Use tox, clean up requirements

.travis.yml

@@ -10,14 +10,10 @@ before_install:
 addons:
   firefox: '42.0'
 install:
-- pip install -r test_requirements.txt
-- pip install -r requirements.txt
-- pip install -r doc_requirements.txt
+- pip install -r requirements/tox.txt
 script:
-- pylint bok_choy
-- pycodestyle bok_choy
-- pycodestyle tests
-- ./run_tests.sh
+- tox -e py27
+- tox -e doc
 after_success:
 - pip install coveralls
 - coveralls

README.rst

@@ -12,6 +12,35 @@ Overview
 A Python framework for writing robust Selenium tests.
 
 
+Installation
+------------
+
+As Bok Choy is a Python framework, you first need to install Python.
+If you’re running Linux or Mac OS X, you probably already have it installed.
+We recommend that you use `pip <http://www.pip-installer.org/>`_ to install your Python
+packages:
+
+.. code-block:: bash
+
+   pip install bok_choy
+
+
+Running Tests
+-------------
+
+To run the test suite for bok-choy itself:
+
+* Install Firefox, `version 46.0.1 <https://ftp.mozilla.org/pub/firefox/releases/46.0.1/>`_
+  or earlier (later versions require a different selenium driver)
+* Install `phantomjs <http://phantomjs.org/download.html>`_
+* Create a virtualenv which uses Python 2.7
+* With that virtualenv activated, run ``pip -r requirements/tox.txt`` to
+  install the `tox <http://tox.testrun.org/>`_ testing tool and its
+  dependencies
+* Run ``tox -e py27``
+* To test and build the documentation, run ``tox -e doc``
+
+
 License
 -------
 

bok_choy/browser.py

@@ -160,12 +160,12 @@ def browser(tags=None, proxy=None):
         then we use a local browser.
 
         * The environment variable `SELENIUM_BROWSER` can be set to
-        specify which local browser to use. The default is Firefox.
+          specify which local browser to use. The default is Firefox.
         * Additionally, if a proxy
-        instance is passed and the browser choice is either Chrome or Firefox, then the browser will
-        be initialized with the proxy server set.
+          instance is passed and the browser choice is either Chrome or Firefox, then the browser will
+          be initialized with the proxy server set.
         * The environment variable `SELENIUM_FIREFOX_PATH` can be used for specifying a path to the
-        Firefox binary. Default behavior is to use the system location.
+          Firefox binary. Default behavior is to use the system location.
 
     2. Remote browser (not SauceLabs): Set all of the following environment variables, but not all of
         the ones needed for SauceLabs:

bok_choy/query.py

