Configuration

Discover and configure guchho.test.config files, options, and CLI precedence.

Guchho Test discovers a configuration file automatically, or you can pass one explicitly with --config.

Configuration controls discovery, execution, reporting, coverage, and plugin loading. CLI options take precedence over file values, and unknown or invalid values are rejected with a clear error rather than silently ignored.

File names

In precedence order within a directory:

guchho.test.config.ts
guchho.test.config.js
guchho.test.config.mjs
guchho.test.config.json

The CLI starts in the working directory and walks up parent directories until it finds a configuration file. The nearest file wins.

TypeScript configuration

import { defineConfig } from '@guchho/test';

export default defineConfig({
  include: ['**/*.{test,spec}.{js,ts}'],
  exclude: ['**/node_modules/**', '**/dist/**'],
  timeout: 5000,
  reporters: ['default'],
  setupFiles: ['./tests/setup.js'],
  setupFilesAfterEnv: ['./tests/setup-after-env.js'],
  globalSetup: './tests/global-setup.js',
  globalTeardown: './tests/global-teardown.js',
  environment: 'node',
  globals: false,
  tsconfig: './tsconfig.json',
  coverage: {
    enabled: false,
    reporter: ['text', 'html'],
  },
});

.ts configuration files are transformed by the built-in loader, so no separate build step is required.

JSON configuration

{
  "include": ["src/**/*.test.js"],
  "timeout": 10000,
  "reporters": ["default"]
}

Schema

Top-level options

Unknown top-level options are rejected.

setupFiles and setupFilesAfterEnv

Setup modules run once per test file, inside that file's worker process. Entries are resolved from the working directory and may be .js, .mjs, .cjs, or .ts files.

Execution order for each test file:

1. every setupFiles entry, in array order;
2. every setupFilesAfterEnv entry, in array order;
3. the test file itself.

setupFiles: ['./tests/setup-environment.js'],
setupFilesAfterEnv: ['./tests/setup-matchers.js'];

A setup module that throws, or cannot be loaded, aborts that test file and exits with code 2. The error identifies the failing setup file.

globalSetup and globalTeardown

These run once per test run in the main process, rather than once per test file:

1. globalSetup runs before any test file is executed.
2. globalTeardown runs after all test files finish, including when a test file fails.

// tests/global-setup.js
export default async function setup({ cwd }) {
  await startDatabase(cwd);
}

// tests/global-teardown.js
export async function teardown({ cwd }) {
  await stopDatabase(cwd);
}

The module may export a function as default, or under the matching hook name (setup or teardown). The function receives { cwd } and may be synchronous or return a promise. A failure in either hook prints its error and exits with code 2; a globalSetup failure prevents the test files from running.

In watch mode both hooks run again for each rerun.

environment

The default node environment leaves Node.js globals unchanged. DOM environments install browser globals such as window, document, and navigator, and restore the previous globals when the test file finishes.

environment: 'jsdom',
environmentOptions: { url: 'https://example.test' },

jsdom and happy-dom are optional peer dependencies. Install the one you use:

npm install --save-dev jsdom

If the package is missing, the run fails with an actionable installation message.

globals

Set globals: true to run Jest-style test files that rely on globals instead of imports:

globals: true;

The following globals are installed for the duration of each test file: describe, suite, it, test, expect, mock, jest, beforeAll, afterAll, beforeEach, afterEach, skip, todo, fails, xdescribe, xit, xtest, fdescribe, and fit. The jest object exposes the mock API and expect.

tsconfig and path aliases

Guchho Test reads compilerOptions.baseUrl and compilerOptions.paths from a TypeScript configuration file to resolve non-relative imports in test files and their dependencies.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["src/*"]
    }
  }
}

By default the CLI looks for tsconfig.json in the working directory. Set tsconfig to use a different file. Relative and absolute imports, file: URLs, node: built-ins, and other URL schemes are left to Node.js.

reporters

A reporter entry is either a built-in name or a [name, options] tuple:

reporters: ['default', ['json', { label: 'CI' }]];

Built-in names: default, verbose, dot, json, junit, tap, github, and github-actions.

Custom reporter names are accepted only when plugins is non-empty. The [name, options] options object is passed to custom reporter factories.

coverage

Threshold values must be numbers between 0 and 100.

Default coverage include:

**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}

Default coverage exclude:

**/node_modules/**
**/dist/**
**/tests/**
**/*.test.*
**/*.spec.*
**/__snapshots__/**
**/coverage/**

Recommended baseline

Start with the defaults and add options only when the project needs them:

import { defineConfig } from '@guchho/test';

export default defineConfig({
  include: ['src/**/*.test.js'],
  timeout: 5000,
  reporters: ['default'],
});

Add coverage thresholds and additional reporters once the suite is stable.

Defaults

Precedence

Command-line options override configuration values, which override defaults.

• --timeout overrides timeout.
• --reporter replaces the configured reporters with a single reporter.
• --coverage sets coverage.enabled to true.
• --config <path> selects a specific file instead of discovery.

Validation

Configuration is validated before running. Errors identify the file and option, for example:

guchho.test.config.js: "timeout" must be a positive, finite number.
guchho.test.config.js: unknown configuration option "foo".
guchho.test.config.js: unknown reporter "mocha".

Invalid configuration exits with code 2.

Globs

Discovery uses a small glob implementation supporting:

• * — any characters except /;
• ** — any characters including / (**/ also matches zero directories);
• ? — a single non-/ character;
• {a,b} — alternatives.

Patterns are matched against POSIX-style relative paths.

Related

• CLI Reference
• Writing Tests
• Coverage
• Reporters

Edit this page on GitHub