Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

ci: a changed knowledge record alone runs no browser accessibility spec (#8674)

Cindy Zhang683320c5e051
diff --git a/.github/scripts/a11y-pr-contracts.mjs b/.github/scripts/a11y-pr-contracts.mjs
index c177222229..abbb22332d 100644
--- a/.github/scripts/a11y-pr-contracts.mjs
+++ b/.github/scripts/a11y-pr-contracts.mjs
@@ -26,7 +26,9 @@
*
* A spec with no `always`, `audit`, or `release-only` line is scoped: a PR runs
* it when it changes the spec, the spec's component folder, or a component the
- * spec is named after, or matches one of its `scope` tokens. A token starting
+ * spec is named after, or matches one of its `scope` tokens. A changed
+ * knowledge record (`*.spec.md`) counts toward neither the folder nor a path
+ * token: no browser renders it. A token starting
* with `^` is a regular expression over changed paths; any other token is a
* package-qualified component (`core/Selector`, `richtext/*`) matched against
* the PR's component scope.
@@ -244,6 +246,9 @@ export function selectSpecs({
title,
}) {
const audited = auditedComponents(title);
+ // A knowledge record (`<Name>.spec.md`) is Markdown no browser renders, so a
+ // changed record selects no spec by its folder or a path token.
+ const rendered = changedPaths?.filter(p => !isKnowledgeRecord(p));
const selected = [];
for (const {file, routing} of specs) {
const reason = (() => {
@@ -259,7 +264,7 @@ export function selectSpecs({
if (changedPaths.includes(file)) return 'spec changed';
const owners = specOwners(file);
for (const prefix of owners.prefixes) {
- const hit = changedPaths.find(p => p.startsWith(prefix));
+ const hit = rendered.find(p => p.startsWith(prefix));
if (hit) return `changed ${hit}`;
}
for (const component of owners.components) {
@@ -268,7 +273,7 @@ export function selectSpecs({
for (const token of routing.scope) {
if (token.startsWith('^')) {
const pattern = new RegExp(token);
- const hit = changedPaths.find(p => pattern.test(p));
+ const hit = rendered.find(p => pattern.test(p));
if (hit) return `changed ${hit}`;
} else if (componentMatches(token, components)) {
return `component ${token}`;
@@ -281,6 +286,46 @@ export function selectSpecs({
return selected;
}
+/**
+ * Path segments that never hold knowledge records. Mirrors
+ * `IGNORED_COMPONENT_KNOWLEDGE_SEGMENTS` in `knowledge-paths.cjs` (a test
+ * keeps them equal); copied because this runner uses only Node built-ins.
+ */
+export const IGNORED_RECORD_SEGMENTS = new Set([
+ '__fixtures__',
+ '__generated__',
+ '__snapshots__',
+ '__tests__',
+ 'build',
+ 'coverage',
+ 'dist',
+ 'fixtures',
+ 'generated',
+ 'node_modules',
+ 'test',
+ 'test-utils',
+ 'tests',
+]);
+
+/**
+ * Whether a changed path is a knowledge record: Markdown, never rendered. A
+ * hidden `*.spec.md`, one under a hidden, fixture, test, generated,
+ * build-output, coverage, or dependency folder, or one named
+ * `*.generated.spec.md`, is not a record (`architecture:knowledge-contracts` INV27), so it still selects specs.
+ * @param {string} file
+ */
+export function isKnowledgeRecord(file) {
+ if (!file.endsWith('.spec.md') || file.endsWith('.generated.spec.md')) {
+ return false;
+ }
+ return !file
+ .split('/')
+ .some(
+ segment =>
+ segment.startsWith('.') || IGNORED_RECORD_SEGMENTS.has(segment),
+ );
+}
+
/** @param {{suites?: object[]}} listing Playwright JSON reporter output (`--list`). */
export function listedFiles(listing) {
const files = new Set();
diff --git a/.github/scripts/a11y-pr-contracts.test.mjs b/.github/scripts/a11y-pr-contracts.test.mjs
index 68fea8c57b..a7d3ebf2f1 100644
--- a/.github/scripts/a11y-pr-contracts.test.mjs
+++ b/.github/scripts/a11y-pr-contracts.test.mjs
@@ -19,6 +19,8 @@ import {
kebab,
planFor,
parseRouting,
+ IGNORED_RECORD_SEGMENTS,
+ isKnowledgeRecord,
selectSpecs,
specOwners,
} from './a11y-pr-contracts.mjs';
@@ -202,6 +204,39 @@ describe('selectSpecs', () => {
).toEqual([]);
});
+ it('runs no spec for a changed knowledge record alone', () => {
+ const record = 'packages/core/src/Chat/ChatLayout.spec.md';
+ expect(pr(all, {changedPaths: [record]})).toEqual([always.file]);
+ const pattern = spec(
+ 'internal/a11y-spec/src/patterns/accordion.chromium.spec.ts',
+ ['// @pr-a11y scope ^packages/core/src/Collapsible/'],
+ );
+ expect(
+ pr([pattern], {
+ changedPaths: ['packages/core/src/Collapsible/Collapsible.spec.md'],
+ }),
+ ).toEqual([]);
+ // Code beside the record still selects the spec.
+ expect(
+ pr(all, {
+ changedPaths: [record, 'packages/core/src/Chat/ChatLayout.tsx'],
+ }),
+ ).toEqual([always.file, scoped.file]);
+ });
+
+ it('still runs a spec for a fixture, test, or generated .spec.md', () => {
+ for (const file of [
+ 'packages/core/src/Chat/__fixtures__/ChatLayout.spec.md',
+ 'packages/core/src/Chat/__tests__/ChatLayout.spec.md',
+ 'packages/core/src/Chat/ChatLayout.generated.spec.md',
+ ]) {
+ expect(pr(all, {changedPaths: [file]}), file).toEqual([
+ always.file,
+ scoped.file,
+ ]);
+ }
+ });
+
it('runs every scoped spec when the changed files are unknown', () => {
expect(pr(all, {changedPaths: null})).toEqual([
always.file,
@@ -460,3 +495,28 @@ describe('repository specs', () => {
}
});
});
+
+describe('isKnowledgeRecord', () => {
+ it('skips the same folders as the knowledge record discovery', async () => {
+ const {IGNORED_COMPONENT_KNOWLEDGE_SEGMENTS} =
+ await import('./knowledge-paths.cjs');
+ expect([...IGNORED_RECORD_SEGMENTS].sort()).toEqual(
+ [...IGNORED_COMPONENT_KNOWLEDGE_SEGMENTS].sort(),
+ );
+ });
+
+ it('treats a component record as a record and its fixtures as not', () => {
+ expect(isKnowledgeRecord('packages/core/src/Chat/ChatLayout.spec.md')).toBe(
+ true,
+ );
+ expect(
+ isKnowledgeRecord('packages/core/src/Chat/.hidden/ChatLayout.spec.md'),
+ ).toBe(false);
+ expect(
+ isKnowledgeRecord('packages/core/src/Collapsible/.Collapsible.spec.md'),
+ ).toBe(false);
+ expect(isKnowledgeRecord('packages/core/src/Chat/ChatLayout.tsx')).toBe(
+ false,
+ );
+ });
+});
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f04104bcd5..324c208e91 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -517,8 +517,10 @@ and CI picks it up:
A browser spec runs on a pull request when the PR changes the spec, its
component folder, or the component it is named after (`ChatSendButton.a11y.chromium.spec.ts`
-belongs to `core/ChatSendButton`). Routing lines in the spec's header comment
-change that, and the runner rejects any other value:
+belongs to `core/ChatSendButton`). A changed knowledge record (`<Name>.spec.md`)
+counts toward neither the folder nor a path token, since no browser renders it.
+Routing lines in the spec's header comment change that, and the runner rejects
+any other value:
```ts
// @pr-a11y always every PR that changes components