espower-typescript

10.0.1 · maintenance · verified Sun Apr 19

espower-typescript is an instrumentation library that integrates `power-assert` with TypeScript projects, enabling rich, detailed assertion messages for test failures. It functions as a `mocha` `--require` hook, transforming TypeScript test files (`.ts`, `.tsx`) on the fly to inject power-assert's expressive assertions. The current stable version is 10.0.1. It aims to maintain compatibility with specific TypeScript versions (v2.7+ for v10.x) and Node.js environments (v10+), typically updating to align with major `ts-node` or `typescript` releases rather than a fixed cadence. Its key differentiators include a zero-config mode, automatic `tsconfig.json` detection, internal reliance on `ts-node` for compilation, and support for JSX/React and `allowJs` configurations.

Common errors

```
Cannot find module 'typescript'
```
cause `typescript` is a peer dependency but is not installed in the project or its version is incompatible.

fix Install `typescript` as a devDependency: `npm install -D typescript`.
```
TS2307: Cannot find module '@types/node'
```
cause Type checking is enabled by default, and `@types/node` (or other required `@types` packages) is missing.

fix Install the missing type definitions: `npm install -D @types/node`.
```
AssertionError: Expected true to be false
```
cause This is a generic assertion error, indicating that `power-assert` instrumentation failed. A common cause is using `import assert from 'assert'` instead of `import assert = require('assert')`.

fix Ensure you are using `import assert = require('assert')` for the `assert` module in your test files.
```
Error: The 'mocha' command failed with exit code 1. You may need to update 'mocha' or 'espower-typescript'.
```
cause This can occur due to Node.js version incompatibility, especially with older Node.js versions no longer supported by `espower-typescript`.

fix Verify your Node.js version is >=10.x. Update Node.js if necessary.

Warnings

breaking espower-typescript v10.x and newer requires Node.js v10.x or higher. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 10 or newer.
breaking espower-typescript v10.x and newer requires TypeScript v2.7 or higher. Ensure your project's `typescript` peer dependency meets this requirement.
Fix: Update the `typescript` package in your project to version 2.7 or later (`npm install typescript@latest`).
breaking Since v9.0.0, `typescript` must be installed as a local dependency in your project (e.g., `npm install -D typescript`), rather than relying on global installations or internal transitive dependencies.
Fix: Explicitly add `typescript` to your project's devDependencies: `npm install -D typescript`.
breaking From v9.0.0, type checking is enabled by default internally via `ts-node`. This requires `@types/node` and `@types/mocha` (or similar `@types` packages for other test runners) to be installed as devDependencies.
Fix: Install necessary type definitions: `npm install -D @types/node @types/mocha`.
gotcha You MUST use `import assert = require('assert')` for Node.js's built-in `assert` module. Using `import assert from 'assert'` will prevent `power-assert` instrumentation from working correctly, resulting in generic assertion errors.
Fix: Always use the CommonJS-style `import assert = require('assert')` for the assertion module when using `espower-typescript`.
breaking The internal `ts-node` dependency was updated from v8 to v9 in v10.0.0. Users relying on specific `ts-node` behaviors or configurations might need to review `ts-node`'s v9 release notes for compatibility.
Fix: Consult the `ts-node` v9 release notes and adjust any `ts-node` specific environment variables or configurations if issues arise.

Install

npm install espower-typescript npm
yarn add espower-typescript yarn
pnpm add espower-typescript pnpm

Imports

assert (Node.js built-in module)
wrong:
```
import assert from 'assert';
```
correct:
```
import assert = require('assert');
```
For `power-assert` instrumentation to work correctly with `espower-typescript`, the CommonJS-style `require` syntax is mandatory for importing Node's built-in `assert` module. Direct ES module imports for `assert` will bypass instrumentation.
espower-typescript/guess (Mocha hook)
wrong:
```
import { guess } from 'espower-typescript';
```
correct:
```
mocha --require espower-typescript/guess
```
This package is primarily consumed as a Mocha `--require` hook to preprocess TypeScript test files. It is not intended for direct JavaScript `import` statements within your application code.
@types/node
```
npm install -D @types/node
```
When type checking is enabled (default since v9.0.0), TypeScript definition files for Node.js globals are often required to prevent compilation errors.
@types/mocha
```
npm install -D @types/mocha
```
When type checking is enabled (default since v9.0.0), TypeScript definition files for Mocha globals are often required for test files.

Quickstart

Demonstrates how to install espower-typescript with its common peer dependencies and run a simple, failing TypeScript test with Mocha to show power-assert's detailed output.

npm install -D espower-typescript power-assert mocha typescript @types/node @types/mocha

// test/test.ts
import assert = require('assert');

describe('Array#join', () => {
  it('joins all elements into a string with separator', () => {
    // This assertion is intentionally designed to fail to demonstrate power-assert's output.
    assert(['a', 'b', 'c'].join(':') === 'a:b:c:');
  });
});

// To run tests from your terminal:
// ./node_modules/.bin/mocha --require espower-typescript/guess "test/**/*.ts"

// Expected (failing) output will include detailed power-assert instrumentation:
// AssertionError [ERR_ASSERTION]:   # test.ts:6
//
//   assert(['a','b','c'].join(':') === 'a:b:c:')
//          |             |         |
//          ["a","b","c"] "a:b:c"   false

view raw JSON →