@cobre-npm/ds-v3 0.144.2 → 0.145.0

package/README.md

@@ -27,6 +27,14 @@ pnpm approve-builds
 
 Then re-run `pnpm install` if needed.
 
+`postinstall` downloads the headless Chromium the render lane tests against (~95 MB, once per
+machine, idempotent). It lives in `postinstall` rather than in the test script because the browser is
+a dependency of the suite, and because more than one command runs that suite — putting it in `test`
+left every other entry point without a browser. `SKIP_TEST_BROWSER=1` skips it, for any image that installs dependencies and never runs the suite —
+the Dockerfile that builds the Storybook showcase sets it. On Alpine it skips itself, because
+Playwright publishes glibc builds only. `--ignore-scripts` skips it too, and `pnpm test:browsers`
+gets it back.
+
 ## Develop with Storybook (primary workflow)
 
 This is a component library — day-to-day development happens in Storybook, which renders every component with its variants and docs:
@@ -48,10 +56,45 @@ Opens at [http://localhost:6006](http://localhost:6006).
 | `pnpm dev` | Bare Vite dev harness (`src/main.ts`) — rarely needed |
 | `pnpm build` | Type-check + build the publishable library into `dist/` |
 | `pnpm build-storybook` | Build the static Storybook site |
-| `pnpm test:unit` | Run unit tests with [Vitest](https://vitest.dev/) |
-| `pnpm test` | Run Storybook interaction tests (test-runner) |
+| `pnpm test` | The whole gate: story render lane, logic lane with coverage, invariants |
+| `pnpm test:stories` | Render lane only — mounts all 81 stories in headless Chromium |
+| `pnpm test:unit` | Logic lane only, with coverage enforced against `coverage-floor.json` |
+| `pnpm test:browsers` | Re-download the Chromium build the render lane needs — normally unnecessary, `pnpm install` does it |
 | `pnpm lint` | Lint & auto-fix with [ESLint](https://eslint.org/) |
 
+## Testing
+
+The suite is split in two lanes because the two numbers would not mean the same thing
+([ADR-0008](https://github.com/Cobre-Colombia/portal/blob/trunk/docs/adr/0008-the-quality-gate-splits-by-subject-and-only-ratchets-up.md)):
+
+- **Render lane** (`test:stories`) — every story mounts without error, in headless Chromium via
+  `@storybook/addon-vitest`. It is **binary**: no percentage is attached to it. Storybook marks a
+  line covered when a story renders it while asserting nothing, so a percentage built that way
+  measures *exercised*, not *verified*.
+- **Logic lane** (`test:unit`) — the non-component sources (`src/**/*.ts` minus stories, tests,
+  type-only modules, barrels and the dev entry), with coverage thresholds enforced.
+
+### The coverage floor ratchets
+
+`coverage-floor.json` holds the thresholds, and it is **a floor, not a target**. It was set to what
+the repo measured the day the gate was switched on — there is no retroactive 95% and no backfill of
+the existing components as a precondition. It may only rise:
+
+- `scripts/check-invariants.mjs` fails the build when any number in the file drops below the base
+  ref. It is a change-level check, so it runs in CI, or locally with
+  `pnpm test:invariants -- --base origin/trunk`.
+- `src/utils/repo-invariants.test.ts` fails when `vitest.config.mts` stops reading its thresholds
+  from that file, which would otherwise be a silent way to lower the gate to nothing.
+
+To raise the floor: improve coverage, run `pnpm test:unit`, and copy the reported totals into
+`coverage-floor.json`.
+
+### Adding tests
+
+Component behaviour belongs in a story — it is the lane that already exists and the one consuming
+apps read as documentation. Reach for the logic lane when the subject is a composable, a pure
+function or shared state.
+
 ## Recommended IDE Setup
 
 [VSCode](https://code.visualstudio.com/) + [Vue - Official (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (disable Vetur).