@bupkis/from-chai

Migrate Chai assertions to bupkis with a single command.

Supports both BDD style (expect/should) and TDD style (assert) assertions.

Installation

npx @bupkis/from-chai

Or install locally:

npm install -D @bupkis/from-chai

Usage

CLI

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

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

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

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

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

Programmatic API

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

// Transform a code string
const { code, transformCount, warnings } = await transformCode(`
  import { expect } from 'chai';
  expect(foo).to.equal(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

BDD Style (expect)

Chai	bupkis
`expect(x).to.equal(y)`	`expect(x, 'to be', y)`
`expect(x).to.deep.equal(y)`	`expect(x, 'to deep equal', y)`
`expect(x).to.be.true`	`expect(x, 'to be true')`
`expect(x).to.be.false`	`expect(x, 'to be false')`
`expect(x).to.be.null`	`expect(x, 'to be null')`
`expect(x).to.be.undefined`	`expect(x, 'to be undefined')`
`expect(x).to.be.ok`	`expect(x, 'to be truthy')`
`expect(x).to.exist`	`expect(x, 'to be defined')`
`expect(x).to.be.a('string')`	`expect(x, 'to be a', 'string')`
`expect(x).to.be.instanceof(Y)`	`expect(x, 'to be an instance of', Y)`
`expect(x).to.have.property('y')`	`expect(x, 'to have property', 'y')`
`expect(x).to.have.length(3)`	`expect(x, 'to have length', 3)`
`expect(x).to.contain(y)`	`expect(x, 'to contain', y)`
`expect(x).to.match(/foo/)`	`expect(x, 'to match', /foo/)`
`expect(x).to.be.above(5)`	`expect(x, 'to be greater than', 5)`
`expect(x).to.be.below(10)`	`expect(x, 'to be less than', 10)`
`expect(x).to.be.at.least(5)`	`expect(x, 'to be greater than or equal to', 5)`
`expect(x).to.be.at.most(10)`	`expect(x, 'to be less than or equal to', 10)`
`expect(fn).to.throw()`	`expect(fn, 'to throw')`
`expect(fn).to.throw(Error)`	`expect(fn, 'to throw', Error)`
`expect(x).to.be.empty`	`expect(x, 'to be empty')`

Negation is supported:

Chai	bupkis
`expect(x).to.not.equal(y)`	`expect(x, 'not to be', y)`
`expect(x).not.to.equal(y)`	`expect(x, 'not to be', y)`

TDD Style (assert)

Chai	bupkis
`assert.equal(x, y)`	`expect(x, 'to be', y)`
`assert.strictEqual(x, y)`	`expect(x, 'to be', y)`
`assert.deepEqual(x, y)`	`expect(x, 'to deep equal', y)`
`assert.isTrue(x)`	`expect(x, 'to be true')`
`assert.isFalse(x)`	`expect(x, 'to be false')`
`assert.isNull(x)`	`expect(x, 'to be null')`
`assert.isUndefined(x)`	`expect(x, 'to be undefined')`
`assert.isOk(x)`	`expect(x, 'to be truthy')`
`assert.isArray(x)`	`expect(x, 'to be a', 'array')`
`assert.isString(x)`	`expect(x, 'to be a', 'string')`
`assert.typeOf(x, 'string')`	`expect(x, 'to be a', 'string')`
`assert.instanceOf(x, Y)`	`expect(x, 'to be an instance of', Y)`
`assert.property(x, 'y')`	`expect(x, 'to have property', 'y')`
`assert.lengthOf(x, 3)`	`expect(x, 'to have length', 3)`
`assert.include(x, y)`	`expect(x, 'to contain', y)`
`assert.match(x, /foo/)`	`expect(x, 'to match', /foo/)`
`assert.isAbove(x, 5)`	`expect(x, 'to be greater than', 5)`
`assert.isBelow(x, 10)`	`expect(x, 'to be less than', 10)`
`assert.throws(fn)`	`expect(fn, 'to throw')`
`assert.isEmpty(x)`	`expect(x, 'to be empty')`

Negated assertions (assert.notEqual, assert.isNotTrue, etc.) are also supported.

Chai Plugins

The following plugins are supported:

chai-as-promised:

Chai	bupkis
`expect(p).to.eventually.equal(y)`	`expect(p, 'to be fulfilled with', y)`
`expect(p).to.be.fulfilled`	`expect(p, 'to be fulfilled')`
`expect(p).to.be.rejected`	`expect(p, 'to be rejected')`
`expect(p).to.be.rejectedWith(E)`	`expect(p, 'to be rejected with', E)`

chai-string:

Chai	bupkis
`expect(s).to.startWith('x')`	`expect(s, 'to start with', 'x')`
`expect(s).to.endWith('x')`	`expect(s, 'to end with', 'x')`

chai-subset:

Chai	bupkis
`expect(x).to.containSubset(y)`	`expect(x, 'to satisfy', y)`

Plugin imports and chai.use() calls are automatically removed.

Import Handling

The transformer automatically:

Replaces import { expect } from 'chai' with import { expect } from 'bupkis'
Removes import { assert } from 'chai' (TDD assertions become expect() calls)
Removes all chai-* plugin imports
Removes all chai.use() calls
Warns about unrecognized plugins passed to chai.use()

Options

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

Handling Unsupported Assertions

In best-effort mode (default), unsupported assertions are preserved with a TODO comment:

// TODO: Manual migration needed - unsupported matcher 'someObscureMatcher'
expect(x).to.someObscureMatcher(y);

Search for "TODO: Manual migration needed" in your codebase after running the transform to find items requiring manual review.

License

Blue Oak Model License 1.0.0