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

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.

# 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 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 (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
• 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:

# 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:

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:

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

Or run all tests in a specific command directory:

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: Validates the playlist:validate command, asserting error handling for blocklisted channel IDs and malformed data
• 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:

 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 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, 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.

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