From c8ea6736535bc8170eea1d5176d84fc4344ea6f7 Mon Sep 17 00:00:00 2001
From: kolaente <k@knt.li>
Date: Wed, 25 Feb 2026 09:21:01 +0100
Subject: [PATCH] docs: instruct agents to save test output instead of
 re-running tests

Adds guidance to always pipe expensive test commands (e2e, web, feature)
through tee to a log file, so agents can re-read the output for analysis
instead of re-running the full test suite with different grep/tail filters.
---
 AGENTS.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index ba6bffdc3..622cbfc4c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -207,6 +207,19 @@ mage test:e2e "--grep menu"                            # filter by name
 mage test:e2e "--headed tests/e2e/misc/menu.spec.ts"  # headed mode
 ```
 
+**IMPORTANT: Always save test output to a file.** E2E tests are expensive (they rebuild the API, start servers, run browsers, etc.). NEVER re-run tests just to look at the output differently (e.g., with different `grep`/`tail` filters). Instead, save the output on the first run and then read the file:
+
+```bash
+# First run: save output to a file
+mage test:e2e "tests/e2e/misc/menu.spec.ts" 2>&1 | tee /tmp/e2e-output.log
+
+# Subsequent analysis: read the file, don't re-run
+cat /tmp/e2e-output.log | grep -E '(passed|failed)'
+cat /tmp/e2e-output.log | tail -20
+```
+
+This also applies to `mage test:web`, `mage test:feature`, and `mage test:filter`.
+
 Set `VIKUNJA_E2E_SKIP_BUILD=true` to skip rebuilding the API binary when iterating on frontend-only changes.
 
 ## Swagger API Documentation