https://github.com/nicshik/playwright-ui-smoke-kit
Install Playwright Chromium UI smoke checks in web projects
https://github.com/nicshik/playwright-ui-smoke-kit
cli codex e2e-testing github-actions openclaw playwright smoke-tests typescript
Last synced: 4 days ago
JSON representation
Install Playwright Chromium UI smoke checks in web projects
- Host: GitHub
- URL: https://github.com/nicshik/playwright-ui-smoke-kit
- Owner: nicshik
- License: mit
- Created: 2026-05-06T15:16:34.000Z (26 days ago)
- Default Branch: main
- Last Pushed: 2026-05-27T07:57:30.000Z (6 days ago)
- Last Synced: 2026-05-27T08:06:43.340Z (6 days ago)
- Topics: cli, codex, e2e-testing, github-actions, openclaw, playwright, smoke-tests, typescript
- Language: TypeScript
- Size: 92.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# playwright-ui-smoke-kit
[](https://github.com/nicshik/playwright-ui-smoke-kit/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/playwright-ui-smoke-kit)
[](LICENSE)
[](package.json)
Install a small, boring Playwright UI smoke check in a web project.
The kit creates a Chromium-only route smoke test, a Playwright config, a GitHub Actions workflow, and a `smoke:web-ui` package script. It is meant to be the first browser check you add to a project: fast enough for every pull request, simple enough to debug, and explicit enough to copy between teams.
The generated GitHub Actions workflow is cost-aware by default: it cancels stale runs, avoids duplicate branch and pull request runs, skips docs-only changes, and keeps the browser smoke timeout short.
## About
`playwright-ui-smoke-kit` covers two related but separate browser automation layers:
- **Route smoke**: a small Chromium check for stable, non-mutating routes. This is the default CI layer generated by `init`.
- **Browser task artifacts**: a proof workspace for longer browser tasks, with `task.md`, `plan.md`, a reusable final script, logs, screenshots, `result.json`, and `verification.md`.
Use route smoke when you need a fast pull request guard. Use browser task artifacts when you need evidence for a specific workflow, such as a checkout-like path, a visual QA proof, a form-fill automation, or a repeatable data extraction task. A stable artifact can later be promoted into CI, but it should first prove the workflow with concrete evidence.
## Quick Start
```bash
npx playwright-ui-smoke-kit init
```
For non-interactive setup:
```bash
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"
```
Then run:
```bash
npm run smoke:web-ui
```
Use the matching command for your package manager:
```bash
pnpm run smoke:web-ui
yarn smoke:web-ui
bun run smoke:web-ui
```
## What It Generates
```text
playwright.config.ts
tests/ui-smoke.spec.ts
.github/workflows/playwright-ui-smoke.yml
```
It also adds this script:
```json
{
"scripts": {
"smoke:web-ui": "playwright test"
}
}
```
## Before / After
Before:
```text
package.json
```
After:
```text
package.json
playwright.config.ts
tests/ui-smoke.spec.ts
tests/static-server.mjs # static-site only
.github/workflows/playwright-ui-smoke.yml
```
## Templates
- `vite-app`
- `next-app`
- `app-plus-api`
- `static-site`
Every template can be overridden with flags. Routes use the format:
```bash
--route "/dashboard::Dashboard"
--route "/settings::Settings"
```
The generated test opens each route, waits for the visible marker, and fails on `console.error` or uncaught page errors. It does not click buttons or mutate application state.
## Monorepo Usage
Use `--repo-root` for the repository root and `--app-dir` for the app package:
```bash
npx playwright-ui-smoke-kit init \
--yes \
--repo-root . \
--app-dir apps/web \
--template vite-app \
--route "/::Home"
```
This writes the GitHub Actions workflow to the root `.github/workflows` directory and sets `working-directory: apps/web`.
## Maintenance Commands
Check an existing setup:
```bash
npx playwright-ui-smoke-kit doctor
```
Add a new route marker:
```bash
npx playwright-ui-smoke-kit add-route "/dashboard::Dashboard"
```
Create a reusable browser task artifact workspace:
```bash
npx playwright-ui-smoke-kit artifact-init \
--task-id customer-new-task-proof \
--title "Customer new task proof" \
--source "http://127.0.0.1:5173/customer/new-task"
```
Check the artifact before using it as proof:
```bash
npx playwright-ui-smoke-kit artifact-check .tmp/browser-task-artifacts/customer-new-task-proof
npx playwright-ui-smoke-kit artifact-check .tmp/browser-task-artifacts/customer-new-task-proof --strict
```
Run the final script from the latest run directory:
```bash
npx playwright-ui-smoke-kit artifact-run .tmp/browser-task-artifacts/customer-new-task-proof -- --user customer-a
```
Install bundled agent skills:
```bash
npx playwright-ui-smoke-kit install-skill codex
npx playwright-ui-smoke-kit install-skill codex --skill browser-task-artifact
npx playwright-ui-smoke-kit install-skill codex --skill all
npx playwright-ui-smoke-kit install-skill openclaw
npx playwright-ui-smoke-kit install-skill openclaw --skill browser-task-artifact
```
## CLI Options
```text
--repo-root repository root for .github/workflows
--app-dir directory with package.json
--template vite-app | next-app | app-plus-api | static-site
--package-manager npm | pnpm | yarn | bun
--web-command command that starts the web app
--web-port web app port
--api-command optional API command
--api-url optional API health URL
--route repeatable /path::Visible marker route
--script-name package.json script name
--test-dir directory for generated smoke tests
--workflow-name GitHub Actions workflow file name
--base-branch base branch for generated GitHub Actions triggers
--workflow-path repeatable extra GitHub Actions path glob
--workflow-all-changes run the generated workflow for all changed files
--workflow-timeout GitHub Actions job timeout in minutes
--web-env repeatable web server env as KEY=value
--api-env repeatable API server env as KEY=value
--ci github | none
--dry-run print planned changes without writing files
--force overwrite generated files
--yes accept defaults
--skip-install do not install @playwright/test
--skill install-skill only: smoke | browser-task-artifact | all
```
## Browser Task Artifacts
Route smoke tests are intentionally small. For longer browser work, use an artifact workspace: a task plan, a final script, an action log, screenshots, a structured result, and verification notes. This is close to an end-to-end test, but the goal is proof and reuse rather than a permanent CI check.
`artifact-init` creates this structure without starting a browser or touching external sites:
```text
.tmp/browser-task-artifacts//
task.md
plan.md
verification.md
final_runs/run_001/
final_script.ts
action_log.md
result.json
screenshots/
```
`artifact-run` executes the selected run's `final_script.ts`, `final_script.js`, or `final_script.py` from the run directory. Use `--dry-run` to print the resolved command, `--run run_001` to select a run, and `--script final_script.js` when a run contains more than one script.
`artifact-check` validates the structure and `result.json`. `--strict` is for real proof: it requires `status=verified`, a non-placeholder command, non-empty `critical_points` and `evidence_refs`, at least one screenshot, and no `TODO` or `pending` markers in `verification.md`.
Simple examples:
- prove that a multi-step customer flow reaches the expected result and records screenshots for each critical point;
- prove that private/internal fields are absent from a customer-facing page;
- capture visual QA evidence for a mobile viewport before a release;
- turn a manual web lookup or form-fill workflow into a parameterized script.
Use this mode for repeatable browser tasks, extraction or form-fill workflows, visual proof, and task-specific scripts. Keep the generated GitHub Actions route smoke small; promote an artifact into CI only after it is deterministic, safe, fast, and valuable as a regression guard.
See [docs/browser-task-artifacts.md](docs/browser-task-artifacts.md) and the strict verified example in [examples/browser-task-artifacts/static-page-proof](examples/browser-task-artifacts/static-page-proof).
## GitHub Actions Minutes
The generated workflow is designed to avoid common minute leaks:
- `push` and `pull_request` are limited to the base branch, so a feature branch with an open pull request does not run the same browser smoke twice.
- `concurrency.cancel-in-progress` cancels stale runs when a newer commit arrives on the same branch or pull request.
- Root apps use `paths-ignore` for docs-only changes. Monorepos use `paths` for the app directory, workflow file, package files, and any extra `--workflow-path` values.
- The default workflow timeout is 10 minutes. Raise it with `--workflow-timeout` only when the app reliably needs more time.
For monorepos with shared frontend packages, add those packages explicitly:
```bash
npx playwright-ui-smoke-kit init \
--repo-root . \
--app-dir apps/web \
--workflow-path "packages/ui/**" \
--workflow-path "packages/design-system/**"
```
If the workflow must run for every file change, pass `--workflow-all-changes`.
Do not make a path-filtered Playwright workflow the only required branch protection check. If branch protection needs a required check, use a separate always-running gate and keep this browser workflow optional or conditionally triggered.
## Skills
The repository includes installable agent skills:
- Codex: `skills/codex/playwright-smoke-setup`
- Codex: `skills/codex/browser-task-artifact`
- OpenClaw: `skills/openclaw/playwright_ui_smoke_setup`
- OpenClaw: `skills/openclaw/browser_task_artifact`
See [docs/skills.md](docs/skills.md).
## Releasing
Releases are published to npm through Trusted Publishing from GitHub Actions. No `NPM_TOKEN` repository secret is required. Maintainer notes live in [docs/releasing.md](docs/releasing.md).
## Troubleshooting
- **Port is busy**: run `npx playwright-ui-smoke-kit doctor` and either stop the external process or choose another `--web-port`.
- **Marker is not found**: pick visible text that is rendered without interaction and is stable across environments.
- **`console.error` fails the test**: fix the app error or make the app avoid noisy browser errors during smoke routes.
- **Browser is missing**: run `npx playwright install chromium` locally or `npx playwright install --with-deps chromium` in CI.
- **GitHub Actions cache misses**: check `--repo-root`, `--app-dir`, and the generated `cache-dependency-path`.
## Russian Quick Start
Русская инструкция: [docs/ru/quickstart.md](docs/ru/quickstart.md).
## License
MIT