qa-setup

name	qa:setup
description	Initialize Sentinel QA testing with Playwright Test Agents integration
argument-hint	[optional: base URL of the application]
user-invocable	true

Initialize Sentinel QA Testing

Set up NL spec-driven QA testing in the current project using Playwright Test Agents.

User Input

$ARGUMENTS

Input Interpretation

Input Pattern	Interpretation
Empty	Prompt for base URL during config generation
http://localhost:3000	Use as the application base URL
https://staging.example.com	Use as the application base URL

Phase 1: Check Prerequisites

Verify Node.js

node --version

If Node.js is not installed, stop and tell the user: "Node.js is required for Sentinel. Install it from https://nodejs.org and try again."

Verify @playwright/test ≥1.56

npx playwright --version

If not installed or version is below 1.56, tell the user: "Install @playwright/test ≥1.56: npm install -D @playwright/test" and stop.

Phase 2: Scaffold Directory Structure

Create the required directories:

mkdir -p specs
mkdir -p tests

The directory layout is:

specs/         <- NL spec files (authored by you, versioned)
tests/         <- generated .spec.ts files (generated by Playwright Planner/Generator)

Phase 3: Generate Configuration

sentinel.config.yaml is the only project-specific source of truth for Sentinel setup. Authoring adapter files for Claude, OpenCode, or other clients are generated boilerplate and must not carry app-specific facts except mechanically templated command paths that cannot be read dynamically at runtime. See @qa (references/authoring-adapters.md) for the full contract.

Use AskUserQuestion to gather configuration values interactively. If $ARGUMENTS contains a URL, use it as the default for the base URL question.

3a. Application Details

Ask the user:

1. Base URL — "What is the base URL of your running application?" (default: value from $ARGUMENTS or http://localhost:3000)
2. Application name — "What is the human-readable name for this application?" (default: derive from the project directory name)

3b. Authentication Strategy

Ask the user:

"How does authentication work in your application?"

• credentials — Login form with username/password
• token — Bearer token set via header or cookie
• cookie — Pre-set session cookie
• none — No authentication required

3c. Credentials Details (if strategy is credentials)

If the user chose credentials, ask:

1. Login URL — "What is the login page path?" (default: /login)
2. Username — "What username/email should be used for QA testing?" (e.g., [e-mail])
3. Password env var — "What environment variable holds the QA password?" (default: SENTINEL_QA_PASSWORD). Remind the user: "Never put actual passwords in config files. Set this env var in your shell before running tests."

3d. Browser Preferences

Ask the user:

1. Headless mode — "Run the browser in headless mode?" (default: true)
2. Viewport size — "What viewport size?" (default: 1280x720)

3e. Bridge Configuration (optional)

If the application uses an HTTP bridge (e.g., Tauri apps tested via bridge shim), ask:

1. Bridge shim path — "Path to the bridge injection script?" (e.g., apps/http-bridge/bridge-inject.js)
2. Bridge port — "What port does the HTTP bridge run on?" (default: 9990)
3. Partitioned execution — "Do you use multiple bridge instances for parallel testing?"

If partitioned, ask for partition configuration:

• Partition names and ports — Map area names to bridge ports (e.g., workspace-pages: 9990, editor-content: 9991)

3f. Authoring Adapters

Ask the user which authoring adapters to scaffold. Use the current agent as the default if it is clear from the environment.

Options:

• claude — Claude Code .mcp.json + .claude/agents/ Playwright Test Agents.
• opencode — OpenCode opencode.json + .opencode/prompts/ Playwright Test Agents.
• grok / factory / codex — Best-effort scaffolding via npx playwright init-agents auto-detection (no native --loop support yet; manual role configuration may be needed).
• none — Only create the tool-agnostic harness; adapters can be generated later.

Record the selected providers in authoring_adapters.providers. These providers are not part of deterministic test execution; they only enable agent-assisted planning, generation, and healing.

3g. Write the Config File

Write sentinel.config.yaml — the full file body is in @qa templates/sentinel-config-template.md (base config, populated bridge example, and per-strategy auth variants). Parameterize it with the gathered values:

• Substitute {base_url}, {app_name}, {strategy}, {headless}, {width}, {height} from the Phase 3 answers.
• If bridge config was gathered in step 3e, uncomment and populate the bridge section — shim_path, port, and (if partitioned) a partitions map of area names to ports — following the template's populated bridge example.
• For the auth section, use the template variant matching the chosen strategy. The credentials variant takes {login_url}, {username}, and {password_env} from step 3c; the token and cookie variants carry env-var guidance comments (SENTINEL_AUTH_TOKEN, SENTINEL_SESSION_COOKIE) and need no substitution.
• List the providers selected in step 3f under authoring_adapters.providers.

Phase 4: Playwright Init Agents

Authoring adapters are generated boilerplate for agent clients. They should:

• Read sentinel.config.yaml before planning, generating, or healing.
• Use app.base_url, auth, playwright.config_path, specs.nl_dir, specs.tests_dir, and specs.seed from the config.
• Avoid hard-coding app names, URLs, login paths, credentials, spec/test directories, or seed paths in prompts.
• Be regenerated by /qa:setup when config paths/providers change rather than manually edited.
• Keep deterministic execution independent: npx playwright test must work without any agent adapter.

Run Playwright Test Agents init to set up the agent scaffolding:

npx playwright init-agents --loop=claude

npx playwright init-agents --loop=opencode

If the project uses a non-root Playwright config, pass the appropriate --config value from playwright.config_path or adjust the generated MCP command mechanically. Keep project facts in sentinel.config.yaml, not in prompt bodies.

npx playwright init-agents

A native --loop=grok option does not currently exist. The command above will attempt to auto-detect the environment. You may need to configure the agents manually or drive the Planner, Generator, and Healer roles directly through the Grok TUI.

npx playwright init-agents

There is currently no official --loop=factory option. The command above will attempt auto-detection. Manual configuration of the agent roles may be required.

npx playwright init-agents

There is currently no official --loop=codex option (Codex relies on its skills + AGENTS.md + MCP integration for Playwright/Test Agents workflows). The command above will attempt auto-detect or manual role configuration. Use Codex skills for Planner/Generator/Healer equivalents where available.

If this command is not available (older Playwright version or the command is not recognized), manually scaffold the agent configuration:

1. Inform the user: "Playwright init-agents not available. Scaffolding manually."
2. Proceed to Phase 5 to generate playwright.config.ts and tests/seed.spec.ts directly.

After running init-agents or manual scaffolding, normalize any generated adapter prompts so they contain only generic Playwright Test Agent role instructions plus a directive to read sentinel.config.yaml. Do not duplicate project paths or credentials in every prompt. It is acceptable for MCP config files to contain mechanically generated command arguments such as --config because those clients cannot dynamically read YAML before starting the MCP server.

Phase 5: Generate playwright.config.ts

Write playwright.config.ts in the project root with bridge shim support and reporter configuration — the full file body is in @qa templates/playwright-config-template.md.

• Substitute {base_url} in the baseURL fallback (the SENTINEL_BASE_URL env var overrides it at runtime).
• If partitioned bridge execution was configured, replace the single chromium project with one project entry per partition — name, baseURL of http://localhost:{partition_port}, and a testMatch glob per area — following the template's partitioned variant.

Phase 6: Create tests/seed.spec.ts

Write tests/seed.spec.ts — a seed spec with project-specific fixtures for auth setup and base URL configuration, plus a seed test verifying the setup works. The full file body is in @qa templates/seed-spec-template.md.

Adapt the authenticatedPage fixture body to the chosen auth strategy (the template ships the none variant). If the auth strategy is credentials, generate a fixture that navigates to the login URL and fills credentials from environment variables.

Phase 7: Write .gitignore

Write .gitignore additions (or create tests/.gitignore):

# Playwright artifacts
test-results/
playwright-report/
blob-report/

# Keep NL specs and generated tests in version control

Phase 8: Generate README.md

Write a README.md in the Sentinel project root as a practical quick-reference for developers. It must cover the 12 sections specified in @qa templates/readme-template.md (quick start, how it works, test partitions, directory structure, fixtures, running specific tests, test statuses, NL spec format, authoring adapters, common workflows, troubleshooting, Sentinel skills).

Tailor the content to the project — use actual port numbers, actual directory paths, and actual fixture names from the generated config. If bridge partitions were not configured, omit the partitions table and simplify to a single bridge instance.

Reference docs/systems/qa-testing-system.md (if it exists) for architecture deep-dive, rather than duplicating it.

Phase 9: Update Project AGENTS.md

Read project AGENTS.md. Append the Sentinel section from @qa templates/agents-sentinel-section.md if not already present (do not duplicate).

Phase 10: Completion

Present completion using @qa templates/setup-complete.md (fill base URL, auth, adapters). Ask: "Would you like to run /qa:discover now to scan your application and generate initial NL specs?"