From a9cef919a8134fde9b21705ddcd0c58d3bb6ba5e 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 22:53:03 +0000
Subject: [PATCH] Add Dockerfile and script for containerized Playwright
 testing

- Add `Dockerfile` based on `mcr.microsoft.com/playwright:v1.57.0-jammy`.
- Add `scripts/run-playwright-docker.sh` to build and run the container with volume mounts.
- Add `.dockerignore` to prevent host `node_modules` from corrupting the build.
- Update `README.md` with usage instructions.
---
 .dockerignore                    |  7 +++++++
 Dockerfile                       | 18 ++++++++++++++++++
 README.md                        | 17 +++++++++++++++++
 scripts/run-playwright-docker.sh | 29 +++++++++++++++++++++++++++++
 4 files changed, 71 insertions(+)
 create mode 100644 .dockerignore
 create mode 100644 Dockerfile
 create mode 100755 scripts/run-playwright-docker.sh

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..b5cc6ace
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,7 @@
+node_modules
+.git
+.gitignore
+artifacts
+Dockerfile
+scripts
+test-results
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 00000000..200a8a90
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,18 @@
+# Base image matching the Playwright version in package.json
+FROM mcr.microsoft.com/playwright:v1.57.0-jammy
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package.json package-lock.json ./
+
+# Install dependencies
+# We use npm ci for a clean, deterministic install
+RUN npm ci
+
+# Copy the rest of the application source code
+COPY . .
+
+# Default command
+CMD ["npm", "run", "test:visual"]
diff --git a/README.md b/README.md
index 60653f3f..12bb8e64 100644
--- a/README.md
+++ b/README.md
@@ -139,6 +139,23 @@ http://localhost:8000
 - **Run DM integration tests**: `npm run test:dm:integration`
 - **Run headless E2E tests**: `npm run test:e2e`
 
+### Running Tests in Docker
+
+To run Playwright tests in a consistent containerized environment, use the provided Docker script:
+
+```bash
+./scripts/run-playwright-docker.sh [command]
+```
+
+- **Default**: Runs `npm run test:visual`.
+- **Custom command**: Pass any command as an argument, e.g., `./scripts/run-playwright-docker.sh npm run test:e2e`.
+
+The script:
+1. Builds the `bitvid-playwright` Docker image (based on `mcr.microsoft.com/playwright`).
+2. Mounts the current directory to `/app` (allowing source changes to be reflected immediately).
+3. Uses an anonymous volume for `/app/node_modules` to preserve the container's Linux-specific dependencies.
+4. Outputs test artifacts to `artifacts/test-results` (accessible on the host).
+
 ### 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.
diff --git a/scripts/run-playwright-docker.sh b/scripts/run-playwright-docker.sh
new file mode 100755
index 00000000..46cbc370
--- /dev/null
+++ b/scripts/run-playwright-docker.sh
@@ -0,0 +1,29 @@
+#!/bin/bash
+set -e
+
+# Build the Docker image
+echo "Building Docker image bitvid-playwright..."
+docker build -t bitvid-playwright .
+
+# Check if arguments are provided, default to "npm run test:visual" if not
+if [ $# -eq 0 ]; then
+    CMD="npm run test:visual"
+else
+    CMD="$@"
+fi
+
+echo "Running: $CMD"
+
+# Run the container
+# - --rm: Remove container after exit
+# - -it: Interactive terminal
+# - --ipc=host: Recommended for Playwright to avoid memory issues
+# - -v $(pwd):/app: Mount current directory to /app for live code updates and artifacts
+# - -v /app/node_modules: Anonymous volume to preserve container's node_modules (prevents host node_modules from overriding)
+# - -w /app: Set working directory
+docker run --rm -it --ipc=host \
+    -v "$(pwd):/app" \
+    -v /app/node_modules \
+    -w /app \
+    bitvid-playwright \
+    $CMD