playwright-skill

Name: playwright-skill
Author: alexei-led

5installs5forks

How to install playwright-skill?

alexei-led/cc-thingz/playwright-skill

$npx -y skills add alexei-led/cc-thingz --skill playwright-skill

Installs into the current project.

Summary

Support-only helper for browser-automation. Provides Playwright primitives: dev-server detection, a script runner (scripts/run.js), screenshot CLIs, and helper utilities (scripts/lib/helpers.js).

Files · 1

View on GitHub

SKILL.md

1	# Playwright Support Runtime
2
3	Support-only helper for `browser-automation`. Provides Playwright primitives:
4	dev-server detection, a script runner (`scripts/run.js`), screenshot CLIs, and
5	helper utilities (`scripts/lib/helpers.js`).
6
7	Do not treat this as the user-facing browser skill. Load it only when
8	`browser-automation` chooses the bundled Playwright helper as the
9	runtime/reference.
10
11	## Critical workflow
12
13	1. Run from this skill directory — the directory containing this `SKILL.md`.
14	If the loaded skill path is different from `~/.pi/agent/skills`, use that
15	loaded path.
16
17	2. Detect dev servers first for localhost testing:
18
19	```bash
20	node scripts/run.js --json "console.log(JSON.stringify(await helpers.detectDevServers()))"
21	```
22
23	One server → use it. Multiple → ask which. None → ask for a URL.
24
25	3. *Use `/tmp/playwright-` for generated scripts and artifacts** unless the
26	user asked for permanent tests. Never write generated scripts or artifacts
27	into `scripts/`, the skill directory, or the user's project.
28
29	4. Prefer headless screenshots in Pi/headless harnesses. Use headed mode
30	only when the platform exposes a usable visible browser.
31
32	5. Parameterize target URLs at the top of generated scripts as `TARGET_URL`.
33
34	## Running scripts
35
36	```bash
37	node scripts/run.js --quiet /tmp/playwright-test-<name>.js
38	node scripts/run.js --json "console.log(JSON.stringify({ ok: !!chromium }))"
39	```
40
41	`run.js` preserves the caller working directory, auto-wraps code for `await`,
42	auto-installs Playwright on first run using bun with npm fallback, and sends
43	runner logs to stderr. Script stdout stays clean for JSON.
44
45	`chromium`, `firefox`, `webkit`, `devices`, `helpers`, and
46	`getContextOptionsWithHeaders(opts)` are exposed as globals for all scripts.
47	Scripts may still use normal imports such as `require("fs")`, `require("path")`,
48	or `require("playwright")`.
49
50	## Turnkey screenshots
51
52	For one page:
53
54	```bash
55	node scripts/screenshot-url.js \
56	--url http://localhost:3030/1?clicks=20 \
57	--selector .slidev-page \
58	--out /tmp/playwright-slide-01.png \
59	--manifest /tmp/playwright-slide-01.json \
60	--json
61	```
62
63	For a sequence:
64
65	```bash
66	node scripts/screenshot-sequence.js \
67	--url-template 'http://localhost:3030/{n}?clicks=20' \
68	--from 1 \
69	--to 17 \
70	--selector .slidev-page \
71	--out-dir /tmp/playwright-slidev \
72	--manifest /tmp/playwright-slidev/manifest.json \
73	--json
74	```
75
76	The manifest includes URL, title, screenshot path, viewport, console errors,
77	network failures, and HTTP responses with status >=400.
78
79	## Helpers
80
81	Open `scripts/lib/helpers.js` when you need helper signatures. Key helpers:
82	`launchBrowser`, `createContext`, `waitForStablePage`, `waitForPageReady`,
83	`safeClick`, `safeType`, `takeScreenshot`, `authenticate`, and
84	`detectDevServers`.
85
86	Use `helpers.waitForStablePage(page, { selector, animationFrames })` before SPA
87	screenshots when `networkidle` is not enough.
88
89	## Custom HTTP headers
90
91	Set env vars before invoking `run.js` or screenshot helpers to inject extra
92	headers into every request:
93
94	```bash
95	# single header
96	PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
97	node scripts/run.js /tmp/script.js
98
99	# multiple
100	PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
101	node scripts/run.js /tmp/script.js
102	```
103
104	Headers apply automatically when scripts use `helpers.createContext(browser)`.
105	For raw `browser.newContext(...)`, wrap options with
106	`getContextOptionsWithHeaders(...)`.
107
108	## Output
109
110	```text
111	URL: <target URL>
112	Actions: <actions run>
113	Artifacts: <paths or none>
114	Failures: <failures or none>
115	```
116
117	Base success claims on script output or artifacts, not on command completion alone.
118
119	## Failure handling
120
121	- `run.js` not found: run from the directory containing this `SKILL.md`, or use
122	the absolute loaded skill path.
123	- Dev server not detected: ask the user for the URL rather than assuming
124	localhost:3000.
125	- Script syntax error: quote the failing line, state the cause, rewrite the
126	offending section — do not re-run the broken script.
127	- Playwright not installed: `run.js` and screenshot helpers auto-install on
128	first run; if that fails, use `references/setup.md`.
129
130	## References
131
132	- [`references/setup.md`](references/setup.md) — first-time install (bun
133	preferred, npm fallback).
134	- [`references/api.md`](references/api.md) — runtime-only patterns and links to
135	official Playwright API docs. Open it when a helper doesn't cover the needed
136	action (custom locators, waits, network interception, or auth patterns).

