chaijs.com

Chai runs in three environments listed on chaijs.com: Node, Browser, and Rails. The same assertion library is available across all three, so you can use one assertion style whether your tests execute in a Node.js process, in a browser, or inside a Rails application. The only condition is that you install or load the build intended for that platform — the site presents them as separate entry points rather than one universal bundle.

The three supported platforms

The site's platform switcher labels these as "for Node," "for Browser," and "for Rails," each with links to the other two. That structure tells you the documentation is organized per platform, so setup instructions differ depending on which one you pick.

What stays the same across platforms

Chai describes itself as a BDD / TDD assertion library for Node and the browser that can be paired with any JavaScript testing framework. Two consequences follow:

• Framework independence. Chai is not tied to a specific test runner. It supplies assertions; the testing framework supplies the test structure and reporting.
• Interface choice is separate from platform choice. Chai offers several interfaces so the developer can pick the most comfortable one. The chain-capable BDD styles provide an expressive, readable language for assertions. This choice applies regardless of whether you are running in Node, a browser, or Rails.

Plugins and extension

Plugins extend Chai's assertions to new contexts such as vendor integration and object construction, and developers can build their own plugins to share with the community. If your target platform needs assertions Chai does not ship by default, a plugin is the intended extension path rather than a platform limitation.

How to decide

• Testing server-side JavaScript or a Node-based test runner → use the Node build.
• Testing code that executes in a browser → use the Browser build.
• Working inside a Rails application → Rails is listed as a supported platform; follow the Rails-specific setup rather than assuming the Node instructions apply.

If you are unsure, start from the platform switcher on chaijs.com and read the page for the environment your tests actually run in — the assertion interfaces and plugin model carry over, but the loading and installation steps are platform-specific.

Yes. Chai is built as a standalone assertion library, not a test runner, so it is designed to be paired with any JavaScript testing framework. According to the official description on chaijs.com, Chai "can be delightfully paired with any javascript testing framework." The only practical requirement is that your test framework lets you run arbitrary assertion code inside a test case, which essentially all of them do.

Why Chai Is Framework-Agnostic

Chai's scope is deliberately narrow: it provides assertions, not test structure. It does not define describe, it, test discovery, reporters, or the runner loop. Those responsibilities belong to the testing framework.

This separation means:

• The framework decides when a test runs. Chai only decides whether an expectation passes or throws.
• Chai has no dependency on a specific runner. Nothing in its interface assumes Mocha, Jest, Jasmine, or any other tool.
• You can swap either side independently. Change the runner without rewriting assertions, or change the assertion style without touching test structure.

The chaijs.com page lists support for Node, Browser, and Rails, and notes that Chai offers several interfaces so developers can choose the most comfortable style. None of those interfaces are tied to a particular test framework.

How the Two Pieces Fit Together

A typical test file combines a framework's structure with Chai's assertions:

// The framework provides describe/it (example: Mocha-style API)
describe('array', function () {
  it('starts empty', function () {
    const arr = [];
    // Chai provides the assertion
    expect(arr).to.have.lengthOf(0);
  });
});

The input is your test case body; the action is calling a Chai assertion; the expected result is that the assertion throws on failure and returns quietly on success. The framework catches that throw and reports it as a failed test. That contract is what makes Chai portable.

Choosing an Interface That Fits Your Setup

Chai's interfaces are a separate decision from your test framework. The site describes chain-capable BDD styles as providing "an expressive language & readable style," and notes that plugins extend Chai's assertions to new contexts such as vendor integration and object construction.

You can pick whichever reads best in your existing tests; the choice does not constrain which framework you use.

Practical Conditions to Check

Before introducing Chai into an existing test setup, confirm:

1. Your framework allows custom assertions. Most do, since assertions are just functions that throw.
2. You are not duplicating an assertion library. If your framework already ships a full assertion API, adding Chai is optional, not required.
3. Your environment is supported. Chai runs in Node and the browser per the site; for other environments, verify compatibility yourself.
4. You install and import it correctly. Chai is a library you add to your project and import into test files; the site does not state pricing or login requirements, so treat availability as a normal package dependency.

What This Means for You

