docs(storybook): render MDX tables + add i18n & testing-strategy docs/skill
- fix: wire remark-gfm into addon-docs so GFM pipe tables in *.mdx render (previously raw text in cibg-gaps/layers/atomic-design docs) - add src/docs/i18n.mdx (Foundations/Internationalization): the $localize locale seam + how to test languages without coupling to copy - add src/docs/testing.mdx (Foundations/Testing strategy): per-layer spec matrix, house style, Storybook a11y gate, GREEN gate - add .claude/skills/test-strategy skill Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,93 @@
|
||||
import { Meta } from '@storybook/addon-docs/blocks';
|
||||
|
||||
<Meta title="Foundations/Internationalization" />
|
||||
|
||||
# Internationalization (the locale seam)
|
||||
|
||||
Every user-visible string goes through Angular's first-party **`$localize`** — no
|
||||
third-party i18n library. The source locale is **`nl`**; a second locale is a
|
||||
**translation file, not a code change**. That's the seam: adding English touched
|
||||
`src/locale/messages.en.xlf`, not the components.
|
||||
|
||||
## How it's wired
|
||||
|
||||
| Piece | Where | What |
|
||||
| --- | --- | --- |
|
||||
| Source locale | `angular.json` → `i18n.sourceLocale` | `nl` — the language the code is written in |
|
||||
| Locales | `angular.json` → `i18n.locales.en` | points at `src/locale/messages.en.xlf` |
|
||||
| Missing-translation policy | `angular.json` → `i18nMissingTranslation` | `error` — a missing `<target>` fails the build |
|
||||
| Runtime global | `angular.json` → `polyfills` | `@angular/localize/init` provides `$localize` |
|
||||
| English build/serve | `angular.json` → `configurations.en` | `ng build --configuration=en`, `ng serve --configuration=en` |
|
||||
|
||||
Locale switching is **build-time**, not runtime: each locale is its own bundle. There is
|
||||
no in-app language picker (out of scope for the POC).
|
||||
|
||||
## Authoring copy
|
||||
|
||||
Two forms, same custom-id rule. The id is **stable** and shaped `@@<context>.<key>`, so
|
||||
translations survive copy edits.
|
||||
|
||||
**In TS logic / value objects — tagged template:**
|
||||
|
||||
```ts
|
||||
// src/app/registratie/domain/value-objects/postcode.ts
|
||||
return err($localize`:@@validation.postcode:Voer een geldige postcode in, bijv. 1234 AB.`);
|
||||
```
|
||||
|
||||
With placeholders (named, so translators can reorder):
|
||||
|
||||
```ts
|
||||
$localize`:@@aanvraag.row.ingediend:ingediend op ${formatDatumNl(a.submittedAt)}:datum:`;
|
||||
```
|
||||
|
||||
**In inline component templates — the `i18n` attribute:**
|
||||
|
||||
```html
|
||||
<!-- src/app/auth/ui/login-form/login-form.component.ts -->
|
||||
<app-button type="submit" i18n="@@login.submit">Inloggen met DigiD</app-button>
|
||||
```
|
||||
|
||||
**Shared/English components never hardcode Dutch.** They expose copy as `input()`s with
|
||||
localizable defaults; the domain caller may override. See
|
||||
`shared/ui/async/async.component.ts`:
|
||||
|
||||
```ts
|
||||
errorText = input($localize`:@@async.error:Er ging iets mis bij het laden van de gegevens.`);
|
||||
```
|
||||
|
||||
## Extract & translate loop
|
||||
|
||||
```bash
|
||||
npm run extract-i18n # ng extract-i18n → src/locale/messages.xlf (source, nl)
|
||||
```
|
||||
|
||||
Then a translator fills `<target>`s in `src/locale/messages.en.xlf`. Both files carry the
|
||||
same trans-units (currently 690 = 690, no drift); the `.en.xlf` header is
|
||||
`source-language="nl" target-language="en"`. Because `i18nMissingTranslation: error`, a
|
||||
forgotten target breaks the `en` build rather than silently shipping Dutch.
|
||||
|
||||
## Testing languages without coupling to the strings
|
||||
|
||||
**Rule: never assert on rendered copy.** Copy is the thing that changes per locale and per
|
||||
edit — a test that reads `"Voer een geldige postcode in"` breaks the moment a translator or
|
||||
a product owner touches the wording, in every locale. Assert on what's *invariant* instead:
|
||||
|
||||
- **Parsers / value objects** — assert on the `Result` discriminant and the parsed value,
|
||||
not the error message. This is the existing house pattern
|
||||
(`registratie/domain/value-objects/postcode.spec.ts`):
|
||||
|
||||
```ts
|
||||
expect(parsePostcode('0234AB').ok).toBe(false); // rejects — never inspects the $localize string
|
||||
```
|
||||
|
||||
- **The seam itself** — if you must verify that translation works, check that a known
|
||||
**id flips**, not that a specific phrase appears. Build/serve the `en` configuration and
|
||||
confirm the target for a stable id renders, e.g. `login.submit`: `nl` "Inloggen met
|
||||
DigiD" → `en` "Log in with DigiD". You're testing the wiring, not the wording.
|
||||
|
||||
```bash
|
||||
ng serve --configuration=en # then eyeball, or point an e2e at the en bundle
|
||||
```
|
||||
|
||||
See [Testing strategy](?path=/docs/foundations-testing-strategy--docs) for how this fits the
|
||||
rest of the test pyramid.
|
||||
@@ -0,0 +1,93 @@
|
||||
import { Meta } from '@storybook/addon-docs/blocks';
|
||||
|
||||
<Meta title="Foundations/Testing strategy" />
|
||||
|
||||
# Testing strategy
|
||||
|
||||
Tests follow the same grain as the architecture: **push the logic down to where it's pure,
|
||||
test it there directly, and keep the layers above thin.** No single tool covers everything,
|
||||
so each layer gets the cheapest test that catches its class of bug.
|
||||
|
||||
## What gets tested where
|
||||
|
||||
| Layer | Test kind | Tool | Rule |
|
||||
| --- | --- | --- | --- |
|
||||
| `domain/` | pure-function unit spec | Vitest | **Required.** Call the function directly — **no `TestBed`**. Reducers, combinators, `visibleSteps`, parsers, policies. |
|
||||
| `domain/value-objects/` | parser spec | Vitest | Happy path + normalisation + **each** rejection. Assert on the `Result`, never the message. |
|
||||
| `infrastructure/` `parse*` | trust-boundary spec | Vitest | Accept a valid DTO; **reject `null` / `{}` / malformed**. Name it `describe('… (trust boundary)')`. |
|
||||
| `application/` | store / command spec | Vitest | Reducer purity, optimistic begin→confirm/rollback, command `Result`. |
|
||||
| `ui/` | Storybook story | Storybook + a11y | Kept thin. Axe runs on every story; add a `play` only for wiring axe can't see. |
|
||||
| flows | e2e smoke | Playwright | One happy path + one error state per critical journey. |
|
||||
| backend | rule + endpoint + golden | xUnit | Mirror of the FE domain rules, plus `WebApplicationFactory` integration. |
|
||||
|
||||
## Tooling
|
||||
|
||||
Vitest runs through Angular's built-in `@angular/build:unit-test` builder — **there is no
|
||||
`vitest.config.ts`**; config is implicit via `tsconfig.spec.json`.
|
||||
|
||||
```bash
|
||||
npm test # ng test → Vitest, all *.spec.ts co-located next to their unit
|
||||
```
|
||||
|
||||
Specs import `{ describe, it, expect }` from `vitest` and are co-located with the unit
|
||||
they cover.
|
||||
|
||||
## The house style
|
||||
|
||||
Pure and direct. A value-object parser spec
|
||||
(`registratie/domain/value-objects/postcode.spec.ts`):
|
||||
|
||||
```ts
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import { parsePostcode } from './postcode';
|
||||
|
||||
describe('parsePostcode', () => {
|
||||
it('normalises to "1234 AB"', () => {
|
||||
const r = parsePostcode(' 1234ab ');
|
||||
expect(r.ok).toBe(true);
|
||||
if (r.ok) expect(r.value).toBe('1234 AB');
|
||||
});
|
||||
it('rejects malformed input', () => {
|
||||
expect(parsePostcode('0234AB').ok).toBe(false); // asserts the tag, not the copy
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
A trust-boundary adapter (`registratie/infrastructure/brp.adapter.spec.ts`) additionally
|
||||
proves the untrusted shape is rejected:
|
||||
|
||||
```ts
|
||||
expect(parseBrpAddress(null).ok).toBe(false);
|
||||
expect(parseBrpAddress({}).ok).toBe(false); // missing required field
|
||||
```
|
||||
|
||||
Elm-style machines test the pure `reduce` with inline state fixtures — no Angular
|
||||
(`registratie/domain/registratie-wizard.machine.spec.ts`).
|
||||
|
||||
## UI = Storybook, not heavy component tests
|
||||
|
||||
`@storybook/addon-a11y` runs the `wcag2a/2aa/21a/21aa` rule sets on **every** story;
|
||||
`@storybook/test-runner` + `axe-playwright` turn that into a CI gate:
|
||||
|
||||
```bash
|
||||
npm run test-storybook # axe over every story against a running Storybook
|
||||
npm run test-storybook:ci # builds storybook-static, serves :6006, runs the gate
|
||||
```
|
||||
|
||||
Disabling a11y on a story needs an inline justification + a WP cross-reference (see
|
||||
[Accessibility](?path=/docs/foundations-accessibility--docs)).
|
||||
|
||||
## Don't assert on copy
|
||||
|
||||
Localized strings change per locale and per edit. Tests assert on the `Result`
|
||||
discriminant, the value object, or the message **id** — never the rendered Dutch/English
|
||||
text. Full detail in [Internationalization](?path=/docs/foundations-internationalization--docs).
|
||||
|
||||
## The GREEN gate
|
||||
|
||||
```bash
|
||||
npm run lint && npm run check:tokens && npm test && npm run build && npm run build-storybook
|
||||
cd backend && dotnet test
|
||||
```
|
||||
|
||||
Everything above must pass before a work package is done.
|
||||
Reference in New Issue
Block a user