How to Run Tests for CLI Development Using Jest in the Agent‑Skills Repository

Run npm test from the repository root to execute the complete Jest test suite for the CLI package, which uses ts‑jest to transpile TypeScript with ES module support enabled.

The tech-leads-club/agent-skills repository is a monorepo containing a fully‑typed TypeScript CLI in packages/cli that relies on Jest for both unit and property‑based testing. Understanding how to run tests for CLI development using Jest requires familiarity with the ES module configuration and the Node experimental flags that enable ESM support in this codebase.

Jest Configuration for the CLI Package

The CLI package maintains its own dedicated Jest configuration in packages/cli/jest.config.ts. This file extends the shared Nx preset while configuring specific settings for Node.js CLI testing.

Key configuration details include:

• testEnvironment: 'node' – Essential for CLI tools that interact with the file system and operating system APIs
• useESM: true in the ts‑jest transformer – Compiles TypeScript as ES modules to match the "type": "module" declaration in packages/cli/package.json
• testMatch: ['**/__tests__/**/*.[jt]s?(x)'] – Locates test files within __tests__ directories throughout the package

// packages/cli/jest.config.ts
const config: Config = {
  displayName: 'cli',
  preset: '../../jest.preset.js',
  testEnvironment: 'node',
  testMatch: ['**/__tests__/**/*.[jt]s?(x)'],
  transform: {
    '^.+\\.[tj]sx?$': ['ts-jest', {
      useESM: true,
      tsconfig: '<rootDir>/tsconfig.spec.json',
      diagnostics: { ignoreCodes: [151002], warnOnly: true },
    }],
  },
  moduleNameMapper: {
    '@tech-leads-club/core$': '<rootDir>/../../libs/core/src/index.ts'
  },
  coverageDirectory: '../../coverage/packages/cli',
}

The tsconfig.spec.json file referenced in the configuration provides TypeScript compiler options specifically optimized for the test environment, enabling strict type checking while allowing the ESM output that Jest expects.

Running the Test Suite

To execute the CLI tests, use the npm script defined in the root package.json. This script handles the complex Node flags required for ES module support.

1. Install dependencies (one‑time setup):

npm ci

2. Run the full test suite:

npm test

The root package.json script expands to:

cross-env NODE_OPTIONS='--experimental-vm-modules' jest

The cross-env package ensures the NODE_OPTIONS environment variable is set correctly across Windows, macOS, and Linux. The --experimental-vm-modules flag is mandatory for Jest to execute ES modules in Node.js.

Alternatively, invoke Jest directly for the CLI package only:

npx jest --config packages/cli/jest.config.ts

Watch Mode and Test Filtering

During active development, you can leverage Jest's watch mode and filtering options to run specific subsets of tests.

Enable watch mode to automatically re‑run tests when files change:

npm test -- --watch

Run a single test file to isolate specific functionality:

npm test -- packages/cli/src/services/__tests__/config.test.ts

Execute only changed tests since the last commit:

npm test -- --onlyChanged

These options integrate seamlessly with the existing configuration in packages/cli/jest.config.ts, which automatically picks up any file matching *.test.ts or *.test.tsx patterns.

Test Types in the CLI

The CLI package employs two distinct testing strategies, both executed by the same Jest configuration:

Unit Tests – Standard Jest tests that mock dependencies like fs/promises and os to verify configuration loading and business logic. Example: packages/cli/src/services/__tests__/config.test.ts.

Property‑Based Tests – Tests using fast‑check to generate random inputs and verify invariants across many scenarios. These files use the *.pbt.test.ts naming convention. Example: packages/cli/src/services/__tests__/terminal-dimensions.pbt.test.ts.

Both test styles are discovered automatically by the testMatch pattern and execute within the same Node environment.

Summary

• Primary command: Run npm test from the repository root to execute CLI tests with proper ESM support
• Configuration location: packages/cli/jest.config.ts extends the shared jest.preset.js and configures ts‑jest with useESM: true
• Critical flag: The --experimental-vm-modules Node option is required for ES module support, handled automatically by the root npm script
• Test patterns: Files in __tests__ directories matching *.test.ts or *.pbt.test.ts are automatically included
• Direct execution: Use npx jest --config packages/cli/jest.config.ts to run CLI tests in isolation

Frequently Asked Questions

Why is the --experimental-vm-modules flag necessary for running CLI tests?

Jest requires the --experimental-vm-modules Node.js flag to support ES modules natively. Since the CLI package specifies "type": "module" in its package.json and uses useESM: true in the ts‑jest configuration, this flag enables the VM to load ECMAScript modules dynamically during test execution.

How do I run only the property‑based tests in the CLI package?

Property‑based tests follow the *.pbt.test.ts naming convention. To run only these tests, use the test path pattern flag: npm test -- --testPathPattern="pbt.test". This filters the test match to include only files like terminal-dimensions.pbt.test.ts while excluding standard unit tests.

Can I run CLI tests without installing root dependencies?

No. The CLI test suite depends on the shared jest.preset.js at the repository root and the cross-env package defined in the root package.json. You must run npm ci from the repository root to install all workspace dependencies before executing any tests in packages/cli.

What is the difference between tsconfig.json and tsconfig.spec.json in the CLI package?

The tsconfig.spec.json file is used exclusively by Jest via the ts‑jest transformer. It extends the base TypeScript configuration but adjusts compiler options specifically for the test environment, such as allowing the ES module output that Jest expects, while the main tsconfig.json targets the production build.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}