@spfx-fast/playwright 0.1.0 → 0.1.2

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 CHANGED
@@ -1,8 +1,10 @@
1
1
  # @spfx-fast/playwright
2
2
 
3
- SPFx-aware Playwright helpers for **any SharePoint Framework project**. This is a development tool: install it in an SPFx project, keep it out of the shipped web-part bundle, and use the signed-in browser state already approved for that test environment. It does not depend on `@spfx-fast/core` or on a particular UI framework.
3
+ Playwright helpers for any SPFx project. This dev tool stays out of the web-part bundle and uses the approved signed-in test browser. It does not depend on `@spfx-fast/core` or a UI framework.
4
4
 
5
- The package builds on Playwright's own test runner, locator model, test recorder, traces, and screenshots. Its added value is a small agent-friendly recipe format, safe same-origin navigation, and a one-command authenticated run that leaves reviewable evidence.
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
+
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.
6
8
 
7
9
  ## Install in an SPFx project
8
10
 
@@ -10,7 +12,7 @@ The package builds on Playwright's own test runner, locator model, test recorder
10
12
  npm install --save-dev @spfx-fast/playwright @playwright/test playwright
11
13
  ```
12
14
 
13
- SPFx is not a Playwright dependency. Nothing from this package is imported by the production web part unless the developer chooses to do so.
15
+ SPFx is not a dependency. Production web parts do not import this package by default.
14
16
 
15
17
  Scaffold a serial Playwright setup with a starter recipe, generated test spec, agent instructions, screenshots, traces, and an ignored auth-state folder:
16
18
 
@@ -18,8 +20,7 @@ Scaffold a serial Playwright setup with a starter recipe, generated test spec, a
18
20
  npx spfx-fast-playwright init
19
21
  ```
20
22
 
21
- The generated config uses Playwright storage state only when `SPFX_STORAGE_STATE` is set. Put that file in the ignored `playwright/.auth/` folder or another ignored location; never commit it.
22
- The scaffold writes `SPFX-PLAYWRIGHT.md` and appends a link to `AGENTS.md` without replacing existing instructions.
23
+ The config uses storage state only when `SPFX_STORAGE_STATE` is set. Keep it in an ignored folder; never commit it. The scaffold adds `SPFX-PLAYWRIGHT.md` and links it from `AGENTS.md` without replacing existing instructions.
23
24
 
24
25
  ## Record a test with the Playwright recorder
25
26
 
@@ -32,48 +33,70 @@ npx spfx-fast-playwright record \
32
33
  --out tests/e2e/home-page.spec.ts
33
34
  ```
34
35
 
35
- Review generated selectors and assertions. Codegen records actions; it cannot know the business result that should be asserted.
36
+ Review selectors and add business assertions; Codegen records actions only.
36
37
 
37
38
  ## Generate a test mechanically from a small recipe
38
39
 
39
- Edit `examples/sharepoint-smoke.recipe.json` for the target site, then:
40
+ Edit the scaffolded `tests/e2e/sharepoint-smoke.recipe.json` for the target site, then:
40
41
 
41
42
  ```sh
42
- npx spfx-fast-playwright validate examples/sharepoint-smoke.recipe.json
43
- npx spfx-fast-playwright generate examples/sharepoint-smoke.recipe.json --out tests/e2e/sharepoint-smoke.spec.mjs
43
+ npx spfx-fast-playwright validate tests/e2e/sharepoint-smoke.recipe.json
44
+ npx spfx-fast-playwright generate tests/e2e/sharepoint-smoke.recipe.json --out tests/e2e/sharepoint-smoke.spec.mjs --force
44
45
  ```
45
46
 
46
- The generated file is a normal Playwright Test spec. It can run in a project's standard test runner and uses `SPFX_BASE_URL` plus that project's `storageState` configuration:
47
+ `init` already creates a spec at that output path; `--force` regenerates it from the edited recipe.
48
+
49
+ The output is a normal Playwright Test spec. Run it with the project's `SPFX_BASE_URL` and `storageState`:
47
50
 
48
51
  ```sh
49
52
  SPFX_BASE_URL="https://tenant.sharepoint.com/sites/your-site" npx playwright test
