Tests, CI and Storybook
Run the checks CI runs (.github/workflows/ci.yml) before you open a pull request.
Backend tests
Section titled “Backend tests”The solution is Maki.sln at the repo root. Test projects under tests/: Maki.Api.Tests, Maki.Core.Tests, Maki.Metadata.Tests and Maki.Sources.Tests.
dotnet build -c Release -warnaserror -warnnotaserror:NU1901,NU1902,NU1903,NU1904dotnet test -c Release
# One projectdotnet test tests/Maki.Sources.TestsCI fails on any compiler or analyzer warning, which is why the build line carries -warnaserror. Only NuGet vulnerability advisories stay warnings.
The JPEG XL tests skip when libjxl is not beside the test assemblies. CI provides it and sets MAKI_REQUIRE_LIBJXL=1, so a missing library fails them there. A Windows build fetches the libjxl DLLs on its own. On Linux, build them with distribution/libjxl/build.sh if you want those tests to run locally.
Tests that set a process-wide environment variable, such as the MAKI_SOURCE_*_BASEURL overrides, run in their own base-url-override collection, so they never run in parallel with tests that check the default hosts.
Frontend checks
Section titled “Frontend checks”Run these from frontend/ after npm ci.
npx tsc -btype-checks. Do not usenpx tsc --noEmit: the roottsconfig.jsonhas"files": []and only project references, so it checks nothing and exits 0 on a broken tree.npm run buildrunstsc -band thenvite build. CI runs this first.npm run check:secure-contextfails on rawcrypto.randomUUID,navigator.clipboardand similar calls. See Pull request conventions.npm run i18n:checkandnpm run i18n:validatecheck the translation catalogues.npm run i18n:bundlechecks the built output, so runnpm run buildfirst.npx lingui extract --cleanregenerateslocales/en/client.pofromtand<Trans>calls. Run it after changing UI text and commit the result.npm run lintruns oxlint. Errors fail CI; warnings are only reported.
Storybook
Section titled “Storybook”cd frontendnpm run storybook # UI on http://localhost:6006npm run test-storybook # every story as a browser testtest-storybook runs each story as a Vitest browser test in headless Chromium (Playwright). A story fails if it throws, its play function fails, or it makes an API request no mock answers. The first run needs npx playwright install chromium, as in CI.
The rules that catch most people:
- A new API call needs a mock in the same change. Mocks are in
frontend/.storybook/mocks/, one file per area. An unmocked request fails every story that reaches it. - Stories run inside the app’s real providers, set up once in
StoryProviders. Add missing contexts there, not per story. - Use plain English strings, not Lingui macros, so story text stays out of the catalogues.
- Put state and count assertions inside
waitFor. A second request can land after the first element appears, so a bare assertion can pass locally and fail on every CI run.
Full notes: .claude/rules/storybook.md.
What CI runs
Section titled “What CI runs”CI runs on every push to main and on every pull request. On a pull request, the backend jobs only run when src/, tests/, locales/, scripts/ci/, distribution/libjxl/ or the build files changed, and the frontend jobs only when frontend/, locales/, scripts/frontend/ or scripts/i18n/ changed. A new push to a pull request cancels the run for the previous one.
Backend (Ubuntu, .NET 10.0.x), split across parallel jobs:
backend: restore anddotnet build -c Release -warnaserrorof the whole solution, restores libjxl from cache or builds it, then runs every test project exceptMaki.Api.TestswithMAKI_REQUIRE_LIBJXL=1.api-tests (1/4)to(4/4): each buildsMaki.Api.Testsand runs a quarter of its test classes throughscripts/ci/test-shard.sh. To run one shard locally after a Release build:bash scripts/ci/test-shard.sh tests/Maki.Api.Tests 2 4.
Frontend (Ubuntu, Node 24, in frontend/):
frontend:npm ci,npm run lintandnpm run buildnpm run check:secure-context- On a pull request into
mainonly:npm run settings:stamp-since -- --check, which fails while any settings entry still sayssince: 'next' npx lingui extract --clean,npm run i18n:check, andgit diff --exit-code ../locales(a non-empty diff means uncommitted catalogues).npm run i18n:validatenpm run i18n:bundle, which fails if a non-English language ends up in the eager bundle
storybook (1/3)to(3/3): install Chromium, thennpm run test-storybook -- --shard=N/3.
Other checks on a pull request:
PR titlefails when the title is not a Conventional Commits title. See Pull request conventions.release-notes-entry, on pull requests intodev, warns when the change touchessrc/orfrontend/src/and adds nothing underchanges/. It never fails.- CodeQL scans pull requests into
devandmain.
The site under site/ has its own workflow, covered in Write docs.