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
The rest of this document assumes that you are working in the
The easiest way to set up the development environment is to run the
$ sh bootstrap.sh
The script does following:
- Initializes and updates GIT submodules. The
Foundation Sphinx Theme
./doc/source_/themes/foundation-sphinx-themeis currently the only GIT submodule used.
- Creates a virtual environment
- Installs the development dependencies specified in
- Runs the
tox -r --notestcommand which creates virtual environments
- Creates symbolic links to
./authomaticin each of the
- Prepares the
./doc/build/htmldirectory for deployment of the compiled documentation to Github Pages.
- Removes the
./doc/build/directory if it exists.
- Clones the origin of this repository to
- Creates the gh-pages branch there.
- Sets the GIT HEAD to gh-pages.
- Removes the GIT index.
- Removes everything in the directory with
git claen -fdx.
- Removes the
- Prepares the
- Compiles the documentation with the
./.tox/py27virtual environment activated.
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¶
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
For easy deploiment to Github Pages,
./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
$ cd doc/build/html $ git add -A $ git commit -m "Updated documentation." $ git push origin gh-pages
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
$ 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
You should also add an alias for the IP address of your localhost, because
some providers like Twitter require the
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)$ 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
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
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
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
(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
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.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:
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/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/