@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 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, screenshots, traces, and an ignored auth-state folder:
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 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
+ 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
- Use a dedicated signed-in test profile. The command calls Playwright Codegen and writes an ordinary Playwright spec:
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
- --profile-dir "$SPFX_TEST_PROFILE" \
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" npx playwright test
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 a persistent authenticated browser profile
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
- This path is useful when a team already has a signed-in Playwright profile and does not want to export its storage state:
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
- --profile-dir "$SPFX_TEST_PROFILE" \
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 is the `0.1.2` companion package. It is framework-agnostic across SPFx projects and ships independently from `@spfx-fast/core`.
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`.
@@ -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, 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.
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, and an ignored auth-state folder.");
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 requireProfileDirectory(options["profile-dir"]);
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 result = spawnSync(process.execPath, [cli, "codegen", `--user-data-dir=${profile}`, `--output=${output}`, "--viewport-size=1440,900", url], { stdio: "inherit" });
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 requireProfileDirectory(options["profile-dir"]);
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
- context = await chromium.launchPersistentContext(profile, {
206
- headless: options.headed ? false : true,
207
- viewport: { width: 1440, height: 900 },
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.2",
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
  }