@spfx-fast/playwright 0.1.1 → 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 +19 -1
- package/agent/PLAYWRIGHT.md +1 -0
- package/bin/spfx-fast-playwright.mjs +43 -1
- package/package.json +1 -1
- 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
|
|
@@ -52,6 +54,22 @@ SPFX_BASE_URL="https://tenant.sharepoint.com/sites/your-site" npx playwright tes
|
|
|
52
54
|
|
|
53
55
|
Keep state files out of source control. They contain impersonation-capable session data. Use a dedicated least-privilege account and test site.
|
|
54
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.
|
|
72
|
+
|
|
55
73
|
## Run a recipe with a persistent authenticated browser profile
|
|
56
74
|
|
|
57
75
|
This path is useful when a team already has a signed-in Playwright profile and does not want to export its storage state:
|
|
@@ -121,4 +139,4 @@ For a full workflow with profile, SharePoint page, image, and OCR guidance, read
|
|
|
121
139
|
|
|
122
140
|
## Package status
|
|
123
141
|
|
|
124
|
-
This is the `0.1.
|
|
142
|
+
This is the `0.1.2` companion package. It is framework-agnostic across SPFx projects and ships independently from `@spfx-fast/core`.
|
package/agent/PLAYWRIGHT.md
CHANGED
|
@@ -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> --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
13
|
|
|
13
14
|
const parsed = parseArgs({
|
|
14
15
|
args: process.argv.slice(2),
|
|
@@ -41,6 +42,15 @@ async function readRecipe(file) {
|
|
|
41
42
|
}
|
|
42
43
|
}
|
|
43
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
|
+
|
|
44
54
|
async function outputPath(file) {
|
|
45
55
|
if (!file) throw new Error("Supply --out.");
|
|
46
56
|
const target = resolve(file);
|
|
@@ -52,6 +62,18 @@ async function outputPath(file) {
|
|
|
52
62
|
return target;
|
|
53
63
|
}
|
|
54
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
|
+
|
|
55
77
|
async function requireProfileDirectory(value) {
|
|
56
78
|
if (!value) throw new Error("Supply an existing --profile-dir. The command will not create or copy a signed-in profile.");
|
|
57
79
|
const path = resolve(value);
|
|
@@ -114,6 +136,26 @@ async function main() {
|
|
|
114
136
|
console.log(`Recipe valid: ${recipe.name} (${recipe.steps.length} steps).`);
|
|
115
137
|
return;
|
|
116
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
|
+
}
|
|
117
159
|
if (command === "generate") {
|
|
118
160
|
const recipe = await readRecipe(recipeFile);
|
|
119
161
|
const target = await outputPath(options.out);
|
package/package.json
CHANGED
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
|
+
}
|