This is an automated email from the ASF dual-hosted git repository.
sbp pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tooling-trusted-releases.git
The following commit(s) were added to refs/heads/main by this push:
new 9f8468e Document how to debug e2e test failures
9f8468e is described below
commit 9f8468e8c4fca0d2c17cb2338615740169ee6a63
Author: Sean B. Palmer <[email protected]>
AuthorDate: Mon Jan 19 15:13:21 2026 +0000
Document how to debug e2e test failures
---
atr/docs/running-and-creating-tests.md | 71 ++++++++++++++++++++++++++++++++++
tests/run-e2e.sh | 10 ++++-
2 files changed, 79 insertions(+), 2 deletions(-)
diff --git a/atr/docs/running-and-creating-tests.md
b/atr/docs/running-and-creating-tests.md
index 8d42c67..b365f47 100644
--- a/atr/docs/running-and-creating-tests.md
+++ b/atr/docs/running-and-creating-tests.md
@@ -68,3 +68,74 @@ The actual test cases themselves tend to use helpers such as
[`go_to_path`](/ref
## Running end-to-end tests
To run ATR end-to-end (e2e) tests, you must first have an OCI container
runtime with Compose functionality, such as Docker or Podman, installed. You
will also need a POSIX shell. You can then run `tests/run-e2e.sh` to run the
entire e2e test suite.
+
+### Debugging e2e test failures
+
+When e2e tests fail, the test script will display suggestions for debugging.
You can also use the following techniques:
+
+**View the ATR server logs:**
+
+```shell
+cd tests && docker compose logs atr-dev --tail 100
+```
+
+**View specific log files from the state volume:**
+
+```shell
+# View the Hypercorn logs
+docker compose exec atr-dev cat /opt/atr/state/logs/hypercorn.log
+
+# View the worker logs
+docker compose exec atr-dev cat /opt/atr/state/logs/atr-worker.log
+
+# View the worker error logs
+docker compose exec atr-dev cat /opt/atr/state/logs/atr-worker-error.log
+```
+
+**Enter a shell in an already running ATR e2e container:**
+
+```shell
+cd tests && docker compose exec atr-dev sh
+```
+
+Once in a shell in the running container you can e.g. run `ls -al
/opt/atr/state/logs`.
+
+### Resetting cached state
+
+The e2e tests use a persistent OCI container volume to store ATR state between
runs. If you encounter errors due to stale or corrupted state, you need to
reset this volume.
+
+**Stop containers and remove the state volume:**
+
+```shell
+cd tests && docker compose down -v
+```
+
+The `-v` flag removes the persistent state volume (`atr-dev-state`), which
resets all ATR state including the database, logs, and any uploaded files.
+
+**Force rebuild the container images:**
+
+If you have made changes to `Dockerfile.e2e` or any other dependencies, and
the cached image is stale, run:
+
+```shell
+cd tests && docker compose build --no-cache atr-dev
+```
+
+**Perform a full reset:**
+
+To stop the container, remove the volume, rebuild, and run the tests:
+
+```shell
+cd tests && docker compose down -v
+docker compose build --no-cache atr-dev
+sh tests/run-e2e.sh
+```
+
+**Remove all test containers and images:**
+
+To completely remove all test related containers, volumes, and images:
+
+```shell
+cd tests && docker compose down -v --rmi all
+```
+
+You probably only need to do this if you're running out of disk space.
diff --git a/tests/run-e2e.sh b/tests/run-e2e.sh
index cd0904f..291cfea 100755
--- a/tests/run-e2e.sh
+++ b/tests/run-e2e.sh
@@ -14,12 +14,18 @@ then
then
echo "ERROR: the atr-dev container failed to start or crashed during
startup"
echo "Container logs:"
- docker compose logs atr-dev --tail 50
+ docker compose logs atr-dev --tail 100
exit 1
fi
fi
docker compose build e2e-dev
-docker compose run --rm e2e-dev pytest e2e/ -v
+if ! docker compose run --rm e2e-dev pytest e2e/ -v
+then
+ exit_code=$?
+ echo "ERROR: e2e tests failed with exit code ${exit_code}"
+ echo "View the container logs with 'docker compose logs atr-dev --tail 100'"
+ exit "${exit_code}"
+fi
echo "Use 'docker compose down atr-dev' to stop the dev container"
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
