test(features): 기능 추가 테스트에 무효화 topic을 넣고 폴더 밖 수정 표를 고친다 (1101/16-01)
문제
- starter-experience.md "Adding a feature"의 폴더 밖 수정 표가 실제와 다르다.
라우트마다 필요한 수동 a11y 기록이 없고, 어느 검사가 실패하는지도 적지
않는다.
- 이 주장을 지키는 second-api-feature-registries 테스트는 무효화 topic이
없는 기능만 넣는다. 그래서 topic 추가가 기준선 재승인을 요구하던 결함을
보지 못했다.
- http-operation-v2-v3-parity 테스트는 스키마 ID "NoRequest"를 "입력 없음"
표시로 고정해 쓴다. 스키마 ID는 전역이라 두 번째 기능은 다른 이름(예:
OrderNoRequest)을 써야 한다. 그러면 이 테스트가 그 기능의 path·request
스키마를 둘 다 입력으로 세어 실패한다(16-02 작업자 발견).
고른 방법
- 표를 지금 코드 기준으로 다시 썼다. 열은 파일 / 언제 / 없으면 무엇이
실패하나. 리뷰 실험 E의 ①~⑨ 중 이번 라운드 앞 커밋이 없앤 것은 뺐다:
governance allowlist(0929/07-03), 기준선 재승인(앞 커밋, 결정 1), README·
체크리스트 route ID 목록(14-05), 인증 프로필 이름(16-03, EXTERNAL_BEARER
재사용), MSW 카탈로그와 무관한 테스트 3개(16-02). runtime-adapters.ts는
product-composition.ts로 바뀌었다(09-02).
- 남은 것: context 선언, 라우트별 a11y 기록, 경로 파라미터가
:resourceId가 아니거나 빈 배열 응답으로 그려지지 않는 페이지의 e2e a11y
spec, 제품 capability·인증 프로필·설정 키(제품 소유 파일 2개), 선택인
FEATURE_OVERRIDES, 계약 패키지를 npm 의존성으로 들일 때의 의존성 검토
증거. 계약 출처(EXTERNAL_PACKAGE)는 기능 계약의 contractPackages에
선언하므로 폴더 밖 수정이 아니다.
- 표 아래에 레지스트리 추가는 기준선을 바꾸지 않는다는 것, 전역 ID에 기능
접두어를 붙인다는 것, 기능의 MSW 시나리오는 createHttpScenarioHandler로
만든다는 것을 적었다.
- second-api 기능에 무효화 topic·namespace·edge·topicVersion을 더하고,
무효화 그래프 변경 3건이 additive인지 단언한다. 라우트는 0929/07-03이
이미 넣었으므로(SECOND_ITEM_LIST) 더하지 않았다.
- second-api의 통과 codec은 검증을 생략하므로 1101/07-03의
unvalidatedPayload로 만든다.
- parity 테스트는 V2 행에서 입력이 있는 쪽을 읽는다. path 스키마는
pathParameterNames가 있을 때, request 스키마는 requestSource가 "none"이
아닐 때 입력이다. 둘 다 없으면 행의 requestSchema(그 기능의 빈 입력
스키마)를 기대한다.
버린 대안
- 표만 고치기(리뷰 대안 a): 테스트가 계속 좁은 모양만 증명한다.
- 참조 기능의 NoRequest를 ReferenceNoRequest로 바꾸기: FE-REG-API 행의
requestSchema·pathSchema가 바뀌어 기준선 재승인이 필요하고 범위 밖이다.
- parity 테스트에서 이름 끝이 NoRequest인 스키마를 빈 입력으로 보기: 이름
관례에 기대는 규칙이라 다른 이름을 쓰면 다시 깨진다.
- second-api 기능에 V3 기여를 넣어 parity를 그 사본에서 돌리기:
1101/07-02(3c31576)가 같은 이유로 버렸다(사본에서는 check:registries만
돈다).
위험·한계
- e2e a11y spec 행은 코드(:resourceId만 치환, 모든 API에 [] 응답)를 읽고
적었다. 다른 파라미터를 가진 라우트로 test:a11y를 실제로 돌려 보지는
않았다.
- 의존성 행은 직접 production 의존성을 더하면 generate:supply-chain이
"high-risk dependency missing review"로 실패한다는 코드를 읽고 적었다.
실행하지 않았다.
- 초기 JS 예산은 표에 넣지 않았다. 기능 하나가 초기 JS를 늘리지만 예산은
기능이 고칠 파일이 아니다. 이번에 측정하지 않았다.
- 표의 완전성은 테스트가 지키지 않는다. 생성 명령(U7)의 게이트 실행이
이 표를 실행으로 확인할 자리다.
검증
- RED: 넓힌 second-api 테스트를 결정 1 전 분류기(HEAD~1의
registry-compatibility.ts)로 돌리면 실패한다. check-registries stderr
"breaking change missing evidence:
FE-REG-QUERY-INVALIDATION:invalidation-graph:{edges,namespaces,topics}:field-changed".
parity 테스트는 참조 기능의 NoRequest를 ReferenceNoRequest로 바꾼
변이(커밋 안 함)에서 "LIST_REFERENCE_RESOURCES: V2 declares both a path
and a request schema" 실패.
- GREEN: second-api 1/1, 같은 변이에서 parity 2/2, 변이 없이 2/2 통과.
V3 inputValidator schemaId를 바꾼 변이는 여전히 inputSchema 차이로
실패한다.
- 회귀: tests/unit 178파일 중 177 통과. 실패 1건 feature-shape-growth(초기
JS 증가 1 KiB 초과)는 기준 커밋에서도 실패한다. tsc app·test rc=0, 바꾼
테스트 eslint rc=0, verify-documentation-readiness PASS_SCOPED,
check-registries PASS(compatibility=none).
- 미실행: check:architecture(pnpm 필요), test:a11y, test:sample-removal.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-01, 8.1, 8.2
This commit is contained in:
@@ -171,15 +171,19 @@ selected app. Every build and check script runs it first; run it yourself with
|
||||
7. Run `corepack pnpm test:sample-removal -- --feature=<feature id>` to prove
|
||||
the product still builds and passes its gates without the feature.
|
||||
|
||||
Files outside the feature directory:
|
||||
Files outside the feature directory. Everything else a feature needs is in
|
||||
`src/features/<feature>/` and `tests/features/<feature>/`.
|
||||
|
||||
| File | Change |
|
||||
| --- | --- |
|
||||
| `src/.generated/*` | regenerated automatically |
|
||||
| `src/contexts/<context>/context-module.ts` | only when the feature needs a new context |
|
||||
| `config/runtime/<profile>.json` | optional `FEATURE_OVERRIDES` entry to switch the feature off |
|
||||
| `src/bootstrap/product-composition.ts` (product-owned) | only when `needs` names a capability the template does not build: augment `FeaturePlatformCapabilities` and return the capability here. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too |
|
||||
| `src/contracts/product-contracts.ts` (product-owned) | only for a product auth profile or a product runtime-config key |
|
||||
| File | When | What fails without it |
|
||||
| --- | --- | --- |
|
||||
| `src/.generated/*` | never by hand: every build and check script regenerates it | — |
|
||||
| `src/contexts/<context>/context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature <id> belongs to undeclared context <context>` |
|
||||
| `artifacts/tests/a11y-manual/<ROUTE_ID>.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release |
|
||||
| `tests/e2e/accessibility.spec.ts` | a route path has a parameter other than `:resourceId`, or a protected page cannot render while every API answers `[]` | `test:a11y` (FE-GATE-009): the spec fills in only `:resourceId` and answers every API with `[]` |
|
||||
| `src/bootstrap/product-composition.ts` (product-owned) | `needs` names a capability the template does not build: augment `FeaturePlatformCapabilities` and return the capability here. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too | `check:types`; at runtime `feature <id> needs <capability>, which the host did not provide` |
|
||||
| `src/contracts/product-contracts.ts` (product-owned) | a product auth profile or a product runtime-config key | auth profile: every gate that loads the operation, with `REST security profiles are incoherent for <operationId>: unknown authProfileId …`. Config key: `check:types` where it is read |
|
||||
| `config/runtime/<profile>.json` | optional: a `FEATURE_OVERRIDES` entry switches the feature off | nothing |
|
||||
| `package.json`, the lockfile, `config/security/dependency-change-evidence.json` | the contract contribution imports a generated `@org-contracts/*` package as a production dependency | `generate:supply-chain` (in `check:bundle`): `high-risk dependency missing review: add:<package>` |
|
||||
|
||||
The central catalogs (`src/features/installed-*.ts`) and the registry
|
||||
governance file do not change: consumer directories there are globs over every
|
||||
@@ -187,9 +191,20 @@ feature (`src/features/*/adapters`, `config/contracts/registry-governance.json`)
|
||||
A route's params/search schema ids are checked against the schemas the feature
|
||||
registers, and its `loadingSurface` only has to be a kebab-case name, so a
|
||||
route with its own schema and loading surface needs no governance edit either.
|
||||
The registry baseline does not change either. New routes, API operations,
|
||||
schemas and invalidation topics, namespaces and edges are additive registry
|
||||
changes; `update:registry-baseline` or breaking evidence is needed only to
|
||||
remove or change a row or graph item.
|
||||
`tests/unit/second-api-feature-registries.test.ts` adds such a feature (an API
|
||||
operation and a route with its own search schema and loading surface) to a copy
|
||||
of the repository and runs `check:registries` on it.
|
||||
operation, a route with its own search schema and loading surface, and an
|
||||
invalidation topic) to a copy of the repository and runs `check:registries` on
|
||||
it.
|
||||
|
||||
Schema, operation, mapper, route and chunk ids and invalidation topics are
|
||||
global. Prefix them with the feature; `NoRequest` already belongs to the
|
||||
sample. MSW scenarios for the feature's own operations come from
|
||||
`createHttpScenarioHandler` (`tests/mocks/handlers/http-scenarios.ts`) with
|
||||
the feature's installed contract; the shared scenario catalog does not change.
|
||||
|
||||
### Before shipping
|
||||
|
||||
|
||||
@@ -30,20 +30,22 @@ const v2Rows = (Object.values(API_OPERATIONS) as readonly ApiOperation[]).filter
|
||||
);
|
||||
|
||||
// V3 validates the whole canonical input with one schema; V2 splits it into a
|
||||
// path schema and a request (search or body) schema, "NoRequest" when absent.
|
||||
// An operation that needs both has no rule yet and fails here until one is
|
||||
// written down.
|
||||
const NO_REQUEST = "NoRequest";
|
||||
|
||||
// path schema and a request (search or body) schema. The row says which of
|
||||
// the two carry input: path parameters, and a request source other than
|
||||
// "none". The other one names the feature's empty-input schema, whatever the
|
||||
// feature calls it (schema ids are global, so a second feature cannot reuse
|
||||
// the sample's `NoRequest`). An operation that needs both has no rule yet and
|
||||
// fails here until one is written down.
|
||||
function v2InputSchema(row: RestOperationV2): string {
|
||||
const declared = [row.pathSchema, row.requestSchema].filter(
|
||||
(schemaId) => schemaId !== NO_REQUEST,
|
||||
);
|
||||
const declared = [
|
||||
...(row.pathParameterNames.length > 0 ? [row.pathSchema] : []),
|
||||
...(row.requestSource !== "none" ? [row.requestSchema] : []),
|
||||
];
|
||||
expect(
|
||||
declared.length,
|
||||
`${row.operationId}: V2 declares both a path and a request schema; decide which V3 input schema matches them`,
|
||||
).toBeLessThanOrEqual(1);
|
||||
return declared[0] ?? NO_REQUEST;
|
||||
return declared[0] ?? row.requestSchema;
|
||||
}
|
||||
|
||||
describe("HTTP operation V2 rows and V3 descriptors", () => {
|
||||
|
||||
@@ -16,25 +16,32 @@ import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.t
|
||||
* 0929/07-03. The feature also owns a route with its own search schema and its
|
||||
* own loading surface name, the values FE-REG-ROUTE once kept in a central
|
||||
* allowlist.
|
||||
* 1101/16-01. And an invalidation topic, namespace and edge: every feature
|
||||
* with server state has them, and adding them is additive.
|
||||
*/
|
||||
const FEATURE_ID = "second-api-feature";
|
||||
const CONTEXT_ID = "second-api-context";
|
||||
const TOPIC_ID = "qinv.01kb3m8q2v6t4r9s1n5p7c0w";
|
||||
|
||||
const FEATURE_CONTRACT = `import { defineRestOperation } from "../../../contracts/api-operations.ts";
|
||||
import type { InstalledBoundaryMapper } from "../../../contracts/boundary-mapper.ts";
|
||||
import { mappingFailure, mappingSuccess } from "../../../contracts/boundary-mapper.ts";
|
||||
import { unvalidatedPayload } from "../../../contracts/external-contract-runtime.ts";
|
||||
import { defineQueryInvalidationTopic } from "../../../contracts/query-invalidation.ts";
|
||||
import { defineQueryNamespaceIdentity } from "../../../contracts/query-keys.ts";
|
||||
import { runtimeSchemaCodecFromValidator } from "../../../contracts/schema-registry.ts";
|
||||
|
||||
const OWNER = "feature-frontend-second-api-feature";
|
||||
const SECOND_ITEM_TOPIC = defineQueryInvalidationTopic("${TOPIC_ID}");
|
||||
const SECOND_ITEM_NAMESPACE = defineQueryNamespaceIdentity("second-item", 1);
|
||||
|
||||
const schema = (schemaId: string, boundary: string, direction: string) =>
|
||||
Object.freeze({ schemaId, boundary, owner: OWNER, runtime: "zod", schemaVersion: 1, direction });
|
||||
|
||||
const codec = (schemaId: string) =>
|
||||
runtimeSchemaCodecFromValidator({
|
||||
schemaId,
|
||||
safeParse: (value: unknown) => Object.freeze({ success: true as const, data: value }),
|
||||
});
|
||||
runtimeSchemaCodecFromValidator(
|
||||
unvalidatedPayload(schemaId, "registry fixture: only check-registries reads it"),
|
||||
);
|
||||
|
||||
const ROUTES = Object.freeze({
|
||||
SECOND_ITEM_LIST: Object.freeze({
|
||||
@@ -64,8 +71,16 @@ export const SECOND_API_CONTRACT = Object.freeze({
|
||||
searchCodec: "SecondItemListQuery",
|
||||
}),
|
||||
}),
|
||||
invalidation: { topics: Object.freeze([]), namespaces: Object.freeze([]), edges: Object.freeze([]) },
|
||||
topicVersions: Object.freeze([]),
|
||||
invalidation: Object.freeze({
|
||||
topics: Object.freeze([SECOND_ITEM_TOPIC]),
|
||||
namespaces: Object.freeze([SECOND_ITEM_NAMESPACE]),
|
||||
edges: Object.freeze([
|
||||
Object.freeze({ topicId: SECOND_ITEM_TOPIC, namespace: SECOND_ITEM_NAMESPACE }),
|
||||
]),
|
||||
}),
|
||||
topicVersions: Object.freeze([
|
||||
Object.freeze({ topicId: SECOND_ITEM_TOPIC, topicVersion: 1 }),
|
||||
]),
|
||||
contractPackages: Object.freeze([]),
|
||||
} as const);
|
||||
|
||||
@@ -175,7 +190,7 @@ afterAll(async () => {
|
||||
await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true })));
|
||||
});
|
||||
|
||||
describe("adding a feature with an API operation and a route (F-3, 09-07, 0929/07-03)", () => {
|
||||
describe("adding a feature with an API operation, a route and an invalidation topic (F-3, 09-07, 0929/07-03, 1101/16-01)", () => {
|
||||
it("passes check-registries without edits outside the feature and its context", async () => {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "second-api-feature-"));
|
||||
roots.push(root);
|
||||
@@ -220,7 +235,10 @@ describe("adding a feature with an API operation and a route (F-3, 09-07, 0929/0
|
||||
expect(checked.status).toBe(0);
|
||||
const report = JSON.parse(
|
||||
await readFile(path.join(root, "artifacts/quality/registries.json"), "utf8"),
|
||||
) as { registries: { registryId: string; rows: Record<string, unknown> }[] };
|
||||
) as {
|
||||
registries: { registryId: string; rows: Record<string, unknown> }[];
|
||||
compatibility: { changes: { registryId: string; field: string; impact: string }[] };
|
||||
};
|
||||
const api = report.registries.find(({ registryId }) => registryId === "FE-REG-API");
|
||||
expect(Object.keys(api?.rows ?? {})).toContain("GET_SECOND_ITEM");
|
||||
const routes = report.registries.find(({ registryId }) => registryId === "FE-REG-ROUTE");
|
||||
@@ -228,5 +246,20 @@ describe("adding a feature with an API operation and a route (F-3, 09-07, 0929/0
|
||||
searchSchema: "SecondItemListQuery",
|
||||
loadingSurface: "second-item-list",
|
||||
});
|
||||
const graph = report.registries.find(
|
||||
({ registryId }) => registryId === "FE-REG-QUERY-INVALIDATION",
|
||||
);
|
||||
expect(graph?.rows["invalidation-graph"]).toMatchObject({
|
||||
topics: expect.arrayContaining([TOPIC_ID]),
|
||||
});
|
||||
expect(
|
||||
report.compatibility.changes
|
||||
.filter(({ registryId }) => registryId === "FE-REG-QUERY-INVALIDATION")
|
||||
.map(({ field, impact }) => [field, impact]),
|
||||
).toEqual([
|
||||
["edges", "additive"],
|
||||
["namespaces", "additive"],
|
||||
["topics", "additive"],
|
||||
]);
|
||||
}, 60_000);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user