50
53
  ```
51
54
 
52
- For local state files, keep them out of source control. Playwright authentication state contains session cookies and can impersonate the test user. Prefer a dedicated, least-privilege test account and a dedicated test site.
55
+ Keep state files out of source control. They contain impersonation-capable session data. Use a dedicated least-privilege account and test site.
56
+
57
+ ## Capture and contribute a SharePoint UI discovery
58
+
59
+ Capture a reusable finding and runnable recipe as a local draft:
60
+
61
+ ```sh
62
+ npx spfx-fast-playwright learn init
63
+ # Edit test-results/spfx-fast-playwright/learning-draft.json.
64
+ npx spfx-fast-playwright learn validate test-results/spfx-fast-playwright/learning-draft.json
65
+ ```
66
+
67
+ 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.
68
+
69
+ 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.
70
+
71
+ 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.
53
72
 
54
73
  ## Run a recipe with a persistent authenticated browser profile
55
74
 
56
75
  This path is useful when a team already has a signed-in Playwright profile and does not want to export its storage state:
57
76
 
58
77
  ```sh
59
- npx spfx-fast-playwright run examples/sharepoint-smoke.recipe.json \
78
+ npx spfx-fast-playwright run tests/e2e/sharepoint-smoke.recipe.json \
60
79
  --base-url "$SPFX_BASE_URL" \
61
80
  --profile-dir "$SPFX_TEST_PROFILE" \
62
81
  --artifacts test-results/sharepoint-smoke
