extending 'assert' assertion flavor

[gullerya]

There is a documentation of extending the expect assertion APIs.

Is there a way (and documentation) how to plugin custom assertions into assert API?

[agammann]

Yes. A plugin receives Chai's assert object as well as Assertion. Add your function to chai.assert inside the plugin; extending Assertion alone does not automatically create an assert helper.

For example, this exposes the same check through both interfaces:

import * as chai from "chai";

function evenPlugin(chai) {
  chai.Assertion.addMethod("even", function () {
    this.assert(
      Number.isInteger(this._obj) && this._obj % 2 === 0,
      "expected #{this} to be an even integer",
      "expected #{this} not to be an even integer"
    );
  });

  chai.assert.isEven = function (value, message) {
    new chai.Assertion(value, message, chai.assert.isEven)
      .to.be.even();
  };
}

chai.use(evenPlugin);
chai.assert.isEven(2);
chai.expect(2).to.be.even();

The wrapper passes the optional message and delegates to the existing assertion, so failures remain AssertionErrors. Choose a helper name that does not overwrite a built-in assertion.

I tested this with Chai 4.3.10 and 6.2.2, including odd values, non-integers, a custom message, and negated expect assertions. For a Chai 4 CommonJS project, replace the import with const chai = require("chai").

See Core Plugin Concepts for plugin registration and assertion construction. Chai's own assert.isOk implementation uses the same pattern of a function on assert wrapping an Assertion.