@bupkis/from-assert

Migrate node:assert assertions to bupkis with a single command.

Supports both strict mode (node:assert/strict) and legacy mode (node:assert) assertions.

Installation

npx @bupkis/from-assert

Or install locally:

npm install -D @bupkis/from-assert

Usage

CLI

# Transform all test files in current directory
npx bupkis-from-assert

# Transform specific patterns
npx bupkis-from-assert "src/**/*.test.ts" "test/**/*.spec.ts"

# Dry run (see what would change without writing)
npx bupkis-from-assert --dry-run

# Exclude patterns
npx bupkis-from-assert --exclude "**/fixtures/**"

# Strict mode (fail on any unsupported assertion)
npx bupkis-from-assert --strict

Programmatic API

import { transform, transformCode } from '@bupkis/from-assert';

// Transform a code string
const { code, transformCount, warnings } = await transformCode(`
  import assert from 'node:assert';
  assert.strictEqual(foo, bar);
`);
// Result: "import { expect } from 'bupkis';\nexpect(foo, 'to be', bar);"

// Transform files
const result = await transform({
  include: ['**/*.test.ts'],
  exclude: ['**/node_modules/**'],
  mode: 'best-effort',
  write: true,
});

Transformations

Strict Equality

| node:assert | bupkis | | --------------------------------- | ----------------------------------- | | assert.strictEqual(a, b) | expect(a, 'to be', b) | | assert.notStrictEqual(a, b) | expect(a, 'not to be', b) | | assert.deepStrictEqual(a, b) | expect(a, 'to deep equal', b) | | assert.notDeepStrictEqual(a, b) | expect(a, 'not to deep equal', b) |

Legacy Equality (with warning)

When using plain node:assert (legacy mode), loose equality assertions are transformed with a warning since behavior may differ:

| node:assert | bupkis | | --------------------------- | ----------------------------------- | | assert.equal(a, b) | expect(a, 'to be', b) ⚠️ | | assert.notEqual(a, b) | expect(a, 'not to be', b) ⚠️ | | assert.deepEqual(a, b) | expect(a, 'to deep equal', b) | | assert.notDeepEqual(a, b) | expect(a, 'not to deep equal', b) |

Truthiness

| node:assert | bupkis | | ------------------ | ------------------------------- | | assert(value) | expect(value, 'to be truthy') | | assert.ok(value) | expect(value, 'to be truthy') |

Throws

| node:assert | bupkis | | ---------------------------- | --------------------------------- | | assert.throws(fn) | expect(fn, 'to throw') | | assert.throws(fn, Error) | expect(fn, 'to throw', Error) | | assert.throws(fn, /regex/) | expect(fn, 'to throw', /regex/) | | assert.doesNotThrow(fn) | expect(fn, 'not to throw') |

Async Assertions

Async assertions use expectAsync:

| node:assert | bupkis | | -------------------------------- | ----------------------------------------------- | | assert.rejects(asyncFn) | expectAsync(asyncFn, 'to reject') | | assert.rejects(asyncFn, Error) | expectAsync(asyncFn, 'to reject with', Error) | | assert.doesNotReject(asyncFn) | expectAsync(asyncFn, 'not to reject') |

String Matching

| node:assert | bupkis | | ----------------------------------- | -------------------------------------- | | assert.match(str, /regex/) | expect(str, 'to match', /regex/) | | assert.doesNotMatch(str, /regex/) | expect(str, 'not to match', /regex/) |

Fail

| node:assert | bupkis | | ---------------------- | ---------------------- | | assert.fail() | expect.fail() | | assert.fail(message) | expect.fail(message) |

Unsupported

The following require manual migration:

• assert.ifError(value) - Semantics don't map cleanly
• assert.CallTracker - Deprecated; use @bupkis/sinon instead
• Complex error matchers with validation functions

Import Handling

The transformer automatically handles all node:assert import styles:

// All of these are transformed
import assert from 'node:assert';
import assert from 'node:assert/strict';
import assert from 'assert';
import assert from 'assert/strict';
import { strict as assert } from 'node:assert';

The import is replaced with:

import { expect } from 'bupkis';
// or, if async assertions are present:
import { expect, expectAsync } from 'bupkis';

Options

| Option | Description | | ----------------- | ---------------------------------------------------------------- | | --dry-run | Show what would change without writing files | | --strict | Fail on any unsupported assertion | | --best-effort | Transform what we can, return warnings for unsupported (default) | | --exclude, -e | Patterns to exclude (default: **/node_modules/**) |

Handling Unsupported Assertions

In best-effort mode (default), unsupported assertions are left unchanged and a warning is returned. Search for warnings in the output to find items requiring manual review.

License

Blue Oak Model License 1.0.0