@@ -447,7 +447,7 @@ def invisible(self):
 
     def is_focused(self):
         """
-        Checks that _at least one_ matched element is focused. More
+        Checks that *at least one* matched element is focused. More
         specifically, it checks whether the element is document.activeElement.
         If no matching element is focused, this returns `False`.
 

docs/api_reference.rst

@@ -16,11 +16,6 @@ page_object
 .. automodule:: bok_choy.page_object
    :members:
 
-performance
-------------
-.. automodule:: bok_choy.performance
-   :members:
-
 accessibility
 -------------
 

docs/conf.py

@@ -11,7 +11,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -11,6 +11,7 @@ UI-level acceptance test framework.
    guidelines
    accessibility
    visual_diff
+   xss
    api_reference
 
 

requirements/base.txt

@@ -0,0 +1,14 @@
+# Indirect dependencies first
+
+# needle (selenium is also used directly, and nose for tests)
+nose==1.3.7
+Pillow==3.2.0
+selenium==2.53.5
+
+# Then the direct dependencies
+
+# For lazy evaluation of the page object's a11y_audit attribute
+lazy==1.2
+
+# For test assertions involving screenshots and visual diffs
+needle==0.3

requirements/doc.txt

@@ -0,0 +1,33 @@
+# Indirect dependencies first
+
+# babel
+pytz==2016.4
+
+# bleach, html5lib, readme_renderer, Sphinx
+six==1.10.0
+
+# Jinja2
+MarkupSafe==0.23
+
+# readme_renderer, Sphinx
+docutils==0.12
+Pygments==2.1.3
+
+# readme_renderer
+bleach==1.4.3
+html5lib==0.9999999
+
+# Sphinx
+alabaster==0.7.8
+babel==2.3.4
+imagesize==0.7.1
+Jinja2==2.8
+snowballstemmer==1.2.1
+
+# Then the direct dependencies
+
+# For verifying that the README will display correctly on PyPI
+readme_renderer==0.7.0
+
+# Documentation generator
+Sphinx==1.4.4

requirements/test.txt

@@ -0,0 +1,39 @@
+# Indirect dependencies first
+
+# astroid, edx-lint
+six==1.10.0
+
+# astroid
+lazy-object-proxy==1.2.2
+wrapt==1.10.8
+
+# pylint
+colorama==0.3.7
+
+# pylint-plugin-utils
+astroid==1.4.6
+pylint==1.5.4
+
+# pylint-celery, pylint-django
+pylint-plugin-utils
+
+# edx-lint
+pylint-celery==0.3
+pylint-django==0.7.2
+
+# Then the direct dependencies
+
+# For code coverage statistics
+coverage==3.7
+
+# pylint plug-ins for additional code quality checks
+edx_lint==0.5.1
+
+# For mocking functionality in assorted tests
+mock==1.0.1
+
+# Test runner
+nose==1.3.7
+
+# For checking compliance with PEP 8 coding style guidelines
+pycodestyle==2.0.0

requirements/tox.txt

@@ -0,0 +1,10 @@
+# Packages needed in order to run tox.
+# Installed by Travis and dev environments.
+
+# tox dependencies
+pluggy==0.3.1
+py==1.4.31
+virtualenv==15.0.2
+
+# For managing test environments
+tox==2.3.1

run_tests.sh

@@ -14,16 +14,6 @@ function echo_task {
 }
 
 REPO_ROOT=`dirname $BASH_SOURCE`
-SERVER_PORT=8005
-
-export LOG_DIR=$REPO_ROOT/logs
-export SCREENSHOT_DIR=$LOG_DIR
-export SELENIUM_DRIVER_LOG_DIR=$LOG_DIR
-
-# Set up the output logs directory for
-# screenshots and selenium driver logs
-mkdir -p $LOG_DIR
-rm -rf $LOG_DIR/*
 
 # Ensure that the server is shut down on exit
 trap "kill -- -$BASHPID || echo 'no child processes found'" SIGINT SIGTERM EXIT
@@ -35,22 +25,3 @@ echo "Running test server on port $SERVER_PORT"
 
 echo_task "Run unit test suite"
 coverage run -m nose $REPO_ROOT/tests/$1
-
-# Skip other tests if we've specified a particular unit test
-if [ -z $1 ]; then
-
-    echo_task "Coverage report"
-    coverage report
-
-    echo_task "Install bok-choy"
-    pip uninstall bok-choy -y &> /dev/null || true
-    python setup.py install
-
-    echo_task "Run tutorial examples"
-    python docs/code/round_1/test_search.py
-    python docs/code/round_2/test_search.py
-    python docs/code/round_3/test_search.py
-
-    echo_task "Build docs"
-    python setup.py build_sphinx
-fi

setup.py

@@ -1,18 +1,27 @@
 #!/usr/bin/env python
 
+import codecs
 from setuptools import setup
 
 VERSION = '0.5.3'
 DESCRIPTION = 'UI-level acceptance test framework'
-with open('requirements.txt') as f:
-    REQUIREMENTS = f.read().splitlines()
+REQUIREMENTS = (
+    'lazy',
+    'needle',
+    'selenium',
+)
+
+with codecs.open('README.rst', 'r', 'utf-8') as f:
+    LONG_DESCRIPTION = f.read()
 
 setup(
     name='bok_choy',
     version=VERSION,
     author='edX',
+    author_email='[email protected]',
     url='http://github.com/edx/bok-choy',
     description=DESCRIPTION,
+    long_description=LONG_DESCRIPTION,
     license='Apache 2.0',
     classifiers=['Development Status :: 3 - Alpha',
                  'Environment :: Console',

tox.ini

@@ -0,0 +1,43 @@
+[tox]
+envlist = py{27,35,py,py3}
+
+[testenv]
+deps =
+    -r{toxinidir}/requirements/base.txt
+    -r{toxinidir}/requirements/test.txt
+passenv =
+    DISPLAY
+setenv =
+    SCREENSHOT_DIR={toxinidir}/logs
+    SELENIUM_DRIVER_LOG_DIR={toxinidir}/logs
+    SERVER_PORT=8005
+whitelist_externals =
+    mkdir
+    rm
+commands =
+    pip install --quiet --requirement requirements/base.txt
+    pip install --quiet --requirement requirements/test.txt
+    pylint bok_choy
+    pycodestyle bok_choy
+    pycodestyle tests
+    mkdir -p $SELENIUM_DRIVER_LOG_DIR
+    rm -rf $SELENIUM_DRIVER_LOG_DIR/*
+    {toxinidir}/run_tests.sh {posargs}
+    coverage report
+
+[testenv:doc]
+deps =
+    -r{toxinidir}/requirements/base.txt
+    -r{toxinidir}/requirements/test.txt
+    -r{toxinidir}/requirements/doc.txt
+commands =
+    pip install --quiet --requirement requirements/base.txt
+    pip install --quiet --requirement requirements/test.txt
+    pip install --quiet --requirement requirements/doc.txt
+    - pip uninstall bok-choy -y
+    python setup.py install
+    python docs/code/round_1/test_search.py
+    python docs/code/round_2/test_search.py
+    python docs/code/round_3/test_search.py
+    python setup.py build_sphinx
+    python setup.py check --restructuredtext --strict