@activatus/code-standards 3.1.1 → 3.2.0
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/docs/Guides/migrating.md +89 -60
- package/docs/Guides/regression-checks.md +72 -0
- package/docs/Guides/setup.md +47 -14
- package/docs/Standards/documentation.md +38 -1
- package/docs/Standards/eslint.md +6 -4
- package/docs/templates.mdx +10 -2
- package/docs/version-history.md +15 -3
- package/package.json +6 -2
- package/scripts/verifyStandards/checkAgentFiles.mjs +148 -0
- package/scripts/verifyStandards/checkComponents.mjs +129 -0
- package/scripts/verifyStandards/checkConfigFiles.mjs +230 -0
- package/scripts/verifyStandards/checkDocs.mjs +86 -0
- package/scripts/verifyStandards/checkRequiredFiles.mjs +96 -0
- package/scripts/verifyStandards/formatReport.mjs +76 -0
- package/scripts/verifyStandards/projectFiles.mjs +109 -0
- package/scripts/verifyStandards/runChecks.mjs +62 -0
- package/scripts/verifyStandards/verifyStandards.mjs +22 -0
- package/static/templates/AGENTS.md +1 -1
- package/static/templates/docs/development/coding-standards.md +4 -0
- package/static/templates/docs/overview/writing-docs.md +4 -0
- package/static/templates/eslint/nextjs/eslint.config.mjs +2 -1
- package/static/templates/eslint/react/eslint.config.mjs +2 -1
- package/static/templates/tests/visual/pageLayout.visual.ts +188 -0
- package/static/templates/tests/visual/playwright.config.mjs +65 -0
- package/static/templates/tests/visual/visualPages.mjs +3 -0
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
// Turns the findings into the report printed for the person or agent:
|
|
2
|
+
// grouped by standard, with the page to read for each.
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
|
|
5
|
+
import { PACKAGE_DIRECTORY } from "./projectFiles.mjs";
|
|
6
|
+
|
|
7
|
+
// The names from the numbered list in docs/Guides/setup.md.
|
|
8
|
+
const STANDARD_NAMES = {
|
|
9
|
+
4: "Every function and component has a test file",
|
|
10
|
+
6: "ESLint",
|
|
11
|
+
7: "Prettier",
|
|
12
|
+
8: "Stylelint",
|
|
13
|
+
9: "EditorConfig",
|
|
14
|
+
10: "Node version",
|
|
15
|
+
12.1: "Constants",
|
|
16
|
+
15: "Design System Components",
|
|
17
|
+
18: "Docs",
|
|
18
|
+
21: "AGENTS.md and the agent skills",
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
const toPagePath = ({ page, projectDirectory }) =>
|
|
22
|
+
path.relative(projectDirectory, path.join(PACKAGE_DIRECTORY, page));
|
|
23
|
+
|
|
24
|
+
const formatStandard = ({ standard, findings, projectDirectory }) => {
|
|
25
|
+
const standardFindings = findings.filter(
|
|
26
|
+
(finding) => finding.standard === standard,
|
|
27
|
+
);
|
|
28
|
+
const lines = standardFindings.map(
|
|
29
|
+
(finding) => ` - ${finding.message}`,
|
|
30
|
+
);
|
|
31
|
+
const pages = [
|
|
32
|
+
...new Set(
|
|
33
|
+
standardFindings.map((finding) => finding.page).filter(Boolean),
|
|
34
|
+
),
|
|
35
|
+
].map(
|
|
36
|
+
(page) => ` Read: ${toPagePath({ page, projectDirectory })}`,
|
|
37
|
+
);
|
|
38
|
+
const heading = `${standard}. ${STANDARD_NAMES[standard] ?? ""}`;
|
|
39
|
+
return [heading, ...lines, ...pages].join("\n");
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
const formatGroup = ({ findings, projectDirectory }) => {
|
|
43
|
+
const standards = [
|
|
44
|
+
...new Set(findings.map((finding) => finding.standard)),
|
|
45
|
+
];
|
|
46
|
+
return standards
|
|
47
|
+
.map((standard) =>
|
|
48
|
+
formatStandard({ standard, findings, projectDirectory }),
|
|
49
|
+
)
|
|
50
|
+
.join("\n\n");
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
export const formatReport = ({ result, projectDirectory }) => {
|
|
54
|
+
const sections = [];
|
|
55
|
+
if (result.failures.length > 0) {
|
|
56
|
+
sections.push(
|
|
57
|
+
`To fix (${result.failures.length}):\n\n${formatGroup({ findings: result.failures, projectDirectory })}`,
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
if (result.recorded.length > 0) {
|
|
61
|
+
sections.push(
|
|
62
|
+
`Recorded exceptions in docs/development/coding-standards.md. Check each one matches what was agreed (${result.recorded.length}):\n\n${formatGroup({ findings: result.recorded, projectDirectory })}`,
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
if (result.unfinishedChanges) {
|
|
66
|
+
sections.push(
|
|
67
|
+
`Unfinished changes, from docs/development/coding-standards.md:\n\n${result.unfinishedChanges}`,
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
if (result.failures.length === 0) {
|
|
71
|
+
sections.push(
|
|
72
|
+
"The project follows the code standards, with its recorded exceptions.",
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
return sections.join("\n\n---\n\n");
|
|
76
|
+
};
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
// Reads what the checks need from the project: its files, and the
|
|
2
|
+
// exceptions it has recorded in docs/development/coding-standards.md.
|
|
3
|
+
import { execFileSync } from "node:child_process";
|
|
4
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
|
|
8
|
+
// The installed @activatus/code-standards package: its templates and
|
|
9
|
+
// its docs are what the project is checked against.
|
|
10
|
+
export const PACKAGE_DIRECTORY = path.resolve(
|
|
11
|
+
path.dirname(fileURLToPath(import.meta.url)),
|
|
12
|
+
"../..",
|
|
13
|
+
);
|
|
14
|
+
|
|
15
|
+
export const CODING_STANDARDS_PATH =
|
|
16
|
+
"docs/development/coding-standards.md";
|
|
17
|
+
|
|
18
|
+
const NO_VALUE_WORDS = new Set(["none", "no differences"]);
|
|
19
|
+
|
|
20
|
+
// A recorded exception starts with its standard number:
|
|
21
|
+
// "7. Prettier — skipped", "- 12.1. Constants — changed".
|
|
22
|
+
const STANDARD_NUMBER_PATTERN =
|
|
23
|
+
/^\s*(?:[-*]\s+)?(?:\*\*)?(\d+(?:\.\d+)?)\.\s/;
|
|
24
|
+
|
|
25
|
+
export const readTextFile = ({ projectDirectory, filePath }) => {
|
|
26
|
+
const fullPath = path.join(projectDirectory, filePath);
|
|
27
|
+
return existsSync(fullPath)
|
|
28
|
+
? readFileSync(fullPath, "utf8")
|
|
29
|
+
: undefined;
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
// Git lists the files, so every git ignore rule applies, the same way
|
|
33
|
+
// as the format scripts. Outside git, nothing is listed.
|
|
34
|
+
export const listProjectFiles = ({ projectDirectory }) => {
|
|
35
|
+
try {
|
|
36
|
+
const output = execFileSync(
|
|
37
|
+
"git",
|
|
38
|
+
["ls-files", "--cached", "--others", "--exclude-standard"],
|
|
39
|
+
{ cwd: projectDirectory, encoding: "utf8" },
|
|
40
|
+
);
|
|
41
|
+
return output
|
|
42
|
+
.split("\n")
|
|
43
|
+
.filter((filePath) => filePath.length > 0)
|
|
44
|
+
.filter((filePath) =>
|
|
45
|
+
existsSync(path.join(projectDirectory, filePath)),
|
|
46
|
+
);
|
|
47
|
+
} catch {
|
|
48
|
+
return [];
|
|
49
|
+
}
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
// The text under one "## Heading" of a Markdown file, up to the next
|
|
53
|
+
// "## " heading.
|
|
54
|
+
export const readSection = ({ markdown, heading }) => {
|
|
55
|
+
const lines = markdown.split("\n");
|
|
56
|
+
const startIndex = lines.findIndex(
|
|
57
|
+
(line) => line.trim() === `## ${heading}`,
|
|
58
|
+
);
|
|
59
|
+
if (startIndex === -1) {
|
|
60
|
+
return "";
|
|
61
|
+
}
|
|
62
|
+
const sectionLines = [];
|
|
63
|
+
const linesAfterHeading = lines.slice(startIndex + 1);
|
|
64
|
+
for (const line of linesAfterHeading) {
|
|
65
|
+
if (line.startsWith("## ")) {
|
|
66
|
+
break;
|
|
67
|
+
}
|
|
68
|
+
sectionLines.push(line);
|
|
69
|
+
}
|
|
70
|
+
return sectionLines.join("\n").trim();
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
const hasContent = (sectionText) => {
|
|
74
|
+
const words = sectionText
|
|
75
|
+
.replaceAll(/[".]/g, "")
|
|
76
|
+
.trim()
|
|
77
|
+
.toLowerCase();
|
|
78
|
+
return words.length > 0 && !NO_VALUE_WORDS.has(words);
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
export const readRecordedExceptions = ({ projectDirectory }) => {
|
|
82
|
+
const markdown =
|
|
83
|
+
readTextFile({
|
|
84
|
+
projectDirectory,
|
|
85
|
+
filePath: CODING_STANDARDS_PATH,
|
|
86
|
+
}) ?? "";
|
|
87
|
+
const details = readSection({ markdown, heading: "Details" });
|
|
88
|
+
const standardNumbers = new Set(
|
|
89
|
+
details
|
|
90
|
+
.split("\n")
|
|
91
|
+
.map((line) => STANDARD_NUMBER_PATTERN.exec(line)?.[1])
|
|
92
|
+
.filter(Boolean),
|
|
93
|
+
);
|
|
94
|
+
const componentsSection = readSection({
|
|
95
|
+
markdown,
|
|
96
|
+
heading: "Components for the standards",
|
|
97
|
+
});
|
|
98
|
+
const unfinishedSection = readSection({
|
|
99
|
+
markdown,
|
|
100
|
+
heading: "Unfinished changes",
|
|
101
|
+
});
|
|
102
|
+
return {
|
|
103
|
+
standardNumbers,
|
|
104
|
+
componentsText: componentsSection.toLowerCase(),
|
|
105
|
+
unfinishedChanges: hasContent(unfinishedSection)
|
|
106
|
+
? unfinishedSection
|
|
107
|
+
: undefined,
|
|
108
|
+
};
|
|
109
|
+
};
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
// Runs every check, and separates the findings for standards the
|
|
2
|
+
// project has recorded as skipped or changed.
|
|
3
|
+
import { readFileSync } from "node:fs";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
|
|
6
|
+
import { checkAgentFiles } from "./checkAgentFiles.mjs";
|
|
7
|
+
import { checkComponents } from "./checkComponents.mjs";
|
|
8
|
+
import { checkConfigFiles } from "./checkConfigFiles.mjs";
|
|
9
|
+
import { checkDocs } from "./checkDocs.mjs";
|
|
10
|
+
import { checkRequiredFiles } from "./checkRequiredFiles.mjs";
|
|
11
|
+
import {
|
|
12
|
+
listProjectFiles,
|
|
13
|
+
PACKAGE_DIRECTORY,
|
|
14
|
+
readRecordedExceptions,
|
|
15
|
+
} from "./projectFiles.mjs";
|
|
16
|
+
|
|
17
|
+
const readPackageMajorVersion = () => {
|
|
18
|
+
const packageText = readFileSync(
|
|
19
|
+
path.join(PACKAGE_DIRECTORY, "package.json"),
|
|
20
|
+
"utf8",
|
|
21
|
+
);
|
|
22
|
+
const [majorVersion] = JSON.parse(packageText).version.split(
|
|
23
|
+
".",
|
|
24
|
+
1,
|
|
25
|
+
);
|
|
26
|
+
return Number(majorVersion);
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
export const runChecks = ({ projectDirectory }) => {
|
|
30
|
+
const templatesDirectory = path.join(
|
|
31
|
+
PACKAGE_DIRECTORY,
|
|
32
|
+
"static/templates",
|
|
33
|
+
);
|
|
34
|
+
const standardsDocsDirectory = path.join(PACKAGE_DIRECTORY, "docs");
|
|
35
|
+
const projectFiles = listProjectFiles({ projectDirectory });
|
|
36
|
+
const recordedExceptions = readRecordedExceptions({
|
|
37
|
+
projectDirectory,
|
|
38
|
+
});
|
|
39
|
+
const findings = [
|
|
40
|
+
...checkAgentFiles({
|
|
41
|
+
projectDirectory,
|
|
42
|
+
templatesDirectory,
|
|
43
|
+
packageMajorVersion: readPackageMajorVersion(),
|
|
44
|
+
}),
|
|
45
|
+
...checkConfigFiles({ projectDirectory, templatesDirectory }),
|
|
46
|
+
...checkRequiredFiles({ templatesDirectory, projectFiles }),
|
|
47
|
+
...checkComponents({
|
|
48
|
+
projectDirectory,
|
|
49
|
+
projectFiles,
|
|
50
|
+
standardsDocsDirectory,
|
|
51
|
+
recordedExceptions,
|
|
52
|
+
}),
|
|
53
|
+
...checkDocs({ projectDirectory, projectFiles }),
|
|
54
|
+
];
|
|
55
|
+
const isRecorded = (finding) =>
|
|
56
|
+
recordedExceptions.standardNumbers.has(finding.standard);
|
|
57
|
+
return {
|
|
58
|
+
failures: findings.filter((finding) => !isRecorded(finding)),
|
|
59
|
+
recorded: findings.filter((finding) => isRecorded(finding)),
|
|
60
|
+
unfinishedChanges: recordedExceptions.unfinishedChanges,
|
|
61
|
+
};
|
|
62
|
+
};
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Checks a project against the Activatus Code Standards, and against
|
|
3
|
+
// the exceptions it has recorded in docs/development/coding-standards.md.
|
|
4
|
+
// It reports; it never changes a file.
|
|
5
|
+
//
|
|
6
|
+
// Run it from the project root:
|
|
7
|
+
// node node_modules/@activatus/code-standards/scripts/verifyStandards/verifyStandards.mjs
|
|
8
|
+
//
|
|
9
|
+
// A finding for a standard the project has recorded as skipped or
|
|
10
|
+
// changed is listed as a recorded exception, to check by hand, and does
|
|
11
|
+
// not fail the run.
|
|
12
|
+
import { formatReport } from "./formatReport.mjs";
|
|
13
|
+
import { runChecks } from "./runChecks.mjs";
|
|
14
|
+
|
|
15
|
+
const projectDirectory = process.cwd();
|
|
16
|
+
const result = runChecks({ projectDirectory });
|
|
17
|
+
|
|
18
|
+
console.log(formatReport({ result, projectDirectory }));
|
|
19
|
+
|
|
20
|
+
if (result.failures.length > 0) {
|
|
21
|
+
process.exitCode = 1;
|
|
22
|
+
}
|
|
@@ -168,7 +168,7 @@ Follow these rules in every change:
|
|
|
168
168
|
|
|
169
169
|
**Look before you build a component.** Check the project's `components/ui/`, then the Design System Components in the code standards, then other Activatus projects, then shadcn. Build to the props listed in the Design System Components; never invent new prop names for a component that is already listed. A component in `components/ui/` takes everything through props and never imports from features, services, stores or `app/`.
|
|
170
170
|
|
|
171
|
-
**Lint must pass before you finish.** Run `pnpm lint` and `pnpm test` before finishing any task, and fix every error by changing the code.
|
|
171
|
+
**Lint must pass before you finish.** Run `pnpm lint` and `pnpm test` before finishing any task, and fix every error by changing the code. After setting up or updating the standards, also run `pnpm standards:check`.
|
|
172
172
|
|
|
173
173
|
**Never switch a lint rule off to make an error go away.** Do not add `eslint-disable` comments, edit `eslint.config.mjs` or `eslint.overrides.mjs`, or move files to hide them. The only exceptions are `let` and a type cast, each on a single line with a reason after ` -- `. If a rule seems impossible to satisfy, stop and ask.
|
|
174
174
|
|
|
@@ -8,6 +8,10 @@
|
|
|
8
8
|
|
|
9
9
|
This project follows the Activatus Code Standards, installed as the `@activatus/code-standards` package. The person agreed which standards apply during setup (steps 3 and 4 of `docs/Guides/setup.md` in the package).
|
|
10
10
|
|
|
11
|
+
## Why
|
|
12
|
+
|
|
13
|
+
Every Activatus project follows the same standards, so people and agents can move between projects without relearning the basics. Recording each difference here keeps it visible, and stops the next update from undoing it.
|
|
14
|
+
|
|
11
15
|
## Details
|
|
12
16
|
|
|
13
17
|
[For each standard this project skips or changes, at setup or later: its number and name from the setup list, what is different, why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
|
|
@@ -10,6 +10,10 @@ This project's docs follow the Activatus documentation standard: https://activat
|
|
|
10
10
|
|
|
11
11
|
Every file in `docs/` is a Decision Doc. Read the standard before adding or editing one.
|
|
12
12
|
|
|
13
|
+
## Why
|
|
14
|
+
|
|
15
|
+
One format for every doc, so people and agents always know where to look.
|
|
16
|
+
|
|
13
17
|
## Related
|
|
14
18
|
|
|
15
19
|
- [What Is It](what-is-it.md)
|
|
@@ -81,7 +81,8 @@ const config = [
|
|
|
81
81
|
},
|
|
82
82
|
settings: {
|
|
83
83
|
// Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
|
|
84
|
-
//
|
|
84
|
+
// A project on another React version sets settings.react.version
|
|
85
|
+
// in eslint.overrides.mjs, never here.
|
|
85
86
|
react: { version: "19.0" },
|
|
86
87
|
"import-x/resolver-next": [createTypeScriptImportResolver()],
|
|
87
88
|
},
|
|
@@ -83,7 +83,8 @@ const config = [
|
|
|
83
83
|
},
|
|
84
84
|
settings: {
|
|
85
85
|
// Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
|
|
86
|
-
//
|
|
86
|
+
// A project on another React version sets settings.react.version
|
|
87
|
+
// in eslint.overrides.mjs, never here.
|
|
87
88
|
react: { version: "19.0" },
|
|
88
89
|
"import-x/resolver-next": [createTypeScriptImportResolver()],
|
|
89
90
|
},
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
// Measures every page at every half-screen scroll stop: each element's
|
|
2
|
+
// box and opacity, the element count, the page height and a screenshot.
|
|
3
|
+
// A refactor passes only when every measurement matches the baseline.
|
|
4
|
+
import { expect, type Page, test } from "@playwright/test";
|
|
5
|
+
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
|
|
8
|
+
import { VISUAL_PAGES } from "./visualPages.mjs";
|
|
9
|
+
|
|
10
|
+
const BOX_TOLERANCE_PIXELS = 1;
|
|
11
|
+
const OPACITY_TOLERANCE = 0.02;
|
|
12
|
+
const SCREENSHOT_DIFFERENCE_RATIO = 0.005;
|
|
13
|
+
const SCROLL_STEP_FRACTION = 0.5;
|
|
14
|
+
// The page clock is frozen and moved on by hand, so every run sees the
|
|
15
|
+
// same frames. A timing change between frames is not caught: see the
|
|
16
|
+
// guide's blind spot.
|
|
17
|
+
const FIXED_TIME = new Date("2026-01-01T00:00:00Z");
|
|
18
|
+
const SETTLE_MILLISECONDS = 2000;
|
|
19
|
+
const MAXIMUM_DIFFERENCES_SHOWN = 20;
|
|
20
|
+
|
|
21
|
+
const isUpdatingBaseline = process.env.VISUAL_UPDATE === "true";
|
|
22
|
+
|
|
23
|
+
type ElementMeasurementType = {
|
|
24
|
+
x: number;
|
|
25
|
+
y: number;
|
|
26
|
+
width: number;
|
|
27
|
+
height: number;
|
|
28
|
+
opacity: number;
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
type PageProps = { page: Page };
|
|
32
|
+
|
|
33
|
+
type ScrollStopType = {
|
|
34
|
+
scrollTop: number;
|
|
35
|
+
pageHeight: number;
|
|
36
|
+
elements: Record<string, ElementMeasurementType>;
|
|
37
|
+
};
|
|
38
|
+
|
|
39
|
+
const settlePage = async ({ page }: PageProps) => {
|
|
40
|
+
await page.clock.runFor(SETTLE_MILLISECONDS);
|
|
41
|
+
await page.evaluate(async () => {
|
|
42
|
+
const finiteAnimations = document
|
|
43
|
+
.getAnimations()
|
|
44
|
+
.filter(
|
|
45
|
+
(animation) =>
|
|
46
|
+
animation.effect?.getTiming().iterations !== Infinity,
|
|
47
|
+
);
|
|
48
|
+
for (const animation of finiteAnimations) {
|
|
49
|
+
animation.finish();
|
|
50
|
+
}
|
|
51
|
+
const images = [...document.images];
|
|
52
|
+
await Promise.all(
|
|
53
|
+
images.map((image) => image.decode().catch(() => null)),
|
|
54
|
+
);
|
|
55
|
+
});
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
const measurePage = ({ page }: PageProps) =>
|
|
59
|
+
page.evaluate(() => {
|
|
60
|
+
const describePath = (element: Element): string => {
|
|
61
|
+
const parent = element.parentElement;
|
|
62
|
+
if (!parent) {
|
|
63
|
+
return element.tagName.toLowerCase();
|
|
64
|
+
}
|
|
65
|
+
const position = [...parent.children].indexOf(element) + 1;
|
|
66
|
+
return `${describePath(parent)}>${element.tagName.toLowerCase()}:${position}`;
|
|
67
|
+
};
|
|
68
|
+
const elements = Object.fromEntries(
|
|
69
|
+
[...document.body.querySelectorAll("*")].map((element) => {
|
|
70
|
+
const box = element.getBoundingClientRect();
|
|
71
|
+
return [
|
|
72
|
+
describePath(element),
|
|
73
|
+
{
|
|
74
|
+
x: box.x,
|
|
75
|
+
y: box.y,
|
|
76
|
+
width: box.width,
|
|
77
|
+
height: box.height,
|
|
78
|
+
opacity: Number(getComputedStyle(element).opacity),
|
|
79
|
+
},
|
|
80
|
+
];
|
|
81
|
+
}),
|
|
82
|
+
);
|
|
83
|
+
return {
|
|
84
|
+
scrollTop: window.scrollY,
|
|
85
|
+
pageHeight: document.documentElement.scrollHeight,
|
|
86
|
+
elements,
|
|
87
|
+
};
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
type DescribeDifferencesProps = {
|
|
91
|
+
baseline: ScrollStopType;
|
|
92
|
+
current: ScrollStopType;
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
const describeDifferences = ({
|
|
96
|
+
baseline,
|
|
97
|
+
current,
|
|
98
|
+
}: DescribeDifferencesProps) => {
|
|
99
|
+
const differences: string[] = [];
|
|
100
|
+
if (baseline.pageHeight !== current.pageHeight) {
|
|
101
|
+
differences.push(
|
|
102
|
+
`page height ${baseline.pageHeight} → ${current.pageHeight}`,
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
const baselineKeys = Object.keys(baseline.elements);
|
|
106
|
+
const currentKeys = Object.keys(current.elements);
|
|
107
|
+
if (baselineKeys.length !== currentKeys.length) {
|
|
108
|
+
differences.push(
|
|
109
|
+
`element count ${baselineKeys.length} → ${currentKeys.length}`,
|
|
110
|
+
);
|
|
111
|
+
}
|
|
112
|
+
for (const key of baselineKeys) {
|
|
113
|
+
const before = baseline.elements[key];
|
|
114
|
+
const after = current.elements[key];
|
|
115
|
+
if (!after) {
|
|
116
|
+
differences.push(`${key} is missing`);
|
|
117
|
+
continue;
|
|
118
|
+
}
|
|
119
|
+
const isBoxMoved = (["x", "y", "width", "height"] as const).some(
|
|
120
|
+
(side) =>
|
|
121
|
+
Math.abs(before[side] - after[side]) > BOX_TOLERANCE_PIXELS,
|
|
122
|
+
);
|
|
123
|
+
const isOpacityChanged =
|
|
124
|
+
Math.abs(before.opacity - after.opacity) > OPACITY_TOLERANCE;
|
|
125
|
+
if (isBoxMoved || isOpacityChanged) {
|
|
126
|
+
differences.push(`${key} moved or faded`);
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return differences.slice(0, MAXIMUM_DIFFERENCES_SHOWN);
|
|
130
|
+
};
|
|
131
|
+
|
|
132
|
+
const toFileName = (pagePath: string) =>
|
|
133
|
+
pagePath === "/" ? "home" : pagePath.replaceAll(/[^a-z0-9]+/gi, "-");
|
|
134
|
+
|
|
135
|
+
for (const pagePath of VISUAL_PAGES) {
|
|
136
|
+
test(`${pagePath} looks exactly as before`, async ({
|
|
137
|
+
page,
|
|
138
|
+
}, testInfo) => {
|
|
139
|
+
await page.clock.install({ time: FIXED_TIME });
|
|
140
|
+
await page.goto(pagePath);
|
|
141
|
+
await settlePage({ page });
|
|
142
|
+
|
|
143
|
+
const viewportHeight = page.viewportSize()?.height ?? 0;
|
|
144
|
+
const scrollStep = viewportHeight * SCROLL_STEP_FRACTION;
|
|
145
|
+
const stops: ScrollStopType[] = [];
|
|
146
|
+
// eslint-disable-next-line no-restricted-syntax -- the scroll position moves down the page one stop at a time
|
|
147
|
+
let scrollTop = 0;
|
|
148
|
+
const pageHeight = await page.evaluate(
|
|
149
|
+
() => document.documentElement.scrollHeight,
|
|
150
|
+
);
|
|
151
|
+
while (scrollTop <= pageHeight - viewportHeight) {
|
|
152
|
+
await page.evaluate(
|
|
153
|
+
(top) => window.scrollTo(0, top),
|
|
154
|
+
scrollTop,
|
|
155
|
+
);
|
|
156
|
+
await settlePage({ page });
|
|
157
|
+
stops.push(await measurePage({ page }));
|
|
158
|
+
await expect(page).toHaveScreenshot(
|
|
159
|
+
`${toFileName(pagePath)}-${stops.length}.png`,
|
|
160
|
+
{ maxDiffPixelRatio: SCREENSHOT_DIFFERENCE_RATIO },
|
|
161
|
+
);
|
|
162
|
+
scrollTop += scrollStep;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
// Saved beside the screenshots: baseline/<project>/<page>.json
|
|
166
|
+
const baselinePath = testInfo.snapshotPath(
|
|
167
|
+
`${toFileName(pagePath)}.json`,
|
|
168
|
+
);
|
|
169
|
+
if (isUpdatingBaseline) {
|
|
170
|
+
mkdirSync(path.dirname(baselinePath), { recursive: true });
|
|
171
|
+
writeFileSync(baselinePath, JSON.stringify(stops));
|
|
172
|
+
return;
|
|
173
|
+
}
|
|
174
|
+
const baseline: ScrollStopType[] = JSON.parse(
|
|
175
|
+
readFileSync(baselinePath, "utf8"),
|
|
176
|
+
);
|
|
177
|
+
expect(stops.length, "number of scroll stops").toBe(
|
|
178
|
+
baseline.length,
|
|
179
|
+
);
|
|
180
|
+
const differences = baseline.flatMap((baselineStop, index) =>
|
|
181
|
+
describeDifferences({
|
|
182
|
+
baseline: baselineStop,
|
|
183
|
+
current: stops[index],
|
|
184
|
+
}).map((difference) => `stop ${index + 1}: ${difference}`),
|
|
185
|
+
);
|
|
186
|
+
expect(differences).toEqual([]);
|
|
187
|
+
});
|
|
188
|
+
}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
// The regression check: proves a refactor changed nothing visible.
|
|
2
|
+
// See "Regression Checks for Refactors" in the code standards.
|
|
3
|
+
import { defineConfig } from "@playwright/test";
|
|
4
|
+
|
|
5
|
+
// The baseline always comes from the live production site, never from
|
|
6
|
+
// the branch being tested. Set it before running test:visual:update.
|
|
7
|
+
const PRODUCTION_URL = process.env.VISUAL_PRODUCTION_URL;
|
|
8
|
+
const isUpdatingBaseline = process.env.VISUAL_UPDATE === "true";
|
|
9
|
+
// The project's own production build, on a port of its own.
|
|
10
|
+
const LOCAL_PORT = 3100;
|
|
11
|
+
const LOCAL_URL = `http://localhost:${LOCAL_PORT}`;
|
|
12
|
+
const SERVER_START_TIMEOUT_MILLISECONDS = 300_000;
|
|
13
|
+
|
|
14
|
+
if (isUpdatingBaseline && !PRODUCTION_URL) {
|
|
15
|
+
throw new Error(
|
|
16
|
+
"Set VISUAL_PRODUCTION_URL to the live site before updating the baseline.",
|
|
17
|
+
);
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** @type {import("@playwright/test").PlaywrightTestConfig} */
|
|
21
|
+
const config = {
|
|
22
|
+
testDir: ".",
|
|
23
|
+
testMatch: "*.visual.ts",
|
|
24
|
+
snapshotPathTemplate: "{testDir}/baseline/{projectName}/{arg}{ext}",
|
|
25
|
+
fullyParallel: true,
|
|
26
|
+
use: {
|
|
27
|
+
baseURL: isUpdatingBaseline ? PRODUCTION_URL : LOCAL_URL,
|
|
28
|
+
},
|
|
29
|
+
projects: [
|
|
30
|
+
{
|
|
31
|
+
name: "desktop",
|
|
32
|
+
use: { viewport: { width: 1440, height: 900 } },
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
name: "tablet",
|
|
36
|
+
use: { viewport: { width: 768, height: 1024 } },
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
name: "mobile",
|
|
40
|
+
use: {
|
|
41
|
+
viewport: { width: 390, height: 844 },
|
|
42
|
+
isMobile: true,
|
|
43
|
+
hasTouch: true,
|
|
44
|
+
},
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
name: "desktopReducedMotion",
|
|
48
|
+
use: {
|
|
49
|
+
viewport: { width: 1440, height: 900 },
|
|
50
|
+
contextOptions: { reducedMotion: "reduce" },
|
|
51
|
+
},
|
|
52
|
+
},
|
|
53
|
+
],
|
|
54
|
+
// Rebuilt before every run, so a stale build is never measured.
|
|
55
|
+
webServer: isUpdatingBaseline
|
|
56
|
+
? undefined
|
|
57
|
+
: {
|
|
58
|
+
command: `pnpm build && pnpm start --port ${LOCAL_PORT}`,
|
|
59
|
+
url: LOCAL_URL,
|
|
60
|
+
reuseExistingServer: false,
|
|
61
|
+
timeout: SERVER_START_TIMEOUT_MILLISECONDS,
|
|
62
|
+
},
|
|
63
|
+
};
|
|
64
|
+
|
|
65
|
+
export default defineConfig(config);
|