63
82
  ```
64
83
 
65
- The command runs one browser job, enforces the configured origin, and writes screenshots requested by the recipe, a Playwright trace, and `summary.json`. It never performs a login or reads profile cookies. It does not create or copy a profile. Do not run another job against the same profile at the same time.
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.
85
+
86
+ 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.
66
87
 
67
88
  ## Recipe actions
68
89
 
69
90
  Recipes are plain JSON so agents can generate them without writing browser plumbing:
70
91
 
92
+ `navigate` accepts a `query` map. `debugManifestsFile` is limited to local HTTPS hosts for SPFx debug builds.
93
+
71
94
  | Action | Purpose |
72
95
  | --- | --- |
73
96
  | `navigate` | Open a path on the configured site origin |
74
97
  | `assertPageReady` | Wait for the document body and SharePoint origin |
75
98
  | `assertAuthenticated` | Check the current web's SharePoint REST endpoint without reading user data |
76
- | `click` | Click a semantic role, label, text, test ID, or placeholder locator |
99
+ | `click` | Click a semantic locator; `confirm: true` accepts an expected browser confirmation |
77
100
  | `fill` | Fill an accessible input |
78
101
  | `select` | Select an option in a native select |
79
102
  | `setChecked` | Set a checkbox or radio state |
@@ -82,17 +105,38 @@ Recipes are plain JSON so agents can generate them without writing browser plumb
82
105
  | `assertValue` | Check an input value |
83
106
  | `screenshot` | Save a named PNG to the local artifact directory |
84
107
 
85
- Prefer role and label locators over CSS selectors. The recipe format intentionally has no raw JavaScript or arbitrary URL action.
108
+ Prefer `testId` locators for stable targeting when the app exposes `data-testid`. Use role/label locators when the test is checking accessible interaction, especially for form controls. Use `assertText` to verify user-visible content on the selected element; use a text locator only when the text itself is the only useful target. Recipes do not allow raw JavaScript or arbitrary URLs.
109
+
110
+ For a known browser confirmation, a click can set `"confirm": true`. The runner accepts only a JavaScript `confirm` dialog and fails if no confirmation appears or a different dialog type appears. Use this only for an explicitly approved test action; it does not bypass the confirmation shown to the user.
111
+
112
+ ### Validate one Graph list CRUD operation
113
+
114
+ The [tenant CRUD recipe](examples/tenant-crud-validation.recipe.json) clicks the dashboard's **Test list CRUD** button, accepts its explicit warning, and requires the create/read/update/read/delete success message. Copy it from the installed package into the project, then replace the site and page path and configure a test list in the web part:
115
+
116
+ ```sh
117
+ cp node_modules/@spfx-fast/playwright/examples/tenant-crud-validation.recipe.json tests/e2e/tenant-crud-validation.recipe.json
118
+ npx spfx-fast-playwright validate tests/e2e/tenant-crud-validation.recipe.json
119
+ npx spfx-fast-playwright run tests/e2e/tenant-crud-validation.recipe.json \
120
+ --base-url "$SPFX_BASE_URL" \
121
+ --profile-dir "$SPFX_TEST_PROFILE" \
122
+ --artifacts test-results/tenant-crud
123
+ ```
124
+
125
+ Use a disposable test list and an account approved for Graph `Sites.ReadWrite.All`. The test creates one temporary item and deletes it; inspect the result and remove any item manually if cleanup reports failure. Do not point this recipe at production data.
126
+
127
+ For a known browser confirmation, a click can set `"confirm": true`. The runner accepts only a JavaScript `confirm` dialog and fails if no confirmation appears or a different dialog type appears. Use this only for an explicitly approved test action; it does not bypass the confirmation shown to the user.
86
128
 
87
129
  ## What this does not do
88
130
 
89
- - It does not automate Microsoft sign-in, extract tokens, or bypass SharePoint permissions.
90
- - It does not create or alter SharePoint content. Add explicit steps and user approval before tests that write data.
91
- - It does not claim a screenshot proves the underlying API or persistence succeeded; assert those separately.
92
- - It does not replace Playwright Codegen. Use Codegen for interactive recording, then add meaningful assertions.
131
+ - No sign-in automation, token extraction, or permission bypass.
132
+ - No content writes unless explicitly added and approved.
133
+ - Screenshots do not prove API success or persistence; assert those separately.
134
+ - Codegen records actions; add meaningful assertions yourself.
135
+
136
+ Artifacts may contain tenant data. Keep results, auth files, and profiles local; review before sharing.
93
137
 
94
- Screenshots and traces may contain tenant content. Keep `test-results/`, `playwright-report/`, authentication files, and profile directories local; review artifacts before sharing.
138
+ For a full workflow with profile, SharePoint page, image, and OCR guidance, read [the agent browser workflow](../../docs/AGENT-BROWSER-WORKFLOW.md).
95
139
 
96
140
  ## Package status
97
141
 
98
- This is the early `0.1.0` companion package. It is framework-agnostic across SPFx projects and ships independently from `@spfx-fast/core`.
142
+ This is the `0.1.2` companion package. It is framework-agnostic across SPFx projects and ships independently from `@spfx-fast/core`.
@@ -1,27 +1,33 @@
1
1
  # SPFx Playwright instructions
2
2
 
3
- Use this guide for tests against any SharePoint Framework project. The package is a development tool and does not require `@spfx-fast/core`.
3
+ For any SPFx project. This dev tool does not require `@spfx-fast/core`.
4
4
 
5
5
  ## Start with the existing project
6
6
 
7
- - Use its installed Playwright version, configuration, signed-in test account, and test site.
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, read or print cookies, copy the user's daily browser profile, or commit authentication state.
10
- - Keep a persistent profile to one browser job at a time.
9
+ - Never automate sign-in, inspect cookies, copy a daily profile, or commit auth state.
10
+ - Run one job per persistent profile. `run` and `record` lock it; close manually opened browsers first.
11
11
 
12
12
  ## Generate and run
13
13
 
14
- - For an interactive recording, use `spfx-fast-playwright record` with the project's dedicated signed-in profile. Review generated selectors and add assertions for the expected user-visible result.
15
- - For a small repeatable workflow, write or adjust a JSON recipe, run `spfx-fast-playwright validate`, then `generate` or `run` it.
16
- - Prefer role and label locators. Add explicit waits for the condition under test; do not use `networkidle` as a generic SharePoint readiness signal.
17
- - Use `assertAuthenticated` to check the current web's REST response without reading account details.
18
- - Keep navigation within the configured origin. A sign-in redirect is a failed precondition, not a passing page load.
19
- - Use the real QA page and data needed for the result. A zero-to-zero comparison or a page missing the web part is inconclusive.
14
+ - Record with `spfx-fast-playwright record`; review selectors and add user-visible assertions.
15
+ - For repeatable checks, validate a JSON recipe, then `generate` or `run` it.
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
+ - Use `run --fast` during fixes, then run once without it.
18
+ - `assertAuthenticated` checks REST without reading account details.
19
+ - A click may set `confirm: true` to accept exactly one expected JavaScript confirmation; it fails if the dialog is missing or has another type.
20
+ - Keep navigation on the configured origin. Sign-in redirects fail the precondition.
21
+ - Test the real QA page and required data; missing web parts or zero-to-zero comparisons prove nothing.
22
+ - Before tenant deployment, read [the SPFx ALM deployment guide](../../../docs/AGENT-SHAREPOINT-DEPLOYMENT.md). Verify the catalog package state and the manifest component ID; don't choose a web part by a generic name.
20
23
 
21
24
  ## Prove and report
22
25
 
23
- - Default to read-only checks. For tests that write SharePoint data, use dedicated test records and an explicit cleanup plan; do not alter production content.
24
- - Inspect the generated spec before running it. Then inspect `summary.json`, each screenshot, and the trace after a run.
25
- - A screenshot proves only what was visible. Add request or persisted-state assertions when the behavior depends on SharePoint REST, Graph, save, or publish.
26
- - If a control cannot be reached after three attempts, stop and report the blocker with its screenshot/trace. Do not loop or mark an inconclusive run as passed.
27
- - Do not share traces or screenshots until checking for tenant content and personal data.
26
+ - Prefer read-only checks. Writes need dedicated records and cleanup; never change production data.
27
+ - The [tenant CRUD recipe](../examples/tenant-crud-validation.recipe.json) is only for a disposable list on a dedicated test page and account.
28
+ - Review generated specs. Inspect `summary.json`, screenshots, and trace after each run.
29
+ - Screenshots show appearance only. Assert API or saved/published state separately.
30
+ - After three failed attempts to reach a control, stop and report the blocker with evidence.
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.
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,8 +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";
10
+ import { acquireProfileLock } from "../src/profile-lock.js";
9
11
 
10
- 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> Generate a native Playwright test\n run <recipe.json> --base-url <url> --profile-dir <dir> [--artifacts <dir>] [--headless]\n record --url <url> --profile-dir <dir> --out <test.spec.ts> Start Playwright Codegen\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> --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`;
11
13
 
