|
| 1 | +# Testing |
| 2 | + |
| 3 | +Three layers, from fastest to closest to a real consumer. |
| 4 | + |
| 5 | +| Command | What runs | Where the tests live | |
| 6 | +| :--- | :--- | :--- | |
| 7 | +| `npm test` | Vitest unit tests in jsdom | `lib/**/*.test.ts(x)` | |
| 8 | +| `npm run test:browser` | Vitest browser mode in real Chromium, Firefox and WebKit | `lib/**/*.browser.test.ts(x)` | |
| 9 | +| `npm run test:smoke` | Package smoke suite: Playwright Test against apps that installed the packed tarball | `e2e/` | |
| 10 | + |
| 11 | +Other gates: `npm run lint`, `npm run typecheck` (lib, tests, demo, e2e), `npm run build:lib` (also checks that React stays external). |
| 12 | + |
| 13 | +One-time setup for the browser and smoke suites: |
| 14 | + |
| 15 | +```bash |
| 16 | +npx playwright install chromium firefox webkit |
| 17 | +``` |
| 18 | + |
| 19 | +## Which one do I write? |
| 20 | + |
| 21 | +- **Render `<DataGrid>` with props and assert on it → Vitest.** Pure logic and hooks in `*.test.ts(x)`; anything that needs layout, `ResizeObserver`, scrolling or focus in `*.browser.test.tsx`. |
| 22 | +- **Needs the built package, a real app, a dev/preview server or a file download → e2e smoke.** Examples: the published `.d.ts` compiles in a strict consumer, the bundle works under React 18, the stylesheet sizes the grid inside an app shell, optional peers (`exceljs`, `jspdf`) load from the consumer's `node_modules`. |
| 23 | + |
| 24 | +Vitest tests import `lib/` source directly, so they cannot catch packaging mistakes (bundled `react/jsx-runtime`, a missing CSS rule in `dist/`, broken `exports`). That is what the smoke suite is for; keep it small. |
| 25 | + |
| 26 | +## The package smoke suite |
| 27 | + |
| 28 | +`npm run test:smoke` (`scripts/smoke.mjs`): |
| 29 | + |
| 30 | +1. `npm run build:lib`, then `npm pack` into `.pack/opencorestack-opengridx.tgz`. |
| 31 | +2. For each fixture in `e2e/fixtures/` (`react19`, `react18`): `npm ci` from its committed lockfile (skipped while the lockfile is unchanged), then unpack the fresh tarball into its `node_modules`. |
| 32 | +3. Build each fixture: `tsc` in strict mode with `skipLibCheck: false` against the shipped types, then `vite build`. The build is itself a typing test. |
| 33 | +4. `playwright test` (`e2e/playwright.config.ts`): Chromium, Firefox and WebKit against `vite preview` of each fixture (ports 4319 and 4318). |
| 34 | + |
| 35 | +Scenarios are selected with `?scenario=`: `basic`, `flex`, `grouping`, `editing` (both fixtures), `pinned`, `dark` (React 19 only). Every test fails on any console error or warning. |
| 36 | + |
| 37 | +Useful variants: |
| 38 | + |
| 39 | +```bash |
| 40 | +npm run test:smoke -- --skip-lib # reuse dist/ from a previous build:lib |
| 41 | +npm run test:smoke -- --skip-tests # pack, install and build the fixtures only |
| 42 | +npm run test:smoke -- -- --project=chromium-react18 # pass arguments to playwright test |
| 43 | +npx playwright test --config e2e/playwright.config.ts # rerun tests against the current fixture builds |
| 44 | +npx playwright show-report playwright-report # HTML report, traces of failed tests |
| 45 | +``` |
| 46 | + |
| 47 | +`--fresh` ignores the fixture lockfiles and installs the newest versions in range (used by the weekly workflow). |
| 48 | + |
| 49 | +### Fixtures |
| 50 | + |
| 51 | +The fixtures are separate npm projects: they are not part of the root lint, typecheck or Vitest runs and install into their own `node_modules`. When you change a fixture's dependencies, run `npm install` in it and then delete the `integrity` field from the `node_modules/@opencorestack/opengridx` entry of its `package-lock.json` (the tarball changes on every build; the script refuses a lockfile that pins it). |
| 52 | + |
| 53 | +## CI |
| 54 | + |
| 55 | +- `.github/workflows/ci.yml` (pull requests and pushes to branches other than `main`): lint, typecheck, unit, browser tests, `build:lib`, smoke suite. Playwright reports and traces are uploaded when a step fails. |
| 56 | +- `npm-publish.yml` runs the smoke suite after `build:lib` and before `npm publish`. |
| 57 | +- `nightly.yml` runs weekly: all Vitest projects and the smoke suite with `--fresh`. |
0 commit comments