Configuration

ShipTested can be configured through config files, environment variables, and CLI flags. This page covers all supported formats, every config option, and how different sources are merged together.

Supported Formats#

ShipTested checks for config files in the following order. The first one found is used:

shiptested.config.ts - TypeScript (ESM, via dynamic import)
shiptested.config.js - JavaScript (ESM, via dynamic import)
.shiptested.json - JSON
package.json - under the "shiptested" key

If no config file is found, ShipTested uses default values. The shiptested init command creates a shiptested.config.ts file automatically.

Config File Examples#

TypeScript (recommended)#

// shiptested.config.ts
interface ShipTestedConfig {
  maxIterations?: number;
  testFramework?: string;
  include?: string[];
  exclude?: string[];
  testDir?: string;
  colocate?: boolean;
}

const config: ShipTestedConfig = {
  maxIterations: 3,
  testFramework: "vitest",
  exclude: [
    "node_modules/**",
    "dist/**",
    "build/**",
    "**/*.test.*",
    "**/*.spec.*",
  ],
  colocate: true,
};

export default config;

JavaScript#

// shiptested.config.js
const config = {
  maxIterations: 3,
  testFramework: "vitest",
  exclude: [
    "node_modules/**",
    "dist/**",
    "build/**",
    "**/*.test.*",
    "**/*.spec.*",
  ],
  colocate: true,
};

export default config;

JSON#

// .shiptested.json
{
  "maxIterations": 3,
  "testFramework": "vitest",
  "exclude": [
    "node_modules/**",
    "dist/**",
    "build/**",
    "**/*.test.*",
    "**/*.spec.*"
  ],
  "colocate": true
}

package.json#

{
  "name": "my-app",
  "version": "1.0.0",
  "shiptested": {
    "maxIterations": 3,
    "testFramework": "vitest",
    "colocate": true
  }
}

Config Options#

All options are optional. ShipTested provides sensible defaults.

Option	Type	Default	Description
`maxIterations`	number	`3`	Maximum number of fix iterations per file. Each iteration runs the tests, and if they fail, sends errors to AI for a fix attempt.
`testFramework`	string	Auto-detected	Test framework to use: `vitest`, `jest`, or `mocha`. If not set, ShipTested detects the framework from your project dependencies.
`include`	string[]	All source files	Glob patterns for files to include in test generation. Example: `["src/*/.ts", "src/*/.tsx"]`
`exclude`	string[]	See below	Glob patterns for files to exclude. The `init` command sets sensible defaults like `node_modules/`, `dist/`, and test files.
`testDir`	string	–	Directory for generated test files. If not set, placement depends on the `colocate` option.
`colocate`	boolean	`false`	When `true`, test files are placed next to their source files (e.g., `src/utils/helpers.test.ts`). When `false`, tests go into a separate test directory.
`apiKey`	string	–	ShipTested API key. Prefer using the `SHIPTESTED_API_KEY` environment variable instead of storing keys in config files.

Default Exclude Patterns#

The init command generates these exclude patterns by default:

exclude: [
  "node_modules/**",
  "dist/**",
  "build/**",
  "**/*.test.*",
  "**/*.spec.*",
]

Config Merging Priority#

When the same option is set in multiple places, ShipTested uses the following priority (highest to lowest):

CLI flags - e.g., --max-iterations 5, --framework jest
Environment variables - e.g., SHIPTESTED_MAX_ITERATIONS
Config file - e.g., shiptested.config.ts
Defaults - built-in fallback values

This means a CLI flag always overrides a config file value, and an environment variable overrides a config file value but not a CLI flag.

# Config file sets maxIterations: 3
# Environment sets SHIPTESTED_MAX_ITERATIONS=5
# CLI flag sets --max-iterations 7

# Result: maxIterations = 7 (CLI flag wins)

Environment Variables#

These environment variables can configure ShipTested without a config file. They are especially useful in CI/CD environments.

Variable	Description
`SHIPTESTED_API_KEY`	API authentication token. Use this in CI/CD instead of OAuth login. Format: `sk_live_` followed by 32 hex characters.
`SHIPTESTED_API_URL`	Override the API base URL. Defaults to the production API.
`SHIPTESTED_MAX_ITERATIONS`	Override the maximum number of fix iterations per file. Parsed as an integer.
`SHIPTESTED_TEST_FRAMEWORK`	Override the test framework. Accepts `vitest`, `jest`, or `mocha`.
`NO_COLOR`	Disable colored terminal output. Set to any value to activate.

Using Environment Variables in CI#

# GitHub Actions example
env:
  SHIPTESTED_API_KEY: ${{ secrets.SHIPTESTED_API_KEY }}
  SHIPTESTED_MAX_ITERATIONS: "5"

# Shell
export SHIPTESTED_API_KEY=sk_live_abc123...
shiptested generate --ci --all

Example Configs for Common Setups#

Next.js + Vitest#

// shiptested.config.ts
const config = {
  testFramework: "vitest",
  include: ["src/**/*.ts", "src/**/*.tsx"],
  exclude: [
    "node_modules/**",
    "dist/**",
    ".next/**",
    "**/*.test.*",
    "**/*.spec.*",
    "src/app/**/layout.tsx",
    "src/app/**/loading.tsx",
  ],
  colocate: false,
  maxIterations: 3,
};

export default config;

Express API + Jest#

// shiptested.config.ts
const config = {
  testFramework: "jest",
  include: ["src/**/*.ts"],
  exclude: [
    "node_modules/**",
    "dist/**",
    "**/*.test.*",
    "**/*.spec.*",
    "src/index.ts",
  ],
  testDir: "__tests__",
  colocate: false,
  maxIterations: 3,
};

export default config;

Monorepo (single package)#

// packages/core/shiptested.config.ts
const config = {
  testFramework: "vitest",
  include: ["src/**/*.ts"],
  exclude: [
    "node_modules/**",
    "dist/**",
    "**/*.test.*",
  ],
  colocate: true,
  maxIterations: 5,
};

export default config;

Next Steps#

CLI Reference - full command and flag documentation
CI/CD Integration - automate test generation in your pipeline
How It Works - understand the generation pipeline

Was this page helpful?

CLI Reference

How It Works