1. Documentation
2. Testing

Testing

We don't require authentication to use our production API endpoints, so you are welcome to develop and test against our real API. However, if you're running a bunch of continuous integration tests (Jenkins, Travis CI, etc.), you'll likely hit our rate limits quickly.

NOTE: If you want to setup a development environment and run tests for the ballotapi code itself, check out our contributing docs.

Option 1: Use Our Test Domains

To make your lives easier, we have setup several testing domains with a small subset of data from our ballot database that have more test-friendly rate limits. That way, you can still run automated tests against them without constantly hitting our production rate limits.

• api-test.ballotapi.org

  • Description: This API domain only has a small subset of our real database (specifically, it only has ballot data for Treasure Island). However, it has much higher rate limits, so you can run most automated tests against it.
  • Example: https://api-test.ballotapi.org/v1/elections
  • Rate limit: 1000 requests per minute per IP address. What's this?
  • Queue limit: 100 requests per IP address. What's this?

• api-test-ratelimited.ballotapi.org

  • Description: This API domain has the same subset of data as api-test.ballotapi.org, but rate limits are set very low. You typically want to use this domain to test your rate limit handling logic.
  • Example: https://api-test-ratelimited.ballotapi.org/v1/elections
  • Rate limit: 1 requests per second per IP address. What's this?
  • Queue limit: 0 requests per IP address. What's this?

Option 2: Run Your Own Test Server

If you want to run your tests completely internally, you are welcome to spin up your own test server. Below are the steps to quickly spin up an equivalent of api-test.ballotapi.org on your own system.

• Debian/Ubuntu Linux setup:

  1. Install prerequisites:
     sudo apt-get install python postgresql postgis
  2. Create a test user and database:
     sudo -u postgres psql -c "CREATE USER bapiuser WITH ENCRYPTED PASSWORD 'hunter2';"
sudo -u postgres psql -c "CREATE DATABASE bapidb;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE bapidb TO bapiuser;"
  3. Download our repo:
     wget https://code.ballotapi.org/ballotapi/releases/ballotapi-latest.tar.gz
tar -xzvf ballotapi-latest.tar.gz
rm ballotapi-latest.tar.gz
  4. Run the test server:
     cd ballotapi/api
python server.py --load "testdata" --dbname "bapidb" --dbuser "bapiuser" --dbpass "hunter2"
  5. Try it out:
     http://localhost:8000/v1/elections

• Mac setup:

  1. Install PostgreSQL and PostGIS:
     brew install postgres
brew install postgis
  2. Create a test user and database:
     sudo -u postgres psql -c "CREATE USER bapiuser WITH ENCRYPTED PASSWORD 'hunter2';"
sudo -u postgres psql -c "CREATE DATABASE bapidb;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE bapidb TO bapiuser;"
  3. Download and unzip the repo:
     https://code.ballotapi.org/ballotapi/releases/ballotapi-latest.zip
  4. Run the test server in your Terminal:
     cd ~/Downloads/ballotapi/api (or wherever you unzipped the archive)
     python server.py --load "testdata" --dbname "bapidb" --dbuser "bapiuser" --dbpass "hunter2"
  5. Try it out:
     http://localhost:8000/v1/elections

• Windows setup:

  1. Install python:
     https://www.python.org/downloads/windows/
  2. Install PostgreSQL:
     https://www.postgresql.org/download/windows/
  3. Install PostGIS:
     https://postgis.net/windows_downloads/
  4. Create a test user and database:
     psql.exe -c "CREATE USER bapiuser WITH ENCRYPTED PASSWORD 'hunter2';"
psql.exe -c "CREATE DATABASE bapidb;"
psql.exe -c "GRANT ALL PRIVILEGES ON DATABASE bapidb TO bapiuser;"
  5. Download and unzip the repo:
     https://code.ballotapi.org/ballotapi/releases/ballotapi-latest.zip
  6. Run the test server in your command line:
     cd Downloads\ballotapi\api (or wherever you unzipped the archive)
     python.exe server.py --load "testdata" --dbname "bapidb" --dbuser "bapiuser" --dbpass "hunter2"
  7. Try it out:
     http://localhost:8000/v1/elections

Updating your test server

If you want to update your existing installation, simply download our repo again (see "Download and unzip the repo..." steps above) and run the same command (python server.py --load ...). It will automatically clear and reload the testdata dataset into the database.

Are these setup instructions incorrect? Help us out by opening an issue or pull request