@spfx-fast/playwright 0.1.1 → 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 +40 -10
- package/agent/PLAYWRIGHT.md +4 -3
- package/bin/spfx-fast-playwright.mjs +79 -12
- package/package.json +2 -2
- package/src/learning.js +110 -0
package/README.md
CHANGED
|
@@ -4,6 +4,8 @@ Playwright helpers for any SPFx project. This dev tool stays out of the web-part
|
|
|
4
4
|
|
|
5
5
|
It adds agent-friendly recipes, same-origin navigation, and authenticated runs with reviewable evidence. Playwright provides the test runner, locators, recorder, traces, and screenshots.
|
|
6
6
|
|
|
7
|
+
When [`@spfx-fast/ide`](https://www.npmjs.com/package/@spfx-fast/ide) is installed, `spfx-ide e2e` routes to this package's CLI. The router does not install the optional Playwright peers or browser runtime; follow the install and browser setup below before running E2E.
|
|
8
|
+
|
|
7
9
|
## Install in an SPFx project
|
|
8
10
|
|
|
9
11
|
```sh
|
|
@@ -12,22 +14,22 @@ npm install --save-dev @spfx-fast/playwright @playwright/test playwright
|
|
|
12
14
|
|
|
13
15
|
SPFx is not a dependency. Production web parts do not import this package by default.
|
|
14
16
|
|
|
15
|
-
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:
|
|
16
18
|
|
|
17
19
|
```sh
|
|
18
20
|
npx spfx-fast-playwright init
|
|
19
21
|
```
|
|
20
22
|
|
|
21
|
-
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.
|
|
22
24
|
|
|
23
25
|
## Record a test with the Playwright recorder
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
Reuse the Workbench shared state. The command calls Playwright Codegen and writes an ordinary Playwright spec:
|
|
26
28
|
|
|
27
29
|
```sh
|
|
28
30
|
npx spfx-fast-playwright record \
|
|
29
31
|
--url "$SPFX_BASE_URL" \
|
|
30
|
-
--
|
|
32
|
+
--storage-state "$HOME/.playwright-auth/workswithagents.json" \
|
|
31
33
|
--out tests/e2e/home-page.spec.ts
|
|
32
34
|
```
|
|
33
35
|
|
|
@@ -47,14 +49,42 @@ npx spfx-fast-playwright generate tests/e2e/sharepoint-smoke.recipe.json --out t
|
|
|
47
49
|
The output is a normal Playwright Test spec. Run it with the project's `SPFX_BASE_URL` and `storageState`:
|
|
48
50
|
|
|
49
51
|
```sh
|
|
50
|
-
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
|
|
51
54
|
```
|
|
52
55
|
|
|
53
56
|
Keep state files out of source control. They contain impersonation-capable session data. Use a dedicated least-privilege account and test site.
|
|
54
57
|
|
|
55
|
-
##
|
|
58
|
+
## Capture and contribute a SharePoint UI discovery
|
|
59
|
+
|
|
60
|
+
Capture a reusable finding and runnable recipe as a local draft:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
npx spfx-fast-playwright learn init
|
|
64
|
+
# Edit test-results/spfx-fast-playwright/learning-draft.json.
|
|
65
|
+
npx spfx-fast-playwright learn validate test-results/spfx-fast-playwright/learning-draft.json
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
The default stays with Playwright artifacts under `test-results/`; `learn init` adds that file to `.gitignore` when the directory is not already ignored. The strict format has no author or tenant fields. Validation rejects common emails, GUIDs, tenant domains, site-specific paths, and credential-like strings; it does not upload anything. It cannot guarantee anonymity, detect every identifier, or inspect screenshots and other attachments. Keep drafts local until you have reviewed all values and evidence. Never include tenant URLs, IDs, user names, list content, browser profiles, auth state, screenshots, or traces in a shared learning.
|
|
69
|
+
|
|
70
|
+
Promote verified findings to the smallest durable artifact: a recipe in `examples/`, a pattern in the agent guide, or an API/scenario note in core docs. Record applicability and validation limits; do not present tenant-specific behavior as universal. The [learning index](https://github.com/vystartasv/spfx-fast/blob/main/docs/LEARNINGS.md) points agents to existing guidance.
|
|
56
71
|
|
|
57
|
-
|
|
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.
|
|
73
|
+
|
|
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.
|
|
84
|
+
|
|
85
|
+
## Legacy persistent profile mode
|
|
86
|
+
|
|
87
|
+
Existing teams can continue using a signed-in Playwright profile:
|
|
58
88
|
|
|
59
89
|
```sh
|
|
60
90
|
npx spfx-fast-playwright run tests/e2e/sharepoint-smoke.recipe.json \
|
|
@@ -63,7 +93,7 @@ npx spfx-fast-playwright run tests/e2e/sharepoint-smoke.recipe.json \
|
|
|
63
93
|
--artifacts test-results/sharepoint-smoke
|
|
64
94
|
```
|
|
65
95
|
|
|
66
|
-
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.
|
|
67
97
|
|
|
68
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.
|
|
69
99
|
|
|
@@ -100,7 +130,7 @@ cp node_modules/@spfx-fast/playwright/examples/tenant-crud-validation.recipe.jso
|
|
|
100
130
|
npx spfx-fast-playwright validate tests/e2e/tenant-crud-validation.recipe.json
|
|
101
131
|
npx spfx-fast-playwright run tests/e2e/tenant-crud-validation.recipe.json \
|
|
102
132
|
--base-url "$SPFX_BASE_URL" \
|
|
103
|
-
--
|
|
133
|
+
--storage-state "$HOME/.playwright-auth/workswithagents.json" \
|
|
104
134
|
--artifacts test-results/tenant-crud
|
|
105
135
|
```
|
|
106
136
|
|
|
@@ -121,4 +151,4 @@ For a full workflow with profile, SharePoint page, image, and OCR guidance, read
|
|
|
121
151
|
|
|
122
152
|
## Package status
|
|
123
153
|
|
|
124
|
-
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.
|
|
@@ -29,4 +29,5 @@ For any SPFx project. This dev tool does not require `@spfx-fast/core`.
|
|
|
29
29
|
- Screenshots show appearance only. Assert API or saved/published state separately.
|
|
30
30
|
- After three failed attempts to reach a control, stop and report the blocker with evidence.
|
|
31
31
|
- Check artifacts for tenant/personal data before sharing.
|
|
32
|
+
- When a task reveals a reusable UI behavior, capture it with `learn init`, validate it with `learn validate`, and recommend a recipe or guide change. Drafts stay local; validation catches common identifiers but cannot guarantee anonymity. Never attach screenshots, traces, profiles, or tenant data to a shared learning.
|
|
32
33
|
- For image overviews, OCR, PDF text, and screenshot diagnostics, see [the browser, image, and OCR workflow](../../../docs/AGENT-BROWSER-WORKFLOW.md). OCR does not prove visual layout or complete text capture.
|
|
@@ -6,9 +6,10 @@ import { createRequire } from "node:module";
|
|
|
6
6
|
import { pathToFileURL } from "node:url";
|
|
7
7
|
import { parseArgs } from "node:util";
|
|
8
8
|
import { generateTestSource, runRecipe, validateBaseUrl, validateRecipe } from "../src/index.js";
|
|
9
|
+
import { createLearningDraft, validateLearning } from "../src/learning.js";
|
|
9
10
|
import { acquireProfileLock } from "../src/profile-lock.js";
|
|
10
11
|
|
|
11
|
-
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 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\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`;
|
|
12
13
|
|
|
13
14
|
const parsed = parseArgs({
|
|
14
15
|
args: process.argv.slice(2),
|
|
@@ -18,6 +19,7 @@ const parsed = parseArgs({
|
|
|
18
19
|
out: { type: "string" },
|
|
19
20
|
"base-url": { type: "string" },
|
|
20
21
|
"profile-dir": { type: "string" },
|
|
22
|
+
"storage-state": { type: "string" },
|
|
21
23
|
artifacts: { type: "string" },
|
|
22
24
|
"timeout-ms": { type: "string" },
|
|
23
25
|
url: { type: "string" },
|
|
@@ -41,6 +43,15 @@ async function readRecipe(file) {
|
|
|
41
43
|
}
|
|
42
44
|
}
|
|
43
45
|
|
|
46
|
+
async function readLearning(file) {
|
|
47
|
+
if (!file) throw new Error("Supply a learning JSON file.");
|
|
48
|
+
try { return validateLearning(JSON.parse(await readFile(resolve(file), "utf8"))); }
|
|
49
|
+
catch (error) {
|
|
50
|
+
if (error instanceof TypeError) throw error;
|
|
51
|
+
throw new Error("Could not read a valid learning JSON file.");
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
44
55
|
async function outputPath(file) {
|
|
45
56
|
if (!file) throw new Error("Supply --out.");
|
|
46
57
|
const target = resolve(file);
|
|
@@ -52,6 +63,18 @@ async function outputPath(file) {
|
|
|
52
63
|
return target;
|
|
53
64
|
}
|
|
54
65
|
|
|
66
|
+
async function ignoreLearningDraft() {
|
|
67
|
+
const file = resolve(".gitignore");
|
|
68
|
+
let existing = "";
|
|
69
|
+
try { existing = await readFile(file, "utf8"); }
|
|
70
|
+
catch (error) { if (error.code !== "ENOENT") throw error; }
|
|
71
|
+
const entry = "/test-results/spfx-fast-playwright/learning-draft.json";
|
|
72
|
+
const ignored = existing.split(/\r?\n/);
|
|
73
|
+
if (ignored.includes(entry) || ignored.includes("/test-results/") || ignored.includes("test-results/")) return false;
|
|
74
|
+
await writeFile(file, `${existing}${existing && !existing.endsWith("\n") ? "\n" : ""}${entry}\n`, "utf8");
|
|
75
|
+
return true;
|
|
76
|
+
}
|
|
77
|
+
|
|
55
78
|
async function requireProfileDirectory(value) {
|
|
56
79
|
if (!value) throw new Error("Supply an existing --profile-dir. The command will not create or copy a signed-in profile.");
|
|
57
80
|
const path = resolve(value);
|
|
@@ -61,6 +84,23 @@ async function requireProfileDirectory(value) {
|
|
|
61
84
|
return path;
|
|
62
85
|
}
|
|
63
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
|
+
|
|
64
104
|
async function main() {
|
|
65
105
|
if (options.help || !command || command === "help") {
|
|
66
106
|
console.log(help);
|
|
@@ -81,7 +121,6 @@ async function main() {
|
|
|
81
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`],
|
|
82
122
|
["tests/e2e/sharepoint-smoke.recipe.json", `${JSON.stringify(smokeRecipe, null, 2)}\n`],
|
|
83
123
|
["tests/e2e/sharepoint-smoke.spec.mjs", generateTestSource(smokeRecipe)],
|
|
84
|
-
["playwright/.auth/.gitignore", "*\n!.gitignore\n"],
|
|
85
124
|
["SPFX-PLAYWRIGHT.md", agentGuide],
|
|
86
125
|
];
|
|
87
126
|
if (!options.force) {
|
|
@@ -105,7 +144,7 @@ async function main() {
|
|
|
105
144
|
const prefix = existingAgents ? `${existingAgents}${existingAgents.endsWith("\n") ? "" : "\n"}\n` : "# Agent instructions\n\n";
|
|
106
145
|
await writeFile(agentsFile, `${prefix}${link}`, "utf8");
|
|
107
146
|
}
|
|
108
|
-
console.log("Created Playwright config, a generated smoke test, agent instructions
|
|
147
|
+
console.log("Created Playwright config, a generated smoke test, and agent instructions.");
|
|
109
148
|
console.log("Set SPFX_BASE_URL to the SharePoint web URL. Keep SPFX_STORAGE_STATE private.");
|
|
110
149
|
return;
|
|
111
150
|
}
|
|
@@ -114,6 +153,26 @@ async function main() {
|
|
|
114
153
|
console.log(`Recipe valid: ${recipe.name} (${recipe.steps.length} steps).`);
|
|
115
154
|
return;
|
|
116
155
|
}
|
|
156
|
+
if (command === "learn") {
|
|
157
|
+
const action = recipeFile;
|
|
158
|
+
const file = parsed.positionals[2];
|
|
159
|
+
if (action === "init") {
|
|
160
|
+
const isDefault = !options.out && !file;
|
|
161
|
+
const target = await outputPath(options.out ?? file ?? "test-results/spfx-fast-playwright/learning-draft.json");
|
|
162
|
+
if (isDefault && await ignoreLearningDraft()) console.log("Added the default draft path to .gitignore.");
|
|
163
|
+
await writeFile(target, `${JSON.stringify(createLearningDraft(), null, 2)}\n`, "utf8");
|
|
164
|
+
console.log(`Created local learning draft: ${target}`);
|
|
165
|
+
console.log("The draft contains no author or tenant fields. Edit it, validate it, then review it manually before sharing.");
|
|
166
|
+
return;
|
|
167
|
+
}
|
|
168
|
+
if (action === "validate") {
|
|
169
|
+
const learning = await readLearning(file ?? options.out);
|
|
170
|
+
console.log(`Learning valid: ${learning.title} (${learning.topic}, ${learning.validation.level}).`);
|
|
171
|
+
console.log("No upload occurred. Validation catches common identifiers; it cannot prove a draft is anonymous. Review every value and attached artifact.");
|
|
172
|
+
return;
|
|
173
|
+
}
|
|
174
|
+
throw new Error("Usage: spfx-fast-playwright learn <init [--out <file>] | validate <file>>");
|
|
175
|
+
}
|
|
117
176
|
if (command === "generate") {
|
|
118
177
|
const recipe = await readRecipe(recipeFile);
|
|
119
178
|
const target = await outputPath(options.out);
|
|
@@ -123,16 +182,17 @@ async function main() {
|
|
|
123
182
|
return;
|
|
124
183
|
}
|
|
125
184
|
if (command === "record") {
|
|
126
|
-
const profile = await
|
|
185
|
+
const { storageState, profile } = await browserAuth();
|
|
127
186
|
const output = await outputPath(options.out);
|
|
128
187
|
if (!/\.spec\.(?:mjs|ts)$/.test(output)) throw new Error("Recorded tests must end in .spec.mjs or .spec.ts.");
|
|
129
188
|
const url = validateBaseUrl(options.url).href;
|
|
130
189
|
const requireFromProject = createRequire(pathToFileURL(resolve("package.json")));
|
|
131
190
|
const playwrightEntry = requireFromProject.resolve("playwright");
|
|
132
191
|
const cli = resolve(dirname(playwrightEntry), "cli.js");
|
|
133
|
-
const releaseProfile = acquireProfileLock(profile);
|
|
192
|
+
const releaseProfile = profile ? acquireProfileLock(profile) : () => {};
|
|
134
193
|
try {
|
|
135
|
-
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" });
|
|
136
196
|
if (result.error) throw new Error("Playwright Codegen could not start. Check that Playwright is installed in this project.");
|
|
137
197
|
if (result.status !== 0) process.exitCode = result.status ?? 1;
|
|
138
198
|
} finally { releaseProfile(); }
|
|
@@ -141,7 +201,7 @@ async function main() {
|
|
|
141
201
|
if (command === "run") {
|
|
142
202
|
const recipe = await readRecipe(recipeFile);
|
|
143
203
|
const base = validateBaseUrl(options["base-url"]);
|
|
144
|
-
const profile = await
|
|
204
|
+
const { storageState, profile } = await browserAuth();
|
|
145
205
|
const artifactRoot = resolve(options.artifacts ?? "test-results/spfx-fast-playwright");
|
|
146
206
|
const timeoutMs = Number(options["timeout-ms"] ?? 15000);
|
|
147
207
|
if (!Number.isInteger(timeoutMs) || timeoutMs < 1) throw new Error("--timeout-ms must be a positive integer.");
|
|
@@ -154,16 +214,22 @@ async function main() {
|
|
|
154
214
|
} catch {}
|
|
155
215
|
await mkdir(artifacts, { recursive: true });
|
|
156
216
|
const { chromium } = await import("playwright");
|
|
157
|
-
const releaseProfile = acquireProfileLock(profile);
|
|
217
|
+
const releaseProfile = profile ? acquireProfileLock(profile) : () => {};
|
|
218
|
+
let browser;
|
|
158
219
|
let context;
|
|
159
220
|
let page;
|
|
160
221
|
let result;
|
|
161
222
|
let error;
|
|
162
223
|
try {
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
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
|
+
}
|
|
167
233
|
page = context.pages()[0] ?? await context.newPage();
|
|
168
234
|
if (!options.fast) await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
|
|
169
235
|
result = await runRecipe(page, recipe, { baseUrl: base.href, screenshotDir: artifacts, timeoutMs, fast: options.fast });
|
|
@@ -175,6 +241,7 @@ async function main() {
|
|
|
175
241
|
} finally {
|
|
176
242
|
if (context && !options.fast) try { await context.tracing.stop({ path: resolve(artifacts, "trace.zip") }); } catch {}
|
|
177
243
|
await context?.close();
|
|
244
|
+
await browser?.close();
|
|
178
245
|
releaseProfile();
|
|
179
246
|
}
|
|
180
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
|
}
|
package/src/learning.js
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { validateRecipe } from "./index.js";
|
|
2
|
+
|
|
3
|
+
const fields = {
|
|
4
|
+
root: ["format", "version", "title", "topic", "appliesTo", "problem", "finding", "reproduction", "recommendation", "limitations", "validation", "recipe"],
|
|
5
|
+
appliesTo: ["service", "surface", "spfxVersion", "browser"],
|
|
6
|
+
validation: ["level", "checkedOn", "sampleSize"],
|
|
7
|
+
};
|
|
8
|
+
const topics = new Set(["ui", "accessibility", "navigation", "deployment", "permissions", "data", "performance", "other"]);
|
|
9
|
+
const levels = new Set(["unverified", "reproduced", "tenant-validated", "documented"]);
|
|
10
|
+
|
|
11
|
+
function rejectUnknownKeys(value, allowed, path) {
|
|
12
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${path} must be an object.`);
|
|
13
|
+
for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new TypeError(`${path}.${key} is not a supported field.`);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export function createLearningDraft() {
|
|
17
|
+
return {
|
|
18
|
+
format: "spfx-fast-learning",
|
|
19
|
+
version: 1,
|
|
20
|
+
title: "Describe the reusable SharePoint discovery",
|
|
21
|
+
topic: "ui",
|
|
22
|
+
appliesTo: { service: "SharePoint Online", surface: "SPFx web part", spfxVersion: "1.24+", browser: "Chromium" },
|
|
23
|
+
problem: "What was difficult to discover?",
|
|
24
|
+
finding: "What behavior or reliable pattern did you observe?",
|
|
25
|
+
reproduction: ["Describe the setup and steps without tenant-specific details."],
|
|
26
|
+
recommendation: "What should another agent or developer do?",
|
|
27
|
+
limitations: "State what has not been verified and where this may not apply.",
|
|
28
|
+
validation: { level: "unverified" },
|
|
29
|
+
recipe: {
|
|
30
|
+
name: "Replace with a focused, reusable UI check",
|
|
31
|
+
steps: [
|
|
32
|
+
{ action: "navigate", path: "/sites/your-site" },
|
|
33
|
+
{ action: "assertPageReady" },
|
|
34
|
+
{ action: "assertAuthenticated" },
|
|
35
|
+
],
|
|
36
|
+
},
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function checkKeys(value, allowed, path) {
|
|
41
|
+
rejectUnknownKeys(value, allowed, path);
|
|
42
|
+
for (const key of allowed) {
|
|
43
|
+
if (!Object.hasOwn(value, key) && !(path === "validation" && key !== "level")) {
|
|
44
|
+
throw new TypeError(`${path}.${key} is required.`);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function strings(value, path, found = []) {
|
|
50
|
+
if (typeof value === "string") {
|
|
51
|
+
const patterns = [
|
|
52
|
+
[/[\w.+-]+@[\w.-]+\.[A-Z]{2,}/i, "email address"],
|
|
53
|
+
[/\b[a-f\d]{8}-(?:[a-f\d]{4}-){3}[a-f\d]{12}\b/i, "GUID"],
|
|
54
|
+
[/\b[a-z\d-]+\.sharepoint(?:-df)?\.com\b|\b[a-z\d-]+\.onmicrosoft\.com\b/i, "tenant domain"],
|
|
55
|
+
[/\/(?:sites|teams)\/(?!your-site(?:\/|$)|your-team(?:\/|$)|example(?:\/|$))[a-z\d._%-]+/i, "site-specific path"],
|
|
56
|
+
[/\bBearer\s+\S+/i, "bearer token"],
|
|
57
|
+
[/\beyJ[a-zA-Z\d_-]{10,}\.[a-zA-Z\d_-]{10,}\.[a-zA-Z\d_-]{10,}\b/, "JWT-like token"],
|
|
58
|
+
[/[?&](?:access_token|refresh_token|client_secret|code)=[^&\s]+/i, "credential query parameter"],
|
|
59
|
+
];
|
|
60
|
+
for (const [pattern, label] of patterns) if (pattern.test(value)) found.push({ path, label });
|
|
61
|
+
} else if (Array.isArray(value)) {
|
|
62
|
+
value.forEach((item, index) => strings(item, `${path}[${index}]`, found));
|
|
63
|
+
} else if (value && typeof value === "object") {
|
|
64
|
+
for (const [key, item] of Object.entries(value)) strings(item, `${path}.${key}`, found);
|
|
65
|
+
}
|
|
66
|
+
return found;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function requireText(value, path, max = 2000) {
|
|
70
|
+
if (typeof value !== "string" || !value.trim() || value.length > max) throw new TypeError(`${path} must be a non-empty string of at most ${max} characters.`);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export function validateLearning(learning) {
|
|
74
|
+
if (!learning || typeof learning !== "object" || Array.isArray(learning)) throw new TypeError("Learning must be a JSON object.");
|
|
75
|
+
const sensitive = strings(learning, "learning");
|
|
76
|
+
if (sensitive.length) throw new TypeError(`Possible ${sensitive[0].label} at ${sensitive[0].path}. Replace it with generic details before sharing.`);
|
|
77
|
+
|
|
78
|
+
checkKeys(learning, fields.root, "learning");
|
|
79
|
+
if (learning.format !== "spfx-fast-learning" || learning.version !== 1) throw new TypeError("Learning format/version must be spfx-fast-learning/1.");
|
|
80
|
+
requireText(learning.title, "learning.title", 120);
|
|
81
|
+
if (!topics.has(learning.topic)) throw new TypeError(`learning.topic must be one of: ${[...topics].join(", ")}.`);
|
|
82
|
+
checkKeys(learning.appliesTo, fields.appliesTo, "learning.appliesTo");
|
|
83
|
+
for (const key of fields.appliesTo) requireText(learning.appliesTo[key], `learning.appliesTo.${key}`, 120);
|
|
84
|
+
requireText(learning.problem, "learning.problem");
|
|
85
|
+
requireText(learning.finding, "learning.finding");
|
|
86
|
+
if (!Array.isArray(learning.reproduction) || learning.reproduction.length < 1 || learning.reproduction.length > 12) throw new TypeError("learning.reproduction must contain 1 to 12 steps.");
|
|
87
|
+
learning.reproduction.forEach((step, index) => requireText(step, `learning.reproduction[${index}]`, 500));
|
|
88
|
+
requireText(learning.recommendation, "learning.recommendation");
|
|
89
|
+
requireText(learning.limitations, "learning.limitations");
|
|
90
|
+
checkKeys(learning.validation, fields.validation, "learning.validation");
|
|
91
|
+
if (!levels.has(learning.validation.level)) throw new TypeError(`learning.validation.level must be one of: ${[...levels].join(", ")}.`);
|
|
92
|
+
if (learning.validation.checkedOn !== undefined) {
|
|
93
|
+
const checkedOn = new Date(`${learning.validation.checkedOn}T00:00:00Z`);
|
|
94
|
+
if (!/^\d{4}-\d{2}-\d{2}$/.test(learning.validation.checkedOn) || Number.isNaN(checkedOn.valueOf()) || checkedOn.toISOString().slice(0, 10) !== learning.validation.checkedOn) throw new TypeError("learning.validation.checkedOn must be a valid YYYY-MM-DD date.");
|
|
95
|
+
}
|
|
96
|
+
if (learning.validation.level !== "unverified" && !learning.validation.checkedOn) throw new TypeError("Set validation.checkedOn for reproduced, tenant-validated, and documented findings.");
|
|
97
|
+
if (learning.validation.sampleSize !== undefined && (!Number.isInteger(learning.validation.sampleSize) || learning.validation.sampleSize < 1 || learning.validation.sampleSize > 10000)) throw new TypeError("learning.validation.sampleSize must be an integer from 1 to 10000.");
|
|
98
|
+
try {
|
|
99
|
+
validateRecipe(learning.recipe);
|
|
100
|
+
rejectUnknownKeys(learning.recipe, ["name", "steps"], "learning.recipe");
|
|
101
|
+
learning.recipe.steps.forEach((step, index) => {
|
|
102
|
+
const stepPath = `learning.recipe.steps[${index}]`;
|
|
103
|
+
rejectUnknownKeys(step, ["action", "path", "query", "locator", "value", "confirm", "checked", "expected", "exact", "name", "fullPage"], stepPath);
|
|
104
|
+
if (step.locator) rejectUnknownKeys(step.locator, ["role", "text", "label", "testId", "placeholder", "name", "exact"], `${stepPath}.locator`);
|
|
105
|
+
if (step.query && Object.keys(step.query).some((key) => key !== "debugManifestsFile")) throw new TypeError(`${stepPath}.query may only contain the local debugManifestsFile parameter.`);
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
catch (error) { throw new TypeError(`learning.recipe is invalid: ${error.message}`); }
|
|
109
|
+
return learning;
|
|
110
|
+
}
|