People who liked this also viewed

6 picks

Type

playwright-skill

5installs5forks

View on GitHub

How to install playwright-skill?

alexei-led/cc-thingz/playwright-skill

$npx -y skills add alexei-led/cc-thingz --skill playwright-skill

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Playwright Support Runtime
2
3	Support-only helper for `browser-automation`. Provides Playwright primitives:
4	dev-server detection, a script runner (`scripts/run.js`), screenshot CLIs, and
5	helper utilities (`scripts/lib/helpers.js`).
6
7	Do not treat this as the user-facing browser skill. Load it only when
8	`browser-automation` chooses the bundled Playwright helper as the
9	runtime/reference.
10
11	## Critical workflow
12
13	1. Run from this skill directory — the directory containing this `SKILL.md`.
14	If the loaded skill path is different from `~/.pi/agent/skills`, use that
15	loaded path.
16
17	2. Detect dev servers first for localhost testing:
18
19	```bash
20	node scripts/run.js --json "console.log(JSON.stringify(await helpers.detectDevServers()))"
21	```
22
23	One server → use it. Multiple → ask which. None → ask for a URL.
24
25	3. *Use `/tmp/playwright-` for generated scripts and artifacts** unless the
26	user asked for permanent tests. Never write generated scripts or artifacts
27	into `scripts/`, the skill directory, or the user's project.
28
29	4. Prefer headless screenshots in Pi/headless harnesses. Use headed mode
30	only when the platform exposes a usable visible browser.
31
32	5. Parameterize target URLs at the top of generated scripts as `TARGET_URL`.
33
34	## Running scripts
35
36	```bash
37	node scripts/run.js --quiet /tmp/playwright-test-<name>.js
38	node scripts/run.js --json "console.log(JSON.stringify({ ok: !!chromium }))"
39	```
40
41	`run.js` preserves the caller working directory, auto-wraps code for `await`,
42	auto-installs Playwright on first run using bun with npm fallback, and sends
43	runner logs to stderr. Script stdout stays clean for JSON.
44
45	`chromium`, `firefox`, `webkit`, `devices`, `helpers`, and
46	`getContextOptionsWithHeaders(opts)` are exposed as globals for all scripts.
47	Scripts may still use normal imports such as `require("fs")`, `require("path")`,
48	or `require("playwright")`.
49
50	## Turnkey screenshots
51
52	For one page:
53
54	```bash
55	node scripts/screenshot-url.js \
56	--url http://localhost:3030/1?clicks=20 \
57	--selector .slidev-page \
58	--out /tmp/playwright-slide-01.png \
59	--manifest /tmp/playwright-slide-01.json \
60	--json
61	```
62
63	For a sequence:
64
65	```bash
66	node scripts/screenshot-sequence.js \
67	--url-template 'http://localhost:3030/{n}?clicks=20' \
68	--from 1 \
69	--to 17 \
70	--selector .slidev-page \
71	--out-dir /tmp/playwright-slidev \
72	--manifest /tmp/playwright-slidev/manifest.json \
73	--json
74	```
75
76	The manifest includes URL, title, screenshot path, viewport, console errors,
77	network failures, and HTTP responses with status >=400.
78
79	## Helpers
80
81	Open `scripts/lib/helpers.js` when you need helper signatures. Key helpers:
82	`launchBrowser`, `createContext`, `waitForStablePage`, `waitForPageReady`,
83	`safeClick`, `safeType`, `takeScreenshot`, `authenticate`, and
84	`detectDevServers`.
85
86	Use `helpers.waitForStablePage(page, { selector, animationFrames })` before SPA
87	screenshots when `networkidle` is not enough.
88
89	## Custom HTTP headers
90
91	Set env vars before invoking `run.js` or screenshot helpers to inject extra
92	headers into every request:
93
94	```bash
95	# single header
96	PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
97	node scripts/run.js /tmp/script.js
98
99	# multiple
100	PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill","X-Debug":"true"}' \
101	node scripts/run.js /tmp/script.js
102	```
103
104	Headers apply automatically when scripts use `helpers.createContext(browser)`.
105	For raw `browser.newContext(...)`, wrap options with
106	`getContextOptionsWithHeaders(...)`.
107
108	## Output
109
110	```text
111	URL: <target URL>
112	Actions: <actions run>
113	Artifacts: <paths or none>
114	Failures: <failures or none>
115	```
116
117	Base success claims on script output or artifacts, not on command completion alone.
118
119	## Failure handling
120
121	- `run.js` not found: run from the directory containing this `SKILL.md`, or use
122	the absolute loaded skill path.
123	- Dev server not detected: ask the user for the URL rather than assuming
124	localhost:3000.
125	- Script syntax error: quote the failing line, state the cause, rewrite the
126	offending section — do not re-run the broken script.
127	- Playwright not installed: `run.js` and screenshot helpers auto-install on
128	first run; if that fails, use `references/setup.md`.
129
130	## References
131
132	- [`references/setup.md`](references/setup.md) — first-time install (bun
133	preferred, npm fallback).
134	- [`references/api.md`](references/api.md) — runtime-only patterns and links to
135	official Playwright API docs. Open it when a helper doesn't cover the needed
136	action (custom locators, waits, network interception, or auth patterns).

People who liked this also viewed

6 picks

Type