Commands

This page lists the scripts of a CAITS project, the commands of CAITS, and the environment variables that they read. init writes the scripts in package.json: they are yours, and you can change them.

The scripts of every day

Script	What it does
`npm run dev`	Starts the app on `http://localhost:3000`, and follows your changes.
`npm run tdd`	Runs the unit tests, then again at each save the tests of the files that you changed. A new handler, controller or store is found at once.
`npm test`	Runs all the unit tests, the contracts and the integration tests included.
`npm run check`	Runs all the checks at once: types, lint, architecture, unit tests with the coverage, mutation tests and end-to-end tests. It prints the output of the checks that fail, and only theirs, and writes the reports. Run it before each commit.
`npm run build`	Builds the app for production, in `dist/`.
`npm start`	Starts the production app, `dist/index.mjs`, on the port `PORT` (3000 when not set).

The scripts of each check

npm run check runs six of these scripts at once, each with a build folder of its own. To fix one check, run it alone.

Script	What it does
`npm run typecheck`	Builds the app, then checks the types of the TypeScript files and of the Marko templates.
`npm run lint`	Runs `lint:code`, then `lint:architecture`.
`npm run lint:code`	Runs ESLint, with `quality/eslint.config.js`.
`npm run lint:architecture`	Checks the architecture rules of `quality/architecture.mjs`, in less than a second.
`npm run test:coverage`	Runs the unit tests with the coverage (100% asked), and writes the documentation of the tests.
`npm run test:mutation`	Runs `caits mutation`: the mutation tests with Stryker (100% of the mutants killed asked), then the score of each file and the mutants that survived.
`npm run test:e2e`	Builds the app, starts it, and runs the end-to-end tests in a browser.

Other test scripts

Script	What it does
`npm run test:unit`	The unit tests, without the tests of the infra and the integration tests: the fastest ones.
`npm run test:contracts`	The tests of the infra: each adapter runs the contract of its port.
`npm run test:integration`	The integration tests: the backend with its real adapters.

The commands of CAITS

The scripts call these commands. Run them yourself with npx caits <command>.

Command	What it does
`caits init [folder]`	Makes a project, or adds CAITS to a project. See Installation for its options.
`caits update`	Writes the defaults of the installed CAITS in `quality/caits/`. Run it after you install another version.
`caits dev`	Starts the development server, with `quality/vite.config.ts`. It builds in `node_modules/.caits/dev/`, not in `dist/`: `npm run check` can run while it runs. When the configuration changes (`quality/vite.config.ts`, an `.env` file), it starts again by itself.
`caits check <script>…`	Runs the npm scripts that it gets, all at once, each with a build folder of its own. It prints one line for each check, then the output of the checks that fail. `npm run check` gives it the scripts of the checks: remove one, or add one of yours.
`caits architecture`	Checks the rules of `quality/architecture.mjs` on `src/` and `test/`.
`caits e2e`	Starts the server of `quality/playwright.config.ts`, then runs the end-to-end tests.
`caits mutation`	Runs Stryker with `quality/stryker.config.mjs`, then gives the score of each file and the mutants that survived, whether Stryker passed or not. Its exit code is that of Stryker. Its options go to Stryker.
`caits mutation-summary`	Gives the mutation score of each file. With `--survivors`, it also gives the mutants that survived.
`caits mutation-suite`	The unit tests, as Stryker runs them for each mutant.

The environment variables

Variable	Read by	What it sets
`PORT`	`npm run dev`, `npm start`	The port of the app. Default: 3000.
`HMR_PORT`	`npm run dev`	The port on which the browser gets the changes. Default: 24678. To run two projects at the same time, give each its two ports.
`DATA_DIR`	The example app	The folder of the files that the backend keeps. When it is not set, or empty: `tmp/`. The end-to-end tests give it a folder of their own for each project, and empty it before each run.

The end-to-end tests start the app on the port 4310. When another program uses this port, caits e2e stops at once and says so.

The reports

npm run check writes its reports in reports/:

Report	What it shows
`reports/test-docs/index.html`	The documentation of the tests: what the app does, test by test. See Test each layer.
`reports/coverage/index.html`	The coverage, line by line.
`reports/mutation/index.html`	The mutants, file by file.