Development¶

Contributions are very welcome. Please read this guide if you want to contribute.

Development Environment Setup¶

Fork the Authomatic repository on Github and clone it:

$ git clone https://github.com/<your-github-id>/authomatic.git
$ cd authomatic

Note

The rest of this document assumes that you are working in the authomatic/ directory.

Although Authomatic has no dependencies except for the optional python-openid package required by the openid.OpenID provider, it has quite a lot of development dependencies.

The easiest way to set up the development environment is to run the ./bootstrap.sh script.

$ sh bootstrap.sh

The script does following:

Initializes and updates GIT submodules. The Foundation Sphinx Theme located in ./doc/source_/themes/foundation-sphinx-theme is currently the only GIT submodule used.
Creates a virtual environment ./e.
Installs the development dependencies specified in ./requirements.txt to the e virtual environment.
Runs the tox -r --notest command which creates virtual environments ./.tox/py26, ./.tox/py27 and ./tox/py34.
Creates symbolic links to ./.tox/py27/lib/python2.7/site-packages/openid and ./authomatic in each of the ./examples/gae/* directories.
Prepares the ./doc/build/html directory for deployment of the compiled documentation to Github Pages.
1. Removes the ./doc/build/ directory if it exists.
2. Clones the origin of this repository to ./doc/build/html.
3. Creates the gh-pages branch there.
4. Sets the GIT HEAD to gh-pages.
5. Removes the GIT index.
6. Removes everything in the directory with git claen -fdx.
Compiles the documentation with the ./.tox/py27 virtual environment activated.

PyOpenSSL Error¶

It is likely, that you will encounter some of following errors during installation of the pyopenssl package:

Missing Python headers Python.h: No such file or directory:

Fix it by installing Python development package e.g:

$ sudo apt-get install python3.4-dev

Missing libffi headers ffi.h: No such file or directory:

Fix it by installing libffi development package e.g:

$ sudo apt-get install libffi-dev

Documentation Compilation and Deployment¶

Warning

Always keep the documentation in sync with the latest code changes.

Compile the documentation with this commands:

$ . ./.tox/py27/bin/activate
(py27)$ cd doc
(py27)$ make html

The documentation will be compiled to ./doc/build/html. For easy deploiment to Github Pages, the ./doc/build/html directory is actually a clone of the origin of the actual project repository that you cloned from (your fork) with the gh-pages branch checked out.

To deploy a compiled documentation to GitHub page go to the ./doc/build/html directory, commit all changes and push to origin gh-pages:

$ cd doc/build/html
$ git add -A
$ git commit -m "Updated documentation."
$ git push origin gh-pages

Testing¶

Tests are written in pytest and Tox is used to run them against Python 2.6, Python 2.7 and Python 3.4.

There are currently only functional (end-to-end) Selenium tests. They are designed to test the login procedure and credentials refreshment and to discover changes in provider APIs.

To run functional tests, you first need to create the ./tests/functional_tests/config.py module by copying and filling out the ./tests/functional_tests/config-template.py template.

$ cd tests/functional_tests
$ cp config-template.py config.py

If you want to run tests for all of the covered providers, you should register an application and a user account by each of them and fill out all possible settings of the user profile. You can exclude providers from the tests by commenting them out of the INCLUDE_PROVIDERS list.

You should also add an alias for the IP address of your localhost, because some providers like Twitter require the callback_uri to match a domain pattern.

$ sudo echo -e "127.0.0.1\tauthomatic.org" >> /etc/hosts
$ cat /etc/hosts
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
127.0.0.1   localhost
127.0.0.1   authomatic.org

Finally launch the tests. If you have set the PORT = 80 in ./tests/functional_tests/config.py (this is needed because some providers like Yahoo don’t support custom ports), then you need to run the tests as sudo:

(e)$ sudo tox

If you want tox to only run tests for let’s say Python 2.6 and Python 3.4 use the -e option:

(e)$ sudo tox -e py26, py34

If something goes wrong, you can examine the py.test logs, at ./tests/pytest-pyXX.log and the provider login logs at ./tests/functional_tests/login-pyXX.log.

You can watch the login logs while the tests are running with the tail -f command. This is useful when debugging the login on Firefox on Linux in an invisible display.

$ tail -f ./tests/functional_tests/login-py*.log

Deployment to Travis CI¶

Install the Travis CI command line client.

(e)$ sudo gem install travis

(e)$ travis login --org

Tweak the Travis CI specific settings in ./tests/functional_tests/config.py, or better leave it as it is.

    # 'vk',  # deprecated for test suite refactoring - consider re-enabling
    # 'windowslive',  # Asks for verification (captcha) in the login form in Travis CI environment.
    # 'yammer',  # deprecated for test suite refactoring - consider re-enabling
    # 'yandex',  # deprecated for test suite refactoring - consider re-enabling

    # OpenID
    # 'openid_livejournal',  # Login and password elements are not visible.
    # 'openid_verisignlabs',  # deprecated for test suite refactoring - consider re-enabling
    # 'openid_wordpress',  # deprecated for test suite refactoring - consider re-enabling
    # 'openid_yahoo',  # deprecated for test suite refactoring - consider re-enabling
]

# Recommended setup for Travis CI environment.
if os.environ.get('TRAVIS'):
    MAX_LOGIN_ATTEMPTS = 20
    WAIT_MULTIPLIER = 2
    MIN_WAIT = 2

Note

LinkedIn and WindowsLive add a captcha to the user login form if the user tries to log in from an unusual location like the Travis CI servers in the US.

Encrypt the config and add it automatically to ./.travis.yml.

(e)$ travis encrypt-file ./tests/functional_tests/config.py ./tests/functional_tests/config.py.enc --add

Commit the encrypted config and updated ./.travis.yml and push it to GitHub.

(e)$ git add ./.travis.yml ./tests/functional_tests/config.py.enc
(e)$ git commit -m 'Updated Travis CI config.'
(e)$ git push

Go to https://travis-ci.org/<your-github-username>/authomatic/builds/ and watch it pass (hopefully). If the tests fail, the ./tests/functional_tests/login-py*.log and the ./tests/pytest-py*.log logs will be displayed at the end of the log so you can get a hang of what went wrong.

Running the Examples¶

If you want to run any of the ./examples/ just copy the example’s config-template.py to config.py, fill it out, activate one of the virtual environments in ./tox/ and run the example the usual way according to its framework.

Example of launching the Simple Django Example with Python 3.4:

$ . ./.tox/py34/bin/activate
(py34)$ cp ./examples/django/example/simple/config-template.py ./examples/django/example/simple/config.py
(py34)$ vim ./examples/django/example/simple/config.py
(py34)$ ./examples/django/example/manage.py runserver

Example of launching the Simple Flask Example with Python 2.6:

$ . ./.tox/py26/bin/activate
(py26)$ cp ./examples/flask/werkzeug_adapter/config-template.py ./examples/flask/werkzeug_adapter/config.py
(py26)$ vim ./examples/flask/werkzeug_adapter/config.py
(py26)$ python ./examples/flask/werkzeug_adapter/main.py

Example of launching the Advanced Webapp2 Google App Engine Example with Python 2.7:

Note

The Google App Engine examples will only work in Python 2.7 The Google App Engine command line tools are installed in the ./tox/py27 virtual environment.

$ . ./.tox/py27/bin/activate
(py27)$ cp ./examples/gae/credentials/config-template.py ./examples/gae/credentials//config.py
(py27)$ vim ./examples/gae/credentials/config.py
(py27)$ dev_appserver ./examples/gae/credentials/