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

> Learn to run Jest tests for CLI development in the agent-skills repository. Use npm test from the root to execute the full test suite with ts-jest for TypeScript ES modules.

- Repository: [TechLeads.club 💎/agent-skills](https://github.com/tech-leads-club/agent-skills)
- Tags: how-to-guide
- Published: 2026-05-18

---

**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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/cli/package.json)
- **`testMatch: ['**/__tests__/**/*.[jt]s?(x)']`** – Locates test files within `__tests__` directories throughout the package

```typescript
// 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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/package.json). This script handles the complex Node flags required for ES module support.

1. **Install dependencies** (one‑time setup):

```bash
npm ci

```

2. **Run the full test suite**:

```bash
npm test

```

The root [`package.json`](https://github.com/tech-leads-club/agent-skills/blob/main/package.json) script expands to:

```bash
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:

```bash
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:

```bash
npm test -- --watch

```

**Run a single test file** to isolate specific functionality:

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

```

**Execute only changed tests** since the last commit:

```bash
npm test -- --onlyChanged

```

These options integrate seamlessly with the existing configuration in [`packages/cli/jest.config.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/cli/jest.config.ts) extends the shared [`jest.preset.js`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/jest.preset.js) at the repository root and the `cross-env` package defined in the root [`package.json`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/tsconfig.json) and [`tsconfig.spec.json`](https://github.com/tech-leads-club/agent-skills/blob/main/tsconfig.spec.json) in the CLI package?

The [`tsconfig.spec.json`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/tsconfig.json) targets the production build.