from-chai

@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