Chai.js Cheatsheet - expect, should & assert Assertions

expect(value).to.equal(expected) passes the subject as the first argument and puts the assertion after it; the should style hangs the assertion off the subject, as in value.should.be.a("string"). Two practical differences: expect reads fine with strict null checking in editors, while should works by adding a property to the object — calling .should on null or undefined throws immediately, so nullable values must be asserted with expect, as in expect(value).to.not.be.null. assert is the TDD flavour, written assert.equal(actual, expected), and looks like classic unit-testing frameworks. Pick one per project and stay consistent.

expect(value).to.equal(expected) is strict equality (===) on references or primitives, so expect([1,2]).to.equal([1,2]) fails — those are two distinct array objects. Only expect(value).to.deep.equal(obj), short form .to.eql, walks the structure recursively and matches arrays and nested objects. Related: expect(obj).to.have.own.property("key") checks own properties without walking the prototype chain, and expect(obj).to.have.nested.property("a.b.c") asserts along a path. When an assertion fails on values that look identical, check for a missing deep first — that is by far the most common cause.

The expect style offers four granularities: expect(fn).to.throw(Error) checks only the exception type, expect(fn).to.throw("error message") requires an exact message, expect(fn).to.throw(/message/) matches part of it with a regex, and expect(fn).to.not.throw() asserts the happy path. The critical detail is passing the function itself, not its result — expect(fn()).to.throw() evaluates fn first, so the exception escapes before the assertion runs. The assert equivalents are assert.throws(fn, TypeError) and assert.doesNotThrow(fn). To mark a branch that should be unreachable, use assert.fail(actual, expected, "message") so the test fails loudly rather than passing silently.

Async assertions are not in chai core — they come from plugins. chai-as-promised is the common one, adding the eventually modifier so expect(promise).to.eventually.equal("resolved") awaits settlement before comparing, with the rejected form used to assert the failure reason, e.g. expect(promise).to.be.rejectedWith(Error). HTTP responses are chai-http: expect(res).to.have.status(200) validates both the status code and body. If your project already runs on Jest, its built-in resolves and rejects matchers cover these cases and the plugins are unnecessary.

expect(arr).to.include(item) only requires that the element be present — extra elements do not affect the result, which suits "the item the user is looking for is in there". expect(arr).to.have.members([1, 2, 3]) demands exact correspondence: same length and same values, suited to snapshot-style whole-collection checks. expect(obj).to.include({ key: "value" }) is the object counterpart, comparing only the named keys rather than the whole object. For strings use expect(str).to.have.string("bar") for substring matching, and for numbers the above / below / at.least / within(1, 10) family. Picking the wrong one yields assertions that are too loose or too strict.