README.md
1# How to test acme-tiny
2
3Testing acme-tiny requires a bit of setup since it interacts with other servers
4(Let's Encrypt's staging server) to test issuing fake certificates. This readme
5explains how to setup and test acme-tiny yourself.
6
7## Setup instructions
8
91. Make a test subdomain for a server you control. Set it as an environmental
10variable on your local test setup.
11 * On your local: `export TRAVIS_DOMAIN=travis-ci.gethttpsforfree.com`
12 * Configure the webserver on `$TRAVIS_DOMAIN` for redirection of
13 `http://$TRAVIS_DOMAIN/.well-known/acme-challenge/` to
14 `http://localhost:8888/`
152. Generate a shared secret between your local test setup and your server.
16 * `openssl rand -base64 32`
17 * On your local: `export TRAVIS_SESSION="<random_string_here>"`
183. Copy and run the test suite mini-server on your server:
19 * `scp server.py ubuntu@travis-ci.gethttpsforfree.com`
20 * `ssh ubuntu@travis-ci.gethttpsforfree.com`
21 * `export TRAVIS_SESSION="<random_string_here>"`
22 * `sudo server.py`
234. Install the test requirements on your local (FUSE and optionally coveralls).
24 * `sudo apt-get install fuse`
25 * `virtualenv /tmp/venv`
26 * `source /tmp/venv/bin/activate`
27 * `pip install -r requirements.txt`
285. Run the test suit on your local.
29 * `cd /path/to/acme-tiny`
30 * `coverage run --source ./ --omit ./tests/server.py,./setup.py -m unittest tests`
31
32## Why use FUSE?
33
34Acme-tiny writes the challenge files for certificate issuance. In order to do
35full integration tests, we actually need to serve correct challenge files to
36the Let's Encrypt staging server on a real domain that they can verify. However,
37Travis-CI doesn't have domains associated with their test VMs, so we need to
38send the files to the remote server that does have a real domain.
39
40The test suite uses FUSE to do this. It creates a FUSE folder that simulates
41being a real folder to acme-tiny. When acme-tiny writes the challenge files
42in the mock folder, FUSE POSTs those files to the real server (which is running
43the included server.py), and the server starts serving them. That way, both
44acme-tiny and Let's Encrypt staging can verify and issue the test certificate.
45This technique allows for high test coverage on automated test runners (e.g.
46Travis-CI).
47
48