@magic/test

CLI & Usage

package.json (recommended)

Add the magic/test bin scripts to package.json:

{  "scripts": {    "test": "t -p",    "coverage": "t",  },  "devDependencies": {    "@magic/test": "github:magic/test"  }}

Then use the npm run scripts:

npm testnpm run coverage

Globally (not recommended)

You can install this library globally, but the recommendation is to add the dependency and scripts to the package.json file.

This both explains to everyone that your app has these dependencies as well as keeping your bash free of clutter.

npm i -g @magic/test// run tests in production modet -p// run tests and get coverage in verbose modet

CLI Flags

Available command-line flags:

  • -p, --production, --prod - Run tests without coverage (faster)
  • -l, --verbose, --loud - Show detailed output including passing tests
  • -i, --include - Files to include in coverage
  • -e, --exclude - Files to exclude from coverage
  • --shards N - Total number of shards to split tests across
  • --shard-id N - Shard ID (0-indexed) to run
  • -w, --workers N - Max parallel workers (default: auto)
  • --help - Show help text

Note: `--shards` and `--shard-id` must be used together. `--shard-id` is 0-indexed (0 to N-1).

Sharding Tests

Run tests in parallel across multiple processes to speed up large test suites:

# Run 4 shards, this is shard 0 (of 0-3)t --shards 4 --shard-id 0# Run shard 1t --shards 4 --shard-id 1# Combine with other flagst -p --shards 4 --shard-id 2

Tests are distributed deterministically using a hash of the test file path, ensuring each test always runs in the same shard.

Add to your package.json for CI/CD:

{  "scripts": {    "test": "t -p",    "test:shard:0": "t -p --shards 4 --shard-id 0",    "test:shard:1": "t -p --shards 4 --shard-id 1",    "test:shard:2": "t -p --shards 4 --shard-id 2",    "test:shard:3": "t -p --shards 4 --shard-id 3"  }}

Or use a single command to run all shards in parallel:

# Run all 4 shards in parallel and wait for all to completenpm run test:shard:0 & npm run test:shard:1 & npm run test:shard:2 & npm run test:shard:3 & wait

Exit Codes

@magic/test returns specific exit codes to indicate test results:

| Exit Code | Meaning |

| --------- | ------- |

| 0 | All tests passed |

| 1 | One or more tests failed |

# Run tests and check exit codenpm testecho "Exit code: $?"  # 0 = success, 1 = failure

Verbose Output

The -l (or --verbose, --loud) flag enables detailed output:

# Shows all tests including passing onest -l

What verbose mode shows:

  • All test results (not just failures)
  • Individual test execution time
  • Full test names with suite hierarchy
  • Detailed error messages with stack traces

Default mode (without -l):

  • Only shows failing tests
  • Shows summary only for passing suites
  • Faster output for large test suites

Example output without -l:

### Testing package: my-lib/addition.js => Pass: 3/3 100%/multiplication.js => Pass: 4/4 100%Ran 7 tests in 12ms. Passed 7/7 100%

Example output with -l:

### Testing package: my-lib▶ addition  ✔ adds two positive numbers (1.2ms)  ✔ handles zero correctly (0.8ms)  ✔ handles negative numbers (0.9ms)▶ multiplication  ✔ multiplies by zero (0.7ms)  ✔ multiplies by one (0.6ms)  ✔ multiplies two positives (0.8ms)  ✔ handles negative numbers (0.9ms)Ran 7 tests in 12ms. Passed 7/7 100%

Performance Tips

For a detailed guide, see the Performance Tips page.

Quick Reference

# Fast mode - no coveraget -p# Shard across 4 processest --shards 4 --shard-id 0

Common Pitfalls

For a detailed guide, see the Common Pitfalls page.

Quick Reference

Avoid these common mistakes:

  • Forgetting to return in async tests
  • Not wrapping callback functions
  • Mutating shared state between tests
  • Using the wrong equality check
  • Not awaiting async operations
  • Incorrect hook usage