Configuration reference

SmartTest reads smarttest.config.{ts,mts,js,mjs,json} from the project root, or the file given with --config. smarttest init writes one for you. The file is transpiled on load, so import { defineConfig } from "@tkmremi/smarttest" works even before the package is resolvable.

import { defineConfig } from "@tkmremi/smarttest";

export default defineConfig({
  mode: "balanced",
  adapters: ["vitest"],
  vcs: { provider: "auto", base: "main", snapshots: true },
  snapshots: { storeContent: false, keep: 20 },
  tests: { layout: "mirror", directory: "tests", naming: "{FileName}.test.{Extension}" },
  generated: [{ path: "src/generated/**", policy: "exclude" }],
  triggers: ["db/schema.sql"],
  rules: [
    {
      name: "auth-critical",
      match: { path: "src/auth/**" },
      risk: "critical",
      execution: { alwaysRunOnAffected: true },
    },
  ],
  retries: 0,
  timeoutMs: 600000,
  reports: { formats: ["html", "json", "junit"], outputDir: ".smarttest/reports" },
});

hook.checks is an array of { name, run, projects?, files?, stage? }. Commands run in affected project directories; {files} becomes quoted changed paths. stage is pre-commit (default), pre-push or both. hook.budgetMs defaults to 60000; exceeding the estimate warns and still runs the full selection. hook.runners (an allow-list of vitest, jest, node, playwright, cypress, angular, pytest, unittest; default every runner) and hook.exclude (project-relative test-file globs; default none) set the hook scope: selected tests outside it are not run by run --staged --hook / run --push --hook and are reported as "selected, not run in the hook (left to CI)" with the rule that removed them, never as passed. run, ci, impact and every other command ignore the scope. An empty hook.runners or an unknown runner name fails with ST_CONFIG_INVALID. See commit and push hooks.

hook.trailer (boolean, default false) adds a Tests: trailer to each commit message with what the pre-commit run of the committed tree did (Tests: 12 run, 2,340 not run · ~4 min saved). smarttest hook install then also writes a commit-msg step; a commit whose tree has no passing pre-commit record gets no trailer. See the commit trailer.

plugins is an array of plugin modules: paths relative to the root (./tools/sql-edges.mjs) or package names. A plugin adds dependency edges that static analysis cannot see; see Plugins. A change to a plugin file inside the project selects the full suite.

Unknown keys produce warnings instead of being silently accepted.

The configuration is repository content, so its paths must stay inside the project: storeDir (a subdirectory, never the project root), reports.outputDir, tests.directory, tests.templates and runners[].dir/config are refused when they are absolute or leave the project with ../ (ST_CONFIG_INVALID). A command-line --output is your own choice and is not restricted. SmartTest also refuses to write its state or reports through a symbolic link inside the project (ST_UNSAFE_PATH), and refuses a store that is committed to Git (ST_STORE_TRACKED). See the security review.

JSON Schema #

The configuration has a published JSON Schema, frozen at 1.0.0: config.v1.schema.json, shipped in the package as @tkmremi/smarttest/schemas/config.v1.schema.json. Point $schema at it in smarttest.config.json to get completion and validation in editors; SmartTest ignores the key:

{
  "$schema": "./node_modules/@tkmremi/smarttest/schemas/config.v1.schema.json",
  "mode": "balanced",
  "plugins": ["./tools/sql-edges.mjs"]
}

A test checks the schema, the SmartTestConfig type and the validator SmartTest runs on load against each other, so they cannot drift. The schema rejects unknown keys so editors catch typos; SmartTest itself only warns about them. Public contracts lists what is frozen and how it may change.

Per-project conventions #

import { defineConfig } from "@tkmremi/smarttest";

export default defineConfig({
  tests: { layout: "mirror", directory: "tests" },
  projects: {
    "FrontLeadsIt/app": {
      tests: { layout: "colocated", naming: "{FileName}.server.test.{Extension}" },
    },
    backend: {
      tests: { layout: "custom", path: "backend/src/__tests__/{FileName}.test.{Extension}" },
      mode: "safe",
    },
  },
});

{ProjectDir} is available in path and naming templates.

Edit this page on GitHub