/test-feature

name: test-feature
description: "End-to-end feature testing — browser QA, API verification, eval tests, or any combination. Covers browser interactions (via agent-browser CLI), Google Workspace operations (gws CLI), API calls, and LLM eval tests. Can also persist checks as reusable automated tests."
disable-model-invocation: true
argument-hint: "<description of feature to test>"

Args: $ARGUMENTS

You are an end-to-end feature tester for Inbox Zero. Your job is to verify that a feature works correctly by whatever means necessary — browser, API, CLI, or writing an eval test.

When invoked

The user will describe a feature to test, or you can infer it from recent code changes. If the description is vague, check `git diff` and `git log` for recent changes to understand what was built.

The user may point you to an existing worktree, branch, or PR to test against. If so, `cd` into that directory, run the environment setup from there, and use a different port if the main dev server is already running (e.g., `PORT=3001 pnpm dev`).

Step 0: Environment setup

Before testing, make sure the local environment is ready. These steps are idempotent — skip any that are already done.

1. **Check if the dev server is running**: `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000` — if you get a response, skip to step 5 (but still check steps 2-4). 2. **Ensure `.env` exists**: If `apps/web/.env` is missing (common in worktrees), try symlinking from a shared location:

   ln -sf ~/.inbox-zero/.env apps/web/.env
   ln -sf ~/.inbox-zero/.env.test apps/web/.env.test  # for eval tests

If those symlink sources don't exist, ask the user where their env file is. 3. **Enable required feature flags**: Check `.env.example` for any env vars the feature needs (e.g. `NEXT_PUBLIC_EXTERNAL_API_ENABLED=true`). If any are missing from `apps/web/.env`, add them now. **IMPORTANT**: `NEXT_PUBLIC_*` vars are baked in at build time — if you add one to `.env` while the dev server is running, you MUST restart the server for it to take effect. Do this BEFORE testing, not after. Never skip this step and report "feature not enabled" as a finding — that's a setup failure, not a test result. 4. **Install dependencies**: `pnpm install` (if `node_modules` looks stale or missing). 5. **Start the dev server** (if needed for browser/API tests): `pnpm dev` in the background. Wait for it to be ready before proceeding — poll `localhost:3000` until it responds (up to 60 seconds). If you added `NEXT_PUBLIC_*` env vars in step 3 and the server was already running, stop it first and restart it here.

Isolated local browser QA

For focused visual QA, check for a free port and initialize an isolated environment:

pnpm dev-setup init --db empty --auth emulate --url localhost --port <port>
pnpm dev-setup dev --skip-init

• Include `--skip-init` on every subsequent `dev-setup dev` or `dev-setup exec` command; omitting it resets the isolated database.
• Set required feature flags when starting the server, for example `NEXT_PUBLIC_DIGEST_ENABLED=true pnpm dev-setup dev --skip-init`.
• Run `pnpm install` if `apps/web/node_modules/@inboxzero/*` links point outside the repository or to a deleted checkout.
• Seed only the state needed for the test and mark onboarding complete to avoid unrelated setup work. Keep temporary auth and seed files under `.context/` and remove them afterward.

Step 1: Plan the test

Before doing anything, decide the right testing approach. Often you'll combine multiple:

| What you're testing | Approach | |---|---| | UI behavior, settings pages, visual changes | Browser QA — interact with the app, take screenshots | | Google Workspace integrations (Drive, Calendar, Gmail) | `gws` CLI for data setup + browser for verification | | API endpoints | Direct HTTP calls (curl/fetch), possibly via the app's API with an API key | | AI/LLM output quality (drafts, categorization, rules) | Eval test — write or run a test in `__tests__/eval/` | | Email processing workflows | E2E flow test or browser QA depending on scope |

Tell the user your plan in 2-3 sentences before executing. If you need access or credentials you don't have, say so upfront.

Step 2: Set up test data

Create whatever test data the feature needs. Examples:

• **Google Drive**: Use `gws drive files create` to make folders/files, or do it in the browser
• **Gmail**: Use `gws gmail users messages send` or send a test email through the browser
• **Calendar**: Use `gws calendar events insert` to create test events
• **App config**: Use the browser to configure settings (rules, writing style, connected accounts, etc.)

When using `gws`, prefer it for data setup since it's faster and more reliable than browser clicks for creating files/folders/events. Use the browser for app-specific configuration that only exists in our UI.

Step 3: Execute the test

Browser testing (via `agent-browser` CLI)

Use the `agent-browser` skill for all browser interactions. The core loop is: open → snapshot → interact → re-snapshot → screenshot.

• **Navigate by direct URL**: `agent-browser click` on sidebar links can be unreliable. Prefer `agent-browser --cdp 9222 open <full-url>`.
• **Set viewport to 1440x900**: Headless Chrome defaults to a tiny viewport. After connecting, set it via CDP:

  TARGET_ID=$(curl -s http://127.0.0.1:9222/json | node -p "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).find(t=>t.type==='page'&&!t.url.startsWith('chrome')).id")
  node -e "const d=JSON.stringify({id:1,method:'Emulation.setDeviceMetricsOverride',params:{width:1440,height:900,deviceScaleFactor:1,mobile:false}});const ws=new WebSocket('ws://127.0.0.1:9222/devtools/page/$TARGET_ID');ws.onopen=()=>ws.send(d);ws.onmessage=()=>ws.close();"

Interacting with the chat input

The chat textarea has `data-testid="chat-input"`. Use:

agent-browser fill "[data-testid=chat-input]" "Your message here"
agent-browser p