12
14
  const parsed = parseArgs({
13
15
  args: process.argv.slice(2),
@@ -21,6 +23,8 @@ const parsed = parseArgs({
21
23
  "timeout-ms": { type: "string" },
22
24
  url: { type: "string" },
23
25
  headless: { type: "boolean", default: false },
26
+ headed: { type: "boolean", default: false },
27
+ fast: { type: "boolean", default: false },
24
28
  force: { type: "boolean", default: false },
25
29
  help: { type: "boolean", short: "h", default: false },
26
30
  },
@@ -38,6 +42,15 @@ async function readRecipe(file) {
38
42
  }
39
43
  }
40
44
 
45
+ async function readLearning(file) {
46
+ if (!file) throw new Error("Supply a learning JSON file.");
47
+ try { return validateLearning(JSON.parse(await readFile(resolve(file), "utf8"))); }
48
+ catch (error) {
49
+ if (error instanceof TypeError) throw error;
50
+ throw new Error("Could not read a valid learning JSON file.");
51
+ }
52
+ }
53
+
41
54
  async function outputPath(file) {
42
55
  if (!file) throw new Error("Supply --out.");
43
56
  const target = resolve(file);
@@ -49,6 +62,18 @@ async function outputPath(file) {
49
62
  return target;
50
63
  }
51
64
 
65
+ async function ignoreLearningDraft() {
66
+ const file = resolve(".gitignore");
67
+ let existing = "";
68
+ try { existing = await readFile(file, "utf8"); }
69
+ catch (error) { if (error.code !== "ENOENT") throw error; }
70
+ const entry = "/test-results/spfx-fast-playwright/learning-draft.json";
71
+ const ignored = existing.split(/\r?\n/);
72
+ if (ignored.includes(entry) || ignored.includes("/test-results/") || ignored.includes("test-results/")) return false;
73
+ await writeFile(file, `${existing}${existing && !existing.endsWith("\n") ? "\n" : ""}${entry}\n`, "utf8");
74
+ return true;
75
+ }
76
+
52
77
  async function requireProfileDirectory(value) {
53
78
  if (!value) throw new Error("Supply an existing --profile-dir. The command will not create or copy a signed-in profile.");
54
79
  const path = resolve(value);
@@ -111,6 +136,26 @@ async function main() {
111
136
  console.log(`Recipe valid: ${recipe.name} (${recipe.steps.length} steps).`);
112
137
  return;
113
138
  }
139
+ if (command === "learn") {
140
+ const action = recipeFile;
141
+ const file = parsed.positionals[2];
142
+ if (action === "init") {
143
+ const isDefault = !options.out && !file;
144
+ const target = await outputPath(options.out ?? file ?? "test-results/spfx-fast-playwright/learning-draft.json");
145
+ if (isDefault && await ignoreLearningDraft()) console.log("Added the default draft path to .gitignore.");
146
+ await writeFile(target, `${JSON.stringify(createLearningDraft(), null, 2)}\n`, "utf8");
147
+ console.log(`Created local learning draft: ${target}`);
148
+ console.log("The draft contains no author or tenant fields. Edit it, validate it, then review it manually before sharing.");
149
+ return;
150
+ }
151
+ if (action === "validate") {
152
+ const learning = await readLearning(file ?? options.out);
153
+ console.log(`Learning valid: ${learning.title} (${learning.topic}, ${learning.validation.level}).`);
154
+ console.log("No upload occurred. Validation catches common identifiers; it cannot prove a draft is anonymous. Review every value and attached artifact.");
155
+ return;
156
+ }
157
+ throw new Error("Usage: spfx-fast-playwright learn <init [--out <file>] | validate <file>>");
158
+ }
114
159
  if (command === "generate") {
115
160
  const recipe = await readRecipe(recipeFile);
116
161
  const target = await outputPath(options.out);
@@ -127,9 +172,12 @@ async function main() {
127
172
  const requireFromProject = createRequire(pathToFileURL(resolve("package.json")));
128
173
  const playwrightEntry = requireFromProject.resolve("playwright");
129
174
  const cli = resolve(dirname(playwrightEntry), "cli.js");
130
- const result = spawnSync(process.execPath, [cli, "codegen", `--user-data-dir=${profile}`, `--output=${output}`, "--viewport-size=1440,900", url], { stdio: "inherit" });
131
- if (result.error) throw new Error("Playwright Codegen could not start. Check that Playwright is installed in this project.");
132
- if (result.status !== 0) process.exitCode = result.status ?? 1;
175
+ const releaseProfile = acquireProfileLock(profile);
176
+ try {
177
+ const result = spawnSync(process.execPath, [cli, "codegen", `--user-data-dir=${profile}`, `--output=${output}`, "--viewport-size=1440,900", url], { stdio: "inherit" });
178
+ if (result.error) throw new Error("Playwright Codegen could not start. Check that Playwright is installed in this project.");
179
+ if (result.status !== 0) process.exitCode = result.status ?? 1;
180
+ } finally { releaseProfile(); }
133
181
  return;
134
182
  }
135
183
  if (command === "run") {
@@ -148,32 +196,36 @@ async function main() {
148
196
  } catch {}
149
197
  await mkdir(artifacts, { recursive: true });
150
198
  const { chromium } = await import("playwright");
151
- const context = await chromium.launchPersistentContext(profile, {
152
- headless: options.headless,
153
- viewport: { width: 1440, height: 900 },
154
- });
199
+ const releaseProfile = acquireProfileLock(profile);
200
+ let context;
155
201
  let page;
156
202
  let result;
157
203
  let error;
158
204
  try {
205
+ context = await chromium.launchPersistentContext(profile, {
206
+ headless: options.headed ? false : true,
207
+ viewport: { width: 1440, height: 900 },
208
+ });
159
209
  page = context.pages()[0] ?? await context.newPage();
160
- await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
161
- result = await runRecipe(page, recipe, { baseUrl: base.href, screenshotDir: artifacts, timeoutMs });
210
+ if (!options.fast) await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
211
+ result = await runRecipe(page, recipe, { baseUrl: base.href, screenshotDir: artifacts, timeoutMs, fast: options.fast });
162
212
  } catch (cause) {
163
213
  error = cause;
164
214
  if (page) {
165
215
  try { await page.screenshot({ path: resolve(artifacts, "failure.png"), fullPage: true }); } catch {}
166
216
  }
167
217
  } finally {
168
- try { await context.tracing.stop({ path: resolve(artifacts, "trace.zip") }); } catch {}
169
- await context.close();
218
+ if (context && !options.fast) try { await context.tracing.stop({ path: resolve(artifacts, "trace.zip") }); } catch {}
219
+ await context?.close();
220
+ releaseProfile();
170
221
  }
171
222
  const report = {
172
223
  name: recipe.name,
173
224
  status: error ? "failed" : "passed",
174
225
  stepCount: recipe.steps.length,
175
226
  screenshots: error ? ["failure.png"] : result.screenshots.map((file) => file.slice(artifacts.length + 1)),
176
- trace: "trace.zip",
227
+ trace: options.fast ? null : "trace.zip",
228
+ fastMode: options.fast,
177
229
  failedStep: error?.step ?? null,
178
230
  error: error ? error.message : null,
179
231
  };
@@ -0,0 +1,11 @@
1
+ {
2
+ "name": "SPFx Fast single-item Graph CRUD validation",
3
+ "steps": [
4
+ { "action": "navigate", "path": "/sites/your-site/SitePages/tenant-validation.aspx" },
5
+ { "action": "assertPageReady" },
6
+ { "action": "assertAuthenticated" },
7
+ { "action": "assertVisible", "locator": { "testId": "tenant-validation-run-list-crud" } },
8
+ { "action": "click", "locator": { "testId": "tenant-validation-run-list-crud" }, "confirm": true },
9
+ { "action": "assertText", "locator": { "testId": "tenant-validation-list-crud-result" }, "expected": "Create, read, update, read, and delete succeeded for one temporary list item.", "exact": false }
10
+ ]
11
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spfx-fast/playwright",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "author": "Vilius Vystartas",
5
5
  "description": "Authenticated, recipe-driven Playwright testing helpers for any SharePoint Framework project.",
6
6
  "license": "MIT",
@@ -16,7 +16,7 @@
16
16
  "main": "./src/index.js",
17
17
  "types": "./src/index.d.ts",
18
18
  "exports": { ".": { "types": "./src/index.d.ts", "import": "./src/index.js" } },
19
- "bin": { "spfx-fast-playwright": "./bin/spfx-fast-playwright.mjs" },
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
22
  "keywords": ["spfx", "sharepoint", "playwright", "e2e", "testing", "agents"]
package/src/index.d.ts CHANGED
@@ -8,10 +8,11 @@ export type RecipeLocator =
8
8
  | { placeholder: string; exact?: boolean };
9
9
 
10
10
  export type RecipeStep =
11
- | { action: "navigate"; path: string }
11
+ | { action: "navigate"; path: string; query?: Record<string, string> }
12
12
  | { action: "assertPageReady" }
13
13
  | { action: "assertAuthenticated" }
14
- | { action: "click" | "assertVisible"; locator: RecipeLocator }
14
+ | { action: "click"; locator: RecipeLocator; confirm?: true }
15
+ | { action: "assertVisible"; locator: RecipeLocator }
15
16
  | { action: "fill"; locator: RecipeLocator; value: string }
16
17
  | { action: "select"; locator: RecipeLocator; value: string }
17
18
  | { action: "setChecked"; locator: RecipeLocator; checked: boolean }
@@ -29,5 +30,6 @@ export function runRecipe(page: Page, recipe: SharePointRecipe, options: {
29
30
  baseUrl: string;
30
31
  screenshotDir?: string;
31
32
  timeoutMs?: number;
33
+ fast?: boolean;
32
34
  }): Promise<{ name: string; steps: number; screenshots: string[] }>;
33
35
  export function generateTestSource(recipe: SharePointRecipe): string;
package/src/index.js CHANGED
@@ -16,8 +16,28 @@ export function validateRecipe(recipe) {
16
16
  if (step.action === "navigate" && (typeof step.path !== "string" || !step.path.startsWith("/") || step.path.startsWith("//") || /[?#]/.test(step.path))) {
17
17
  throw new TypeError(`Recipe step ${index + 1} needs a same-site path beginning with / and no query or fragment.`);
18
18
  }
19
+ if (step.action === "navigate" && step.query !== undefined) {
20
+ if (!step.query || typeof step.query !== "object" || Array.isArray(step.query) || Object.keys(step.query).length > 16) {
21
+ throw new TypeError(`Recipe step ${index + 1} query must be an object with at most 16 parameters.`);
22
+ }
23
+ for (const [key, value] of Object.entries(step.query)) {
24
+ if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(key) || typeof value !== "string" || value.length > 2048) {
25
+ throw new TypeError(`Recipe step ${index + 1} has an invalid query parameter.`);
26
+ }
27
+ if (key.toLowerCase() === "debugmanifestsfile") {
28
+ let manifest;
29
+ try { manifest = new URL(value); } catch { throw new TypeError("debugManifestsFile must use a local HTTPS URL."); }
30
+ if (manifest.protocol !== "https:" || !["localhost", "127.0.0.1"].includes(manifest.hostname) || manifest.username || manifest.password) {
31
+ throw new TypeError("debugManifestsFile must use a local HTTPS URL.");
32
+ }
33
+ }
34
+ }
35
+ }
19
36
  if (["click", "fill", "select", "setChecked", "assertVisible", "assertText", "assertValue"].includes(step.action)) validateLocator(step.locator, index + 1);
20
37
  if (["fill", "select"].includes(step.action) && typeof step.value !== "string") throw new TypeError(`Recipe step ${index + 1} needs a string value.`);
38
+ if (step.confirm !== undefined && (step.action !== "click" || step.confirm !== true)) {
39
+ throw new TypeError(`Recipe step ${index + 1} can only set confirm: true on a click action.`);
40
+ }
21
41
  if (step.action === "setChecked" && typeof step.checked !== "boolean") throw new TypeError(`Recipe step ${index + 1} needs a boolean checked value.`);
22
42
  if (["assertText", "assertValue"].includes(step.action) && typeof step.expected !== "string") throw new TypeError(`Recipe step ${index + 1} needs expected text.`);
23
43
  if (step.action === "screenshot" && (typeof step.name !== "string" || !/^[\w-]+$/.test(step.name))) {
@@ -60,7 +80,7 @@ function assertSameOrigin(page, base) {
60
80
  if (current.origin !== base.origin) throw new Error("Navigation left the configured SharePoint origin; check sign-in state and page links.");
61
81
  }
62
82
 
63
- export async function runRecipe(page, recipe, { baseUrl, screenshotDir, timeoutMs = 15000 } = {}) {
83
+ export async function runRecipe(page, recipe, { baseUrl, screenshotDir, timeoutMs = 15000, fast = false } = {}) {
64
84
  validateRecipe(recipe);
65
85
  const base = validateBaseUrl(baseUrl);
66
86
  const screenshots = [];
@@ -71,6 +91,7 @@ export async function runRecipe(page, recipe, { baseUrl, screenshotDir, timeoutM
71
91
  if (step.action === "navigate") {
72
92
  const destination = new URL(step.path, base);
73
93
  if (destination.origin !== base.origin) throw new Error("Navigation must stay on the configured SharePoint origin.");
94
+ for (const [key, value] of Object.entries(step.query ?? {})) destination.searchParams.set(key, value);
74
95
  const response = await page.goto(destination.href, { waitUntil: "domcontentloaded", timeout: timeoutMs });
75
96
  if (response && response.status() >= 400) throw new Error(`Page returned HTTP ${response.status()}.`);
76
97
  assertSameOrigin(page, base);
@@ -93,7 +114,28 @@ export async function runRecipe(page, recipe, { baseUrl, screenshotDir, timeoutM
93
114
  }
94
115
  assertSameOrigin(page, base);
95
116
  } else if (step.action === "click") {
96
- await locatorFor(page, step.locator).click({ timeout: timeoutMs });
117
+ if (step.confirm) {
118
+ let dialogSeen = false;
119
+ let dialogError;
120
+ let dialogHandling = Promise.resolve();
121
+ const handleDialog = (dialog) => {
122
+ dialogSeen = true;
123
+ dialogHandling = dialog.type() === "confirm"
124
+ ? dialog.accept().catch(() => { dialogError = "The browser confirmation could not be accepted."; })
125
+ : dialog.dismiss().then(() => { dialogError = "Expected a browser confirmation dialog."; });
126
+ };
127
+ page.once("dialog", handleDialog);
128
+ try {
129
+ await locatorFor(page, step.locator).click({ timeout: timeoutMs });
130
+ await dialogHandling;
131
+ if (!dialogSeen) throw new Error("Expected a browser confirmation dialog, but none appeared.");
132
+ if (dialogError) throw new Error(dialogError);
133
+ } finally {
134
+ page.off("dialog", handleDialog);
135
+ }
136
+ } else {
137
+ await locatorFor(page, step.locator).click({ timeout: timeoutMs });
138
+ }
97
139
  assertSameOrigin(page, base);
98
140
  } else if (step.action === "fill") {
99
141
  await locatorFor(page, step.locator).fill(step.value, { timeout: timeoutMs });
@@ -121,6 +163,7 @@ export async function runRecipe(page, recipe, { baseUrl, screenshotDir, timeoutM
121
163
  if (!(step.exact === false ? actual.includes(step.expected) : actual === step.expected)) throw new Error(`Value assertion failed (${step.exact === false ? "contains" : "exact"}).`);
122
164
  assertSameOrigin(page, base);
123
165
  } else if (step.action === "screenshot") {
166
+ if (fast) continue;
124
167
  if (!screenshotDir) throw new Error("Screenshots need an artifact directory.");
125
168
  assertSameOrigin(page, base);
126
169
  const file = join(screenshotDir, `${step.name}.png`);
@@ -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
+ }
@@ -0,0 +1,72 @@
1
+ import { createHash } from "node:crypto";
2
+ import { hostname, tmpdir } from "node:os";
3
+ import { join, resolve } from "node:path";
4
+ import { mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, writeFileSync } from "node:fs";
5
+
6
+ function processExists(pid) {
7
+ try { process.kill(pid, 0); return true; }
8
+ catch (error) { return error?.code === "EPERM"; }
9
+ }
10
+
11
+ function assertProfileFree(profileDir) {
12
+ if (process.platform === "win32") return;
13
+ let value;
14
+ try { value = readlinkSync(join(profileDir, "SingletonLock")); }
15
+ catch { return; }
16
+ const separator = value.lastIndexOf("-");
17
+ const ownerHost = value.slice(0, separator);
18
+ const ownerPid = Number(value.slice(separator + 1));
19
+ if (ownerHost === hostname() && Number.isInteger(ownerPid) && processExists(ownerPid)) {
20
+ throw new Error("The supplied browser profile is already open. Close that browser before running Playwright.");
21
+ }
22
+ }
23
+
24
+ /** Serialize SPFx Fast jobs using one persistent browser profile. Never removes Chrome profile files. */
25
+ export function acquireProfileLock(profileDirectory) {
26
+ const profileDir = resolve(profileDirectory);
27
+ assertProfileFree(profileDir);
28
+ const hash = createHash("sha256").update(profileDir).digest("hex").slice(0, 24);
29
+ const lockDir = join(tmpdir(), `spfx-fast-playwright-${hash}.lock`);
30
+ const owner = JSON.stringify({ host: hostname(), pid: process.pid });
31
+ try {
32
+ mkdirSync(lockDir);
33
+ writeFileSync(join(lockDir, "owner.json"), owner, { flag: "wx", mode: 0o600 });
34
+ } catch (error) {
35
+ if (error?.code === "EEXIST") {
36
+ let previous;
37
+ try { previous = JSON.parse(readFileSync(join(lockDir, "owner.json"), "utf8")); }
38
+ catch { throw new Error("A Playwright job may be starting with this browser profile; retry after it finishes."); }
39
+ if (previous.host !== hostname() || processExists(Number(previous.pid))) {
40
+ throw new Error("Another SPFx Fast Playwright job is using this browser profile.");
41
+ }
42
+ const staleDir = `${lockDir}.stale-${process.pid}-${Date.now()}`;
43
+ try { renameSync(lockDir, staleDir); }
44
+ catch (renameError) {
45
+ if (renameError?.code === "ENOENT") return acquireProfileLock(profileDir);
46
+ throw new Error("A Playwright job may be opening this browser profile; retry after it finishes.");
47
+ }
48
+ try {
49
+ if (readFileSync(join(staleDir, "owner.json"), "utf8") !== JSON.stringify(previous)) {
50
+ try { renameSync(staleDir, lockDir); } catch { /* Another run already restored or replaced the lock. */ }
51
+ throw new Error("The browser-profile lock changed while checking it; retry after the active job finishes.");
52
+ }
53
+ } catch (verifyError) {
54
+ if (verifyError instanceof Error && verifyError.message.startsWith("The browser-profile lock changed")) throw verifyError;
55
+ throw new Error("Could not verify the browser-profile lock owner; retry after the active job finishes.");
56
+ }
57
+ rmSync(staleDir, { recursive: true, force: true });
58
+ return acquireProfileLock(profileDir);
59
+ }
60
+ rmSync(lockDir, { recursive: true, force: true });
61
+ throw error;
62
+ }
63
+ let released = false;
64
+ return () => {
65
+ if (released) return;
66
+ released = true;
67
+ try {
68
+ const current = readFileSync(join(lockDir, "owner.json"), "utf8");
69
+ if (current === owner) rmSync(lockDir, { recursive: true, force: true });
70
+ } catch { /* The lock was already released or replaced. */ }
71
+ };
72
+ }