playwright-smoke-setup

name	playwright-smoke-setup
description	Add or maintain Playwright Chromium UI smoke checks in JavaScript/TypeScript web projects. Use when Codex is asked to install Playwright route-smoke tests, generate playwright.config.ts, add GitHub Actions browser checks, or standardize frontend smoke coverage across npm, pnpm, yarn, or bun projects.

Playwright Smoke Setup

Boundary

Use this skill for baseline route-smoke coverage: install Playwright, generate playwright.config.ts, route marker tests, and a small GitHub Actions workflow.

If the user asks for a repeatable browser task, reusable task-specific script, web extraction/form-fill automation, visual proof, screenshots as evidence, or "browser task -> verified artifact", use browser-task-artifact instead. A stable artifact can later be promoted into route smoke or CI, but the artifact workflow should prove the task first.

Workflow

1. Inspect the project before changing files:
   • locate package.json;
   • detect npm, pnpm, yarn, or bun from lock files or packageManager;
   • find the web dev command and port from scripts/configs;
   • identify 1-5 stable non-mutating routes and visible text markers.
2. Prefer the CLI:

npx playwright-ui-smoke-kit init

For monorepos, pass both roots:

npx playwright-ui-smoke-kit init --repo-root . --app-dir apps/web

When a monorepo app depends on shared frontend packages, add those globs so the generated workflow still runs when shared UI code changes:

npx playwright-ui-smoke-kit init \
  --repo-root . \
  --app-dir apps/web \
  --workflow-path "packages/ui/**"

Use non-interactive mode when enough project facts are known:

npx playwright-ui-smoke-kit init \
  --yes \
  --template vite-app \
  --web-command "npm run dev -- --host 127.0.0.1" \
  --web-port 5173 \
  --route "/::Home"

3. Pick the nearest template:
   • next-app for Next.js;
   • app-plus-api when Playwright should start both API and Web App;
   • static-site for static HTML or documentation sites;
   • vite-app for Vite, Astro, SvelteKit, Nuxt, and unknown JavaScript web apps unless project evidence suggests another template.
4. Do not use --force unless the user explicitly asks to replace existing Playwright files.
5. Keep the generated GitHub Actions workflow cost-aware unless the project explicitly needs broader coverage:
   • leave base-branch triggers and concurrency enabled;
   • prefer generated paths or paths-ignore filters;
   • use --workflow-all-changes only when the app depends on broad repository state;
   • do not make a path-filtered browser workflow the only required branch-protection check.
6. Use doctor after installation and add-route for later route additions:

npx playwright-ui-smoke-kit doctor
npx playwright-ui-smoke-kit add-route "/dashboard::Dashboard"

6. Run the generated check with the project package manager.

Skill Installation

Install or update this skill with:

npx playwright-ui-smoke-kit install-skill codex

Install both bundled Codex skills with:

npx playwright-ui-smoke-kit install-skill codex --skill all

Use --dry-run before copying and --force only when replacing an existing local skill.

Manual Fallback

If the CLI cannot be used, create the same surface manually:

playwright.config.ts
tests/ui-smoke.spec.ts
.github/workflows/playwright-ui-smoke.yml

Add:

{
  "scripts": {
    "smoke:web-ui": "playwright test"
  }
}

Install Playwright locally in the project:

npm install -D @playwright/test
npx playwright install chromium

Use equivalent commands for pnpm, yarn, or bun.

Test Standards

• Keep the first layer Chromium-only.
• Route-smoke tests should open pages and assert visible text markers.
• Collect console.error and pageerror.
• Avoid clicks, form submits, payments, deletes, and other state mutations.
• Use Playwright webServer to start required local processes.
• Use trace: "retain-on-failure" and screenshot: "only-on-failure".
• In CI, install browsers with playwright install --with-deps chromium.
• In GitHub Actions, avoid duplicate push and pull_request runs and use concurrency.cancel-in-progress.

Verification

Run at least:

npm run smoke:web-ui

For projects with TypeScript/build checks, run the existing checks too. If long-running servers are started outside Playwright webServer, record and stop them according to the repository's local runtime hygiene rules.