# Related tests per track (CI-1)

Owner decision, 2026-11-14: a track runs only the tests related to what it changed, once, when it is merged into `development`. The full suite (`npm run check:all`) runs once before a release, and what it finds is fixed in that release.

| When                                           | Command                 | What runs                                   |
| ---------------------------------------------- | ----------------------- | ------------------------------------------- |
| Before every commit                            | `npm run check`         | The fast checks, as today                   |
| Before a track's merge, after the review fixes | `npm run check:related` | The suites the track's changes select, once |
| Before a release (`development` → `master`)    | `npm run check:all`     | Every suite on the AI box                   |

## The map

`ci/test-map.mjs` is data: an ordered list of rules, each a set of path globs, a name (the area) and the suites it selects. The first rule that matches a file wins, so specific rules stand before general ones. `scripts/test-plan.mjs` reads the changed files (`git diff --name-only origin/development...HEAD`), applies the map, merges what the files select and prints the plan with the reason for every suite.

| Suite                | Where         | Selected by                                                                                                                  |
| -------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| ESLint, stylelint    | Mac           | JS, CSS and lint config changes                                                                                              |
| PHPCS, PHPStan       | Mac           | `app/`, `kimaai.php` and their config; `premium/` is not scanned by either (ROADMAP, "Later")                                |
| Jest                 | Mac           | `jest --findRelatedTests` on the changed JS and test files; the whole suite for Jest setup and the JS toolchain              |
| PHPUnit unit         | Mac or AI box | Whole, on the Mac's PHP, for any PHP change (about 12 seconds); on PHP 8.0 to 8.4 on the box for PHP-version-sensitive files |
| PHPUnit integration  | AI box        | AI providers, the chatbot pipeline, the admin assistant, pinned answers and the query condenser; PHP 8.4, or 8.0 and 8.4     |
| Build                | AI box        | Anything under `src/` and the JS toolchain; before Playwright, WP-CLI and Plugin Check                                       |
| Playwright           | AI box        | Spec groups per area (below); a changed spec runs itself                                                                     |
| WP-CLI (`tests/cli`) | AI box        | Test-class groups per area (below); a changed test class runs itself                                                         |
| Storybook build      | AI box        | The chatbot, shared and admin components, `tests/storybook/`, `.storybook/`                                                  |
| Plugin Check         | AI box        | What the free plugin ships: `app/`, `kimaai.php`, `readme.txt`, `languages/`, `assets/`, the staging and packaging           |

**PHP versions.** The unit suite always runs whole: it is fast, and a narrower filter would save seconds. It runs on every supported PHP version only when the Composer files, the Symfony patches, `kimaai.php`, the container (`app/Lib/`, `app/Main.php`, `premium/app/Lib/`), the unit bootstrap or `tests/unit/Runtime/` change: that is where the PHP 8.0 to 8.4 differences have shown up.

**Playwright groups.** chatbot-widget, chatbot-settings, chatbot-request, feedback, admin-settings, setup-wizard, search-answers, embedding, mcp, leads, insights, customer-centre, privacy, free-build. Every spec is in at least one group.

**WP-CLI groups.** smoke, chat, schema, vectors, eval, insights, mcp, free-build. Every test class is in at least one group.

**Shared infrastructure widens to its whole layer**: e2e fixtures, helpers, page objects, `tests/e2e/playground.json` and the Playwright config select every spec; `tests/cli/CliTestCase.php`, its bootstrap and fixtures every CLI test; Jest setup and helpers the whole Jest suite; `package-lock.json`, webpack and `ci/node.Dockerfile` the whole JS layer; `composer.*`, the patches and `kimaai.php` the whole PHP layer.

**Two exceptions.** `ci/run-remote.sh` and `ci/remote-check.sh` select a shell syntax check only, not every box suite: every related run goes through them, and `check:all` before the release runs them in full. A `package.json` change that touches only `scripts` selects nothing; any other `package.json` change selects the whole JS layer.

**Docs-only changes select nothing.** A file no rule matches selects every suite and is listed under "Unmatched", so the map gets a rule instead of the file being skipped. A Jest test fails when a tracked file matches no rule, or a spec or CLI class belongs to no group.

## Running the plan

`npm run check:related` runs the selected fast suites on the Mac, then, when the plan selects a heavy suite, `ci/run-remote.sh --plan <file>`: the plan travels with the checkout and `ci/remote-check.sh` runs only its steps, with the Playwright spec list, the PHPUnit `--filter` for the CLI classes and the PHP versions. Without `--plan`, `ci/remote-check.sh` runs every step as before. `--local`, `--no-paid` and `--wp-min` work as before.

## Interrupted runs

Today Ctrl-C or a dropped connection leaves `ci/remote-check.sh` and its containers running on the box, with the checkout and the `/dev/shm` env file (API keys). The Mac now sends a heartbeat through the SSH session; on the box a watcher stops the run when the heartbeat ends or stalls for a minute: it ends `ci/remote-check.sh`, removes its containers (labelled with the run), its Compose projects and volumes, the checkout and the env file. The Mac's exit trap waits for that before it removes what is left.

## Items

| Item | What                                                                             |
| ---- | -------------------------------------------------------------------------------- |
| CI-1 | This note                                                                        |
| CI-2 | The map, `ci/test-map.mjs`                                                       |
| CI-3 | The planner, `scripts/test-plan.mjs`, and its tests                              |
| CI-4 | `npm run check:related`, `--plan` in `ci/run-remote.sh` and `ci/remote-check.sh` |
| CI-5 | Cleanup after an interrupted run                                                 |
