# How to Run the IPTV Test Suite with Jest: Complete Setup Guide

> Learn how to run the IPTV test suite using Jest. This comprehensive guide details the setup process for executing tests serially with TypeScript compilation via @swc/jest in the iptv-org/iptv repository. Execute `npm test` to g...

- Repository: [iptv-org/iptv](https://github.com/iptv-org/iptv)
- Tags: how-to-guide
- Published: 2026-02-25

---

**Run `npm test` in the iptv-org/iptv repository to execute the Jest test suite serially with TypeScript compilation via @swc/jest.**

The iptv-org/iptv repository relies on **Jest** to validate playlist generation and validation logic. Running the IPTV test suite with Jest ensures that CLI commands in `scripts/commands/` behave correctly across different scenarios. The entire suite executes without external service dependencies, requiring only Node.js 18 or higher.

## Prerequisites and Installation

Before executing tests, install the required dependencies. The repository uses **@swc/jest** for high-performance TypeScript compilation and **jest-expect-message** for enhanced assertion messages.

```bash

# Install dependencies (recommended for CI)

npm ci

# Or for local development

npm install

```

The test suite requires **Node.js ≥ 18** because the underlying CLI scripts use modern JavaScript features. No additional global packages or external databases are needed.

## Jest Configuration in package.json

The Jest configuration is embedded directly in [`package.json`](https://github.com/iptv-org/iptv/blob/main/package.json) rather than a separate config file. This setup instructs Jest to transform all `*.ts` files using **@swc/jest** and locate tests matching the pattern `tests/(.*?/)?.*test.ts$`.

According to the source code in [`package.json`](https://github.com/iptv-org/iptv/blob/main/package.json) (lines 22-30), the configuration specifies:

- **transform**: Maps `.ts$` files to `@swc/jest` for on-the-fly TypeScript compilation
- **testMatch**: Locates files in `tests/` directories ending with [`.test.ts`](https://github.com/iptv-org/iptv/blob/main/.test.ts)
- **setupFilesAfterEnv**: Loads `jest-expect-message` to provide custom error messages on assertion failures

The `test` script (lines 19-20) invokes **Jest** with the `--runInBand` flag, forcing serial test execution. This prevents race conditions when multiple tests spawn CLI processes that manipulate filesystem state.

## Executing the Test Suite

Run the full test suite using the npm script defined in the repository:

```bash

# Run all tests serially

npm test

```

This command executes `jest --runInBand`, which processes each test file sequentially rather than in parallel. Serial execution is critical because tests spawn actual CLI commands that read and write to `tests/__data__/`, and concurrent access could cause flaky results.

### Debugging Test Execution

To see the exact CLI commands being executed during tests, set the `DEBUG` environment variable:

```bash
DEBUG=true npm test

```

This outputs the underlying shell commands that the test suite spawns using `cross-env`, helping diagnose path or environment issues.

### Running Individual Test Files

Target specific test suites using Jest's file path matching:

```bash
npx jest tests/commands/playlist/validate.test.ts

```

Or run all tests in a specific command directory:

```bash
npx jest tests/commands/playlist/

```

## Test Structure and File Organization

All test files reside in the `tests/` directory and follow the naming convention `*.test.ts`. The repository organizes tests to mirror the command structure in `scripts/commands/`.

Key test files include:

- **[`tests/commands/playlist/validate.test.ts`](https://github.com/iptv-org/iptv/blob/main/tests/commands/playlist/validate.test.ts)**: Validates the `playlist:validate` command, asserting error handling for blocklisted channel IDs and malformed data
- **[`tests/commands/playlist/generate.test.ts`](https://github.com/iptv-org/iptv/blob/main/tests/commands/playlist/generate.test.ts)**: Tests the `playlist:generate` command against fixture data in `tests/__data__/`, verifying output playlists match expected snapshots
- **`tests/__data__/`**: Contains fixture files including input playlists, expected outputs, and log files that serve as test oracle data

Tests typically spawn the compiled CLI commands using `cross-env` to control environment variables, then assert on **stdout** content, exit codes, or filesystem side effects.

## Understanding Test Output

A successful test run produces output similar to this excerpt from [`tests/commands/playlist/validate.test.ts`](https://github.com/iptv-org/iptv/blob/main/tests/commands/playlist/validate.test.ts):

```text
 PASS  tests/commands/playlist/validate.test.ts
  playlist:validate
    ✓ show an error if channel id in the blocklist (123 ms)
    ✓ show a warning if channel has wrong id (45 ms)
    ✓ skip the file if it does not exist (10 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Time:        1.234 s

```

The `--runInBand` flag ensures that tests within a suite and across suites execute one at a time, preventing resource contention when multiple tests write to the same fixture directories.

## Summary

- **Install dependencies** with `npm ci` before running tests
- **Execute tests** using `npm test`, which runs `jest --runInBand` for serial execution
- **Enable debugging** by setting `DEBUG=true` to see spawned CLI commands
- **Run individual files** with `npx jest <path>` for targeted development feedback
- **Locate test files** in `tests/` matching the pattern `*.test.ts`, with fixtures stored in `tests/__data__/`

## Frequently Asked Questions

### Why does the IPTV test suite use --runInBand instead of parallel execution?

The **--runInBand** flag forces Jest to run tests serially rather than spawning multiple worker processes. According to the [`package.json`](https://github.com/iptv-org/iptv/blob/main/package.json) configuration in iptv-org/iptv, this prevents race conditions because multiple test files manipulate shared fixture data in `tests/__data__/` and spawn CLI commands that write to the filesystem. Parallel execution could cause tests to overwrite each other's temporary files or interfere with environment variable states.

### How do I run a single test file instead of the entire suite?

Use **npx jest** with the specific file path: `npx jest tests/commands/playlist/validate.test.ts`. This command bypasses the npm script and executes only the specified test file while still respecting the Jest configuration in [`package.json`](https://github.com/iptv-org/iptv/blob/main/package.json), including the `@swc/jest` TypeScript transformer and the `jest-expect-message` setup.

### What should I do if tests fail with TypeScript compilation errors?

Ensure you have installed all dependencies with `npm ci` rather than `npm install` to guarantee exact version matching. The **@swc/jest** transformer compiles TypeScript on-the-fly, so no separate build step is required. If errors persist, verify you are using **Node.js 18 or higher**, as the repository relies on modern JavaScript features not available in earlier versions.

### Can I see the actual CLI commands that the tests are executing?

Set the **DEBUG=true** environment variable before running tests: `DEBUG=true npm test`. This enables verbose logging that shows the exact shell commands spawned by the test suite, including arguments and environment variables passed via `cross-env`. This is particularly useful when debugging path resolution or environment-specific failures in the `scripts/commands/` implementations.