If you already have a test framework and want more expressive assertions, Chai can be added without replacing the runner. If you are starting fresh, you can choose the runner and the assertion style independently. The main thing Chai will not do is run your tests for you — that stays with your framework.

Chai is a BDD/TDD assertion library for Node.js and the browser. It is designed to be paired with any JavaScript testing framework, so it does not replace your test runner — it supplies the assertions you write inside your tests. If you already have a test framework (Mocha, Jest, Jasmine, etc.) and want a more expressive or flexible way to assert outcomes, Chai is the piece you add.

Where Chai fits in a JavaScript test setup

A typical JavaScript test stack has two distinct roles:

• Test framework / runner — discovers and runs tests, reports pass/fail (e.g. Mocha, Jest).
• Assertion library — expresses what the test expects to be true (e.g. Chai).

Chai occupies the second role. Its own description states it "can be delightfully paired with any javascript testing framework," which means the choice of runner and the choice of assertion style are independent decisions.

Chai runs in two environments, both listed on the site:

• Node — for server-side and tooling tests.
• Browser — for tests executed in a browser context.

The site also lists a Rails option alongside Node and Browser, so Chai is not limited to a pure JavaScript toolchain.

The interfaces: why Chai offers more than one style

Chai's distinguishing feature is that it ships several interfaces, letting the developer "choose the most comfortable." The site highlights the chain-capable BDD styles as providing "an expressive language & readable style."

In practice this means you pick the assertion syntax that matches how your team reads tests, rather than being locked into one. The BDD-style interfaces are chainable, so assertions read close to natural language. The TDD-style interface follows a more traditional assert-function form. Because all interfaces sit on the same library, switching styles does not mean switching dependencies.

Plugins and extensibility

Chai supports plugins that "extend Chai's assertions to new contexts such as vendor integration & object construction." Two practical consequences:

• Vendor integration — you can add assertions tailored to a specific library or platform instead of writing manual checks.
• Object construction — assertions can be extended to cover how objects are built, not just their final values.

The site also notes that developers "can build their own plugins to share with community," so if an assertion you need does not exist, writing and publishing one is an intended path rather than a workaround.

When Chai is a good fit

Choose Chai when:

• You want assertions decoupled from your test runner.
• You want to pick between BDD-style and TDD-style syntax, or mix readable chained assertions into an existing suite.
• You need to extend assertions for a specific vendor or object-construction pattern.

Chai may be unnecessary when your test framework already provides an assertion style you are satisfied with and you have no need for alternative interfaces or plugins — in that case adding Chai is an extra dependency without a clear gain.

Getting oriented on the site

The homepage is organized around platform entry points — Node, Browser, and Rails — each with links to the other platforms. Start from the platform you are testing in, then move to the interface documentation to choose a style. The plugin material is worth reading before you write custom assertions, since an existing plugin may already cover your case.

Chai plugins extend the library by registering new assertions, properties, or chain methods onto Chai's core, so that expect, assert, and should can express checks the base library does not cover. According to Chai's own documentation, plugins "extend Chai's assertions to new contexts such as vendor integration & object construction," and developers can build their own plugins to share with the community. You would reach for a plugin when your test suite needs domain-specific assertions — for example, checking a framework-specific object shape or a vendor SDK's response — rather than writing the same manual comparison in every test.

What a plugin actually adds

Chai's core gives you a set of built-in assertions and chain-capable BDD styles. A plugin hooks into that same assertion system and adds to it, so the new checks behave like native ones: they participate in the same chaining language and are available across the interfaces Chai supports.

The documentation frames the benefit in two directions:

• New contexts — assertions that make sense for a particular library, framework, or vendor, instead of generic value comparisons.
• Object construction — assertions that reason about how an object was built or what it represents, not just its current value.

Because the plugin registers into Chai rather than wrapping it, you keep one consistent assertion style instead of mixing Chai with ad-hoc helper functions.

Why the plugin model matters for your test suite

The practical gain is readability and reuse: a well-named custom assertion documents what the test is verifying, and packaging it as a plugin means the same check can be reused across files, projects, or the wider community.

Can you write your own?

Yes. The documentation states that developers can build their own plugins to share with the community. That means the extension path is open to you, not limited to a fixed set of official add-ons — if your team has a recurring assertion need, it can become a plugin.

Before writing one, confirm two things:

1. The assertion is genuinely reusable. A one-off check is usually clearer as a local helper; a plugin pays off when the same assertion appears across many tests or projects.
2. It fits Chai's assertion model. Plugins extend assertions into new contexts, so the check should express a condition on a value or object, consistent with how Chai assertions read.

Choosing between a plugin and a plain helper

• Use a plugin when the assertion is domain-specific, used repeatedly, and you want it to chain and read like a native Chai assertion.
• Use a plain helper function when the logic is a one-off, or when it is really test setup rather than an assertion.
• Use built-in assertions when they already express the check — adding a plugin for something deep.equal or include already covers adds a dependency without benefit.

Where plugins run

Chai is a BDD / TDD assertion library for Node and the browser, and it can be paired with any JavaScript testing framework. Plugins extend Chai itself, so they follow Chai into whichever of those environments you use — the same extension applies whether your tests run under Node or in a browser, and regardless of which testing framework drives them.

Chai ships with three assertion interfaces — expect, should, and assert — and you pick one per test file (or per project) based on how much you want your assertions to read like English versus how explicitly you want them to behave. expect and should are the BDD styles; assert is the TDD style. All three run on Node and in the browser, and all three can be paired with any JavaScript testing framework.

The three interfaces at a glance

The BDD styles are chain-capable: you build a sentence out of language chains and end it with an assertion. The TDD style is a flat set of assertion functions with no chaining.

expect: the BDD style without side effects

expect wraps a value and exposes the full chainable language, but it does not touch any built-in prototypes. That makes it the safest default when you are unsure which style to choose.

const { expect } = require('chai');

expect([1, 2, 3]).to.have.lengthOf(3);
expect({ name: 'chai' }).to.have.property('name').that.equals('chai');
expect(() => { throw new Error('boom'); }).to.throw('boom');

What you get: readable, sentence-like assertions and a single import. What you give up: nothing structural — the only cost is that every assertion starts with expect(...) rather than reading as a bare property on the value.

should: the same language, attached to the object

should uses the identical chain vocabulary as expect, but it extends Object.prototype so assertions hang directly off the value.

const chai = require('chai');
chai.should();

[1, 2, 3].should.have.lengthOf(3);
({ name: 'chai' }).should.have.property('name', 'chai');

The trade-offs are the reason many teams avoid it:

• Prototype pollution. Extending Object.prototype can collide with other libraries or with your own code, and it is a common reason teams standardize on expect instead.
• null and undefined cannot be asserted directly. should needs a real object to attach to, so null.should throws before your assertion ever runs. You have to route those cases through expect or assert.
• Setup is required. You must call chai.should() before the assertions run, which is easy to forget in a fresh file.

If your values are always defined objects and you like the bare-property reading, should is pleasant. Otherwise expect gives you the same language with none of these caveats.

assert: the TDD style

assert is a function-per-check interface with no chaining and no language chains. It is closer to Node's built-in assert module in feel.

const { assert } = require('chai');

assert.lengthOf([1, 2, 3], 3);
assert.property({ name: 'chai' }, 'name');
assert.throws(() => { throw new Error('boom'); }, 'boom');

What you get: explicit, predictable calls that are easy to grep and easy to read in a diff. What you give up: the expressive, sentence-like quality of the BDD styles — assert.lengthOf(list, 3) states a fact, while expect(list).to.have.lengthOf(3) reads as a sentence.

How to choose

• Pick expect if you want the readable BDD language and want to avoid modifying built-in prototypes. This is the most common choice and the safest default.
• Pick should only if you specifically want assertions to hang off the value itself, and you are comfortable with prototype extension and the null/undefined limitation.
• Pick assert if your team prefers explicit function calls, minimal magic, and assertions that read the same way regardless of context.

You do not have to commit globally: the three interfaces are independent exports, so a project can use expect in most files and assert where an explicit call reads better. Mixing them within a single file is possible but usually hurts consistency more than it helps.

Beyond the core interfaces

Chai's assertion set is extensible. Plugins add assertions for new contexts such as vendor integration and object construction, and developers can write their own plugins to share with the community. That means the interface you choose is not a ceiling — you can extend whichever style you pick with domain-specific assertions.