@spfx-fast/playwright 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -10
- package/agent/PLAYWRIGHT.md +3 -3
- package/bin/spfx-fast-playwright.mjs +37 -12
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -14,22 +14,22 @@ npm install --save-dev @spfx-fast/playwright @playwright/test playwright
|
|
|
14
14
|
|
|
15
15
|
SPFx is not a dependency. Production web parts do not import this package by default.
|
|
16
16
|
|
|
17
|
-
Scaffold a serial Playwright setup with a starter recipe, generated test spec, agent instructions
|
|
17
|
+
Scaffold a serial Playwright setup with a starter recipe, generated test spec, and agent instructions:
|
|
18
18
|
|
|
19
19
|
```sh
|
|
20
20
|
npx spfx-fast-playwright init
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
The config uses storage state
|
|
23
|
+
The config uses storage state when `SPFX_STORAGE_STATE` is set. Point it at the shared per-tenant file such as `~/.playwright-auth/workswithagents.json`; keep state out of the project and never commit it. The scaffold adds `SPFX-PLAYWRIGHT.md` and links it from `AGENTS.md` without replacing existing instructions.
|
|
24
24
|
|
|
25
25
|
## Record a test with the Playwright recorder
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
Reuse the Workbench shared state. The command calls Playwright Codegen and writes an ordinary Playwright spec:
|
|
28
28
|
|
|
29
29
|
```sh
|
|
30
30
|
npx spfx-fast-playwright record \
|
|
31
31
|
--url "$SPFX_BASE_URL" \
|
|
32
|
-
--
|
|
32
|
+
--storage-state "$HOME/.playwright-auth/workswithagents.json" \
|
|
33
33
|
--out tests/e2e/home-page.spec.ts
|
|
34
34
|
```
|
|
35
35
|
|
|
@@ -49,7 +49,8 @@ npx spfx-fast-playwright generate tests/e2e/sharepoint-smoke.recipe.json --out t
|
|
|
49
49
|
The output is a normal Playwright Test spec. Run it with the project's `SPFX_BASE_URL` and `storageState`:
|
|
50
50
|
|
|
51
51
|
```sh
|
|
52
|
-
SPFX_BASE_URL="https://tenant.sharepoint.com/sites/your-site"
|
|
52
|
+
SPFX_BASE_URL="https://tenant.sharepoint.com/sites/your-site" \
|
|
53
|
+
SPFX_STORAGE_STATE="$HOME/.playwright-auth/workswithagents.json" npx playwright test
|
|
53
54
|
```
|
|
54
55
|
|
|
55
56
|
Keep state files out of source control. They contain impersonation-capable session data. Use a dedicated least-privilege account and test site.
|
|
@@ -70,9 +71,20 @@ Promote verified findings to the smallest durable artifact: a recipe in `example
|
|
|
70
71
|
|
|
71
72
|
To contribute the browser discovery through the shared knowledge flow, convert and review the draft with `npx --yes @spfx-fast/knowledge learn import-playwright <draft.json>`, then run `learn validate` and `learn patch`. The converter maps fields mechanically; verify the result before sharing.
|
|
72
73
|
|
|
73
|
-
## Run a recipe with
|
|
74
|
+
## Run a recipe with shared storage state
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
npx spfx-fast-playwright run tests/e2e/sharepoint-smoke.recipe.json \
|
|
78
|
+
--base-url "$SPFX_BASE_URL" \
|
|
79
|
+
--storage-state "$HOME/.playwright-auth/workswithagents.json" \
|
|
80
|
+
--artifacts test-results/sharepoint-smoke
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Runs headless and saves requested screenshots, a trace, and `summary.json`. Set `SPFX_STORAGE_STATE` instead of passing `--storage-state` to share the path across commands. State is loaded into a normal browser context and is not rewritten. Use `--headed` to debug.
|
|
74
84
|
|
|
75
|
-
|
|
85
|
+
## Legacy persistent profile mode
|
|
86
|
+
|
|
87
|
+
Existing teams can continue using a signed-in Playwright profile:
|
|
76
88
|
|
|
77
89
|
```sh
|
|
78
90
|
npx spfx-fast-playwright run tests/e2e/sharepoint-smoke.recipe.json \
|
|
@@ -81,7 +93,7 @@ npx spfx-fast-playwright run tests/e2e/sharepoint-smoke.recipe.json \
|
|
|
81
93
|
--artifacts test-results/sharepoint-smoke
|
|
82
94
|
```
|
|
83
95
|
|
|
84
|
-
Runs headless, enforces the origin, and saves requested screenshots, a trace, and `summary.json`. Use `--headed` to debug. The command locks the profile and releases it after browser exit. It does not sign in, inspect cookies, or copy/remove profile files.
|
|
96
|
+
Runs headless, enforces the origin, and saves requested screenshots, a trace, and `summary.json`. Use `--headed` to debug. The command locks the profile and releases it after browser exit. It does not sign in, inspect cookies, or copy/remove profile files. The Workbench IDE workflow uses storage-state JSON instead.
|
|
85
97
|
|
|
86
98
|
Use `--fast` during fix loops: assertions remain, successful screenshots/traces are skipped, and failures capture a screenshot. Run once without it after fixes. Use one job per profile; close any manually opened Chrome first.
|
|
87
99
|
|
|
@@ -118,7 +130,7 @@ cp node_modules/@spfx-fast/playwright/examples/tenant-crud-validation.recipe.jso
|
|
|
118
130
|
npx spfx-fast-playwright validate tests/e2e/tenant-crud-validation.recipe.json
|
|
119
131
|
npx spfx-fast-playwright run tests/e2e/tenant-crud-validation.recipe.json \
|
|
120
132
|
--base-url "$SPFX_BASE_URL" \
|
|
121
|
-
--
|
|
133
|
+
--storage-state "$HOME/.playwright-auth/workswithagents.json" \
|
|
122
134
|
--artifacts test-results/tenant-crud
|
|
123
135
|
```
|
|
124
136
|
|
|
@@ -139,4 +151,4 @@ For a full workflow with profile, SharePoint page, image, and OCR guidance, read
|
|
|
139
151
|
|
|
140
152
|
## Package status
|
|
141
153
|
|
|
142
|
-
This
|
|
154
|
+
This checkout prepares `0.1.3`; published `0.1.2` remains unchanged. It is framework-agnostic across SPFx projects and ships independently from `@spfx-fast/core`.
|
package/agent/PLAYWRIGHT.md
CHANGED
|
@@ -6,12 +6,12 @@ For any SPFx project. This dev tool does not require `@spfx-fast/core`.
|
|
|
6
6
|
|
|
7
7
|
- Reuse the project's Playwright version, config, test account, and site.
|
|
8
8
|
- Set `SPFX_BASE_URL` to the SharePoint **web URL**. Set `SPFX_STORAGE_STATE` only to a local ignored file when that project already uses saved state.
|
|
9
|
-
- Never automate sign-in, inspect cookies,
|
|
10
|
-
-
|
|
9
|
+
- Reuse the shared per-tenant state at `~/.playwright-auth/<tenant>.json` with `--storage-state` or `SPFX_STORAGE_STATE`. Never automate sign-in, inspect cookies, or commit state.
|
|
10
|
+
- Legacy `--profile-dir` mode is supported for existing projects and locks the profile; close manually opened browsers first.
|
|
11
11
|
|
|
12
12
|
## Generate and run
|
|
13
13
|
|
|
14
|
-
- Record with `spfx-fast-playwright record`; review selectors and add user-visible assertions.
|
|
14
|
+
- Record with `spfx-fast-playwright record --url "$SPFX_BASE_URL" --storage-state "$HOME/.playwright-auth/$SPFX_TENANT.json" --out tests/e2e/recorded.spec.ts`; set `SPFX_TENANT` to the tenant key and review selectors and add user-visible assertions.
|
|
15
15
|
- For repeatable checks, validate a JSON recipe, then `generate` or `run` it.
|
|
16
16
|
- Prefer `testId` locators for stable targeting when the app exposes `data-testid`. Use role/label locators when checking accessible interaction, especially for form controls. Use `assertText` to verify user-visible content on the selected element; use text locators only when the text itself is the only useful target. Always use explicit waits; do not use generic `networkidle` on SharePoint.
|
|
17
17
|
- Use `run --fast` during fixes, then run once without it.
|
|
@@ -9,7 +9,7 @@ import { generateTestSource, runRecipe, validateBaseUrl, validateRecipe } from "
|
|
|
9
9
|
import { createLearningDraft, validateLearning } from "../src/learning.js";
|
|
10
10
|
import { acquireProfileLock } from "../src/profile-lock.js";
|
|
11
11
|
|
|
12
|
-
const help = `SPFx Fast Playwright\n\nCommands:\n init [--force] Scaffold config and a smoke recipe\n validate <recipe.json> Validate a recipe\n generate <recipe.json> --out <test.spec.mjs> [--force] Generate a native Playwright test\n learn init [--out <learning.json>] Create a local, anonymous learning draft\n learn validate <learning.json> Validate structure and check for common identifiers\n run <recipe.json> --base-url <url> --profile-dir <dir> [--artifacts <dir>] [--fast] [--headed]\n record --url <url> --profile-dir <dir> --out <test.spec.ts> Start Playwright Codegen\n\nLearning drafts default to test-results/spfx-fast-playwright/ and stay local; no telemetry or upload is performed. Review all evidence manually before sharing.\nRuns are headless by default. --fast skips success screenshots and traces; do one full run after fixes.\n`;
|
|
12
|
+
const help = `SPFx Fast Playwright\n\nCommands:\n init [--force] Scaffold config and a smoke recipe\n validate <recipe.json> Validate a recipe\n generate <recipe.json> --out <test.spec.mjs> [--force] Generate a native Playwright test\n learn init [--out <learning.json>] Create a local, anonymous learning draft\n learn validate <learning.json> Validate structure and check for common identifiers\n run <recipe.json> --base-url <url> (--storage-state <file> | --profile-dir <dir>) [--artifacts <dir>] [--fast] [--headed]\n record --url <url> (--storage-state <file> | --profile-dir <dir>) --out <test.spec.ts> Start Playwright Codegen\n\nLearning drafts default to test-results/spfx-fast-playwright/ and stay local; no telemetry or upload is performed. Review all evidence manually before sharing.\nRuns are headless by default. --fast skips success screenshots and traces; do one full run after fixes.\nSet SPFX_STORAGE_STATE to reuse a storage-state file for run and record.\n`;
|
|
13
13
|
|
|
14
14
|
const parsed = parseArgs({
|
|
15
15
|
args: process.argv.slice(2),
|
|
@@ -19,6 +19,7 @@ const parsed = parseArgs({
|
|
|
19
19
|
out: { type: "string" },
|
|
20
20
|
"base-url": { type: "string" },
|
|
21
21
|
"profile-dir": { type: "string" },
|
|
22
|
+
"storage-state": { type: "string" },
|
|
22
23
|
artifacts: { type: "string" },
|
|
23
24
|
"timeout-ms": { type: "string" },
|
|
24
25
|
url: { type: "string" },
|
|
@@ -83,6 +84,23 @@ async function requireProfileDirectory(value) {
|
|
|
83
84
|
return path;
|
|
84
85
|
}
|
|
85
86
|
|
|
87
|
+
async function requireStorageState(value) {
|
|
88
|
+
if (!value) return undefined;
|
|
89
|
+
const path = resolve(value);
|
|
90
|
+
let metadata;
|
|
91
|
+
try { metadata = await stat(path); } catch { throw new Error("The supplied storage-state file does not exist."); }
|
|
92
|
+
if (!metadata.isFile()) throw new Error("The supplied storage-state path must be a file.");
|
|
93
|
+
return path;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
async function browserAuth() {
|
|
97
|
+
const storageState = await requireStorageState(options["storage-state"] ?? (options["profile-dir"] ? undefined : process.env.SPFX_STORAGE_STATE));
|
|
98
|
+
if (storageState && options["profile-dir"]) throw new Error("Choose either --storage-state or --profile-dir, not both.");
|
|
99
|
+
const profile = options["profile-dir"] ? await requireProfileDirectory(options["profile-dir"]) : undefined;
|
|
100
|
+
if (!storageState && !profile) throw new Error("Supply --storage-state (or set SPFX_STORAGE_STATE) or --profile-dir.");
|
|
101
|
+
return { storageState, profile };
|
|
102
|
+
}
|
|
103
|
+
|
|
86
104
|
async function main() {
|
|
87
105
|
if (options.help || !command || command === "help") {
|
|
88
106
|
console.log(help);
|
|
@@ -103,7 +121,6 @@ async function main() {
|
|
|
103
121
|
["playwright.config.ts", `import { defineConfig } from "@playwright/test";\n\nexport default defineConfig({\n testDir: "./tests/e2e",\n fullyParallel: false,\n workers: 1,\n reporter: [["list"], ["html", { open: "never" }]],\n use: {\n baseURL: process.env.SPFX_BASE_URL,\n storageState: process.env.SPFX_STORAGE_STATE || undefined,\n actionTimeout: 15_000,\n navigationTimeout: 45_000,\n screenshot: "only-on-failure",\n trace: "retain-on-failure",\n viewport: { width: 1440, height: 900 },\n },\n});\n`],
|
|
104
122
|
["tests/e2e/sharepoint-smoke.recipe.json", `${JSON.stringify(smokeRecipe, null, 2)}\n`],
|
|
105
123
|
["tests/e2e/sharepoint-smoke.spec.mjs", generateTestSource(smokeRecipe)],
|
|
106
|
-
["playwright/.auth/.gitignore", "*\n!.gitignore\n"],
|
|
107
124
|
["SPFX-PLAYWRIGHT.md", agentGuide],
|
|
108
125
|
];
|
|
109
126
|
if (!options.force) {
|
|
@@ -127,7 +144,7 @@ async function main() {
|
|
|
127
144
|
const prefix = existingAgents ? `${existingAgents}${existingAgents.endsWith("\n") ? "" : "\n"}\n` : "# Agent instructions\n\n";
|
|
128
145
|
await writeFile(agentsFile, `${prefix}${link}`, "utf8");
|
|
129
146
|
}
|
|
130
|
-
console.log("Created Playwright config, a generated smoke test, agent instructions
|
|
147
|
+
console.log("Created Playwright config, a generated smoke test, and agent instructions.");
|
|
131
148
|
console.log("Set SPFX_BASE_URL to the SharePoint web URL. Keep SPFX_STORAGE_STATE private.");
|
|
132
149
|
return;
|
|
133
150
|
}
|
|
@@ -165,16 +182,17 @@ async function main() {
|
|
|
165
182
|
return;
|
|
166
183
|
}
|
|
167
184
|
if (command === "record") {
|
|
168
|
-
const profile = await
|
|
185
|
+
const { storageState, profile } = await browserAuth();
|
|
169
186
|
const output = await outputPath(options.out);
|
|
170
187
|
if (!/\.spec\.(?:mjs|ts)$/.test(output)) throw new Error("Recorded tests must end in .spec.mjs or .spec.ts.");
|
|
171
188
|
const url = validateBaseUrl(options.url).href;
|
|
172
189
|
const requireFromProject = createRequire(pathToFileURL(resolve("package.json")));
|
|
173
190
|
const playwrightEntry = requireFromProject.resolve("playwright");
|
|
174
191
|
const cli = resolve(dirname(playwrightEntry), "cli.js");
|
|
175
|
-
const releaseProfile = acquireProfileLock(profile);
|
|
192
|
+
const releaseProfile = profile ? acquireProfileLock(profile) : () => {};
|
|
176
193
|
try {
|
|
177
|
-
const
|
|
194
|
+
const authArgs = storageState ? [`--load-storage=${storageState}`] : [`--user-data-dir=${profile}`];
|
|
195
|
+
const result = spawnSync(process.execPath, [cli, "codegen", ...authArgs, `--output=${output}`, "--viewport-size=1440,900", url], { stdio: "inherit" });
|
|
178
196
|
if (result.error) throw new Error("Playwright Codegen could not start. Check that Playwright is installed in this project.");
|
|
179
197
|
if (result.status !== 0) process.exitCode = result.status ?? 1;
|
|
180
198
|
} finally { releaseProfile(); }
|
|
@@ -183,7 +201,7 @@ async function main() {
|
|
|
183
201
|
if (command === "run") {
|
|
184
202
|
const recipe = await readRecipe(recipeFile);
|
|
185
203
|
const base = validateBaseUrl(options["base-url"]);
|
|
186
|
-
const profile = await
|
|
204
|
+
const { storageState, profile } = await browserAuth();
|
|
187
205
|
const artifactRoot = resolve(options.artifacts ?? "test-results/spfx-fast-playwright");
|
|
188
206
|
const timeoutMs = Number(options["timeout-ms"] ?? 15000);
|
|
189
207
|
if (!Number.isInteger(timeoutMs) || timeoutMs < 1) throw new Error("--timeout-ms must be a positive integer.");
|
|
@@ -196,16 +214,22 @@ async function main() {
|
|
|
196
214
|
} catch {}
|
|
197
215
|
await mkdir(artifacts, { recursive: true });
|
|
198
216
|
const { chromium } = await import("playwright");
|
|
199
|
-
const releaseProfile = acquireProfileLock(profile);
|
|
217
|
+
const releaseProfile = profile ? acquireProfileLock(profile) : () => {};
|
|
218
|
+
let browser;
|
|
200
219
|
let context;
|
|
201
220
|
let page;
|
|
202
221
|
let result;
|
|
203
222
|
let error;
|
|
204
223
|
try {
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
224
|
+
if (profile) {
|
|
225
|
+
context = await chromium.launchPersistentContext(profile, {
|
|
226
|
+
headless: options.headed ? false : true,
|
|
227
|
+
viewport: { width: 1440, height: 900 },
|
|
228
|
+
});
|
|
229
|
+
} else {
|
|
230
|
+
browser = await chromium.launch({ headless: !options.headed });
|
|
231
|
+
context = await browser.newContext({ storageState, viewport: { width: 1440, height: 900 } });
|
|
232
|
+
}
|
|
209
233
|
page = context.pages()[0] ?? await context.newPage();
|
|
210
234
|
if (!options.fast) await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
|
|
211
235
|
result = await runRecipe(page, recipe, { baseUrl: base.href, screenshotDir: artifacts, timeoutMs, fast: options.fast });
|
|
@@ -217,6 +241,7 @@ async function main() {
|
|
|
217
241
|
} finally {
|
|
218
242
|
if (context && !options.fast) try { await context.tracing.stop({ path: resolve(artifacts, "trace.zip") }); } catch {}
|
|
219
243
|
await context?.close();
|
|
244
|
+
await browser?.close();
|
|
220
245
|
releaseProfile();
|
|
221
246
|
}
|
|
222
247
|
const report = {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@spfx-fast/playwright",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"author": "Vilius Vystartas",
|
|
5
5
|
"description": "Authenticated, recipe-driven Playwright testing helpers for any SharePoint Framework project.",
|
|
6
6
|
"license": "MIT",
|
|
@@ -19,5 +19,5 @@
|
|
|
19
19
|
"bin": { "spfx-fast-playwright": "bin/spfx-fast-playwright.mjs" },
|
|
20
20
|
"files": ["src", "bin", "README.md", "LICENSE", "examples", "agent"],
|
|
21
21
|
"peerDependencies": { "@playwright/test": ">=1.50.0 <2", "playwright": ">=1.50.0 <2" },
|
|
22
|
-
"keywords": ["spfx", "sharepoint", "playwright", "e2e", "testing", "agents"]
|
|
22
|
+
"keywords": ["spfx", "sharepoint", "playwright", "e2e", "testing", "agents", "agent-skills"]
|
|
23
23
|
}
|