diff --git a/README.md b/README.md
index 267a741..ebce6c5 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ pipenv run flask run
 
 Interested in learning more? How about a trip to the the `docs/` folder:
 
-- [**Setting up capsul-flask locally**](./docs/local-set-up.md)
+- [**Setting up `capsul-flask` locally**](./docs/local-set-up.md)
   - [Manually](./docs/local-set-up.md#manually)
   - [With docker-compose](./docs/local-set-up.md#docker_compose)
 - [**Configuring `capsul-flask`**](./docs/configuration.md)
@@ -40,6 +40,7 @@ Interested in learning more? How about a trip to the the `docs/` folder:
   - [Database schema management (schema versions)](./docs/database.md#schema_management)
   - [Running manual database queries](./docs/database.md#manual_queries)
 - [**`capsul-flask`'s hub-and-spoke architecture**](./docs/architecture.md)
+- [**Running the automated tests**](./docs/testing.md)
 - [**Deploying capsul-flask on a server**](./docs/deployment.md)
   - [Installing prerequisites for Spoke Mode](./docs/deployment.md#spoke_mode_prerequisites)
   - [Deploying capsul-flask manually](./docs/deployment.md#deploy_manually)
diff --git a/capsulflask/console.py b/capsulflask/console.py
index 5960daf..3375c3b 100644
--- a/capsulflask/console.py
+++ b/capsulflask/console.py
@@ -405,7 +405,7 @@ def account_balance():
 
   vms_billed = list()
 
-  for vm in get_vms():
+  for vm in vms:
     vm_months = get_vm_months_float(vm, datetime.utcnow())
     vms_billed.append(dict(
       id=vm["id"], 
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 0000000..15db636
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,32 @@
+## automated testing 
+
+Automated tests could make it safer to contribute code, easier to review new code, and much easier to refactor, or upgrade Python dependencies.
+
+To run tests: 
+1. create a Postgres database called `capsulflask_test`
+  - e.g.: `docker exec -it d1702306f409 psql -U postgres createdb -O postgres capsulflask_test;`
+    - (`d1702306f409` is the docker container ID of the postgres container)
+2. run `python -m unittest`
+
+### Architecture
+
+I tried to make the absolute minimal changes to be able to override settings in tests – possible alternative approaches include accepting an argument to create_app() to define which env file to load, or adding conditional logic to create_app() to pre-load specific settings before running load_dotenv() – but allowing env vars to override dotenv vars seemed cleanest. (Thanks @forest for improving on this approach)
+
+### Creating test databases
+
+One outstanding question is how to initialise/reinitialise the test database.
+
+Currently, the tests rely on the existence of a capsulflask_test database on localhost, accessible by the postgres user with password dev.
+
+I create this manually using:
+`docker exec -it d1702306f409 psql -U postgres createdb -O postgres capsulflask_test;`
+
+where `d1702306f409` is the docker container ID of the postgres container. 
+
+In between test runs, you can either drop and recreate that database, or manually clear data using:
+
+`docker exec -it d1702306f409 psql -U postgres capsulflask_test -c "DELETE FROM vms; DELETE FROM login_tokens; DELETE FROM ssh_public_keys; DELETE FROM api_tokens; DELETE FROM accounts;`
+
+### Test coverage
+
+This tests the "landing" (public) pages, login, capsul index and creation. I didn't add automated coverage reporting yet, unclear if that seems useful.
\ No newline at end of file