From 29df7ad5075c4953902cb310ea0acab71a7d0080 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 22 Jan 2026 20:20:20 +0000
Subject: [PATCH] feat: retain visual test artifacts on failure

- Updated `playwright.config.ts` to use separate projects for 'visual' and 'e2e' tests.
- Configured 'visual' project to retain screenshots, traces, and videos on failure.
- Set Playwright output directory to `artifacts/test-results`.
- Added `scripts/show-artifacts.sh` to help locate test artifacts.
- Updated `KNOWN_ISSUES.md` and `README.md` with debugging instructions.
---
 KNOWN_ISSUES.md           |  1 +
 README.md                 | 12 ++++++++++++
 playwright.config.ts      | 17 ++++++++++++++++-
 scripts/show-artifacts.sh | 12 ++++++++++++
 4 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100755 scripts/show-artifacts.sh

diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md
index 0bc7354c..56b6b338 100644
--- a/KNOWN_ISSUES.md
+++ b/KNOWN_ISSUES.md
@@ -6,6 +6,7 @@
 - `npm run test:unit` consistently times out in the CI environment due to resource constraints. Targeted testing (`test:dm:unit`, `test:dm:integration`) is recommended.
 
 ### Visual Regression Tests (`test:visual`)
+- **Artifact Retention**: Visual tests are configured to retain screenshots, traces, and videos on failure to assist with debugging. These artifacts can be found in `artifacts/test-results/`.
 - **Moderation UI (`tests/visual/moderation.spec.ts`)**: The "Show anyway" button and related moderation badges fail to render in the test environment, causing `toBeVisible()` assertions to fail. The logic for creating the button appears correct (`allowOverride` is true), but the button element is not found in the DOM during the test execution. This might be due to a race condition in the test fixture's state initialization or an environment-specific rendering issue.
 - **Sidebar Layout (`tests/visual/overlay-layers.spec.ts`)**: The `mobile sidebar shares desktop rail behavior` test fails. The expected margin for the app container does not match the computed margin in the test environment (diff of ~45px). Attempts to fix this by adjusting CSS margin calculations were incomplete and reverted to avoid instability.
 - **Kitchen Sink (`tests/visual/kitchen-sink.spec.ts`)**: Minor pixel mismatch (width 1292 vs expected 1280) in snapshot comparison.
diff --git a/README.md b/README.md
index bdab848c..60653f3f 100644
--- a/README.md
+++ b/README.md
@@ -139,6 +139,18 @@ http://localhost:8000
 - **Run DM integration tests**: `npm run test:dm:integration`
 - **Run headless E2E tests**: `npm run test:e2e`
 
+### Visual Regression Debugging
+
+Visual regression tests (`test:visual`) are configured to retain screenshots, videos, and traces when they fail. These artifacts are stored in the `artifacts/test-results` directory.
+
+To quickly view the location of these artifacts:
+
+```bash
+./scripts/show-artifacts.sh
+```
+
+Use these artifacts to inspect the UI state at the moment of failure and diagnose rendering issues or regressions.
+
 ### Send your first video post
 
 Use the event builders in `js/nostrEventSchemas.js` to construct valid video notes.
diff --git a/playwright.config.ts b/playwright.config.ts
index 843b554a..7ccf7d60 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -6,7 +6,7 @@ const BASE_URL = process.env.PLAYWRIGHT_BASE_URL ?? `http://${HOST}:${PORT}`;
 
 export default defineConfig({
   testDir: "./tests",
-  testMatch: ["visual/**/*.spec.ts", "e2e/**/*.spec.ts"],
+  outputDir: "artifacts/test-results",
   timeout: 60_000,
   reporter: process.env.CI
     ? [["github"], ["html", { open: "never" }]]
@@ -16,6 +16,21 @@ export default defineConfig({
     viewport: { width: 1280, height: 720 },
     ignoreHTTPSErrors: true,
   },
+  projects: [
+    {
+      name: "visual",
+      testMatch: "visual/**/*.spec.ts",
+      use: {
+        screenshot: "only-on-failure",
+        trace: "retain-on-failure",
+        video: "retain-on-failure",
+      },
+    },
+    {
+      name: "e2e",
+      testMatch: "e2e/**/*.spec.ts",
+    },
+  ],
   webServer: {
     command: `npx http-server . -p ${PORT} -a ${HOST} -c-1 --silent`,
     url: `${BASE_URL}/docs/kitchen-sink.html`,
diff --git a/scripts/show-artifacts.sh b/scripts/show-artifacts.sh
new file mode 100755
index 00000000..005d3531
--- /dev/null
+++ b/scripts/show-artifacts.sh
@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# script to show artifacts
+ARTIFACTS_DIR="artifacts/test-results"
+
+if [ -d "$ARTIFACTS_DIR" ]; then
+  echo "Artifacts located in $ARTIFACTS_DIR"
+  echo "Listing contents:"
+  ls -F "$ARTIFACTS_DIR"
+else
+  echo "No artifacts found in $ARTIFACTS_DIR"
+fi