mirror of
https://github.com/oven-sh/bun
synced 2026-02-12 11:59:00 +00:00
011e157cac
* Restructure * Update nav * Reorg * Reshuffle ecosystem pages * Split up runtime/runtime * Back to runtime/index * Fix issue * Split up runtime/index * Add Writing Tests page * Prettier matcher table * More updates
358 lines
6.7 KiB
Markdown
358 lines
6.7 KiB
Markdown
Define tests with a Jest-like API imported from the built-in `bun:test` module. Long term, Bun aims for complete Jest compatibility; at the moment, a [limited set](#matchers) of `expect` matchers are supported.
|
|
|
|
## Basic usage
|
|
|
|
To define a simple test:
|
|
|
|
```ts#math.test.ts
|
|
import { expect, test } from "bun:test";
|
|
|
|
test("2 + 2", () => {
|
|
expect(2 + 2).toBe(4);
|
|
});
|
|
```
|
|
|
|
Tests can be grouped into suites with `describe`.
|
|
|
|
```ts#math.test.ts
|
|
import { expect, test, describe } from "bun:test";
|
|
|
|
describe("arithmetic", () => {
|
|
test("2 + 2", () => {
|
|
expect(2 + 2).toBe(4);
|
|
});
|
|
|
|
test("2 * 2", () => {
|
|
expect(2 * 2).toBe(4);
|
|
});
|
|
});
|
|
```
|
|
|
|
Tests can be `async`.
|
|
|
|
```ts
|
|
import { expect, test } from "bun:test";
|
|
|
|
test("2 * 2", async () => {
|
|
const result = await Promise.resolve(2 * 2);
|
|
expect(result).toEqual(4);
|
|
});
|
|
```
|
|
|
|
Alternatively, use the `done` callback to signal completion. If you include the `done` callback as a parameter in your test definition, you _must_ call it or the test will hang.
|
|
|
|
```ts
|
|
import { expect, test } from "bun:test";
|
|
|
|
test("2 * 2", done => {
|
|
Promise.resolve(2 * 2).then(result => {
|
|
expect(result).toEqual(4);
|
|
done();
|
|
});
|
|
});
|
|
```
|
|
|
|
Skip individual tests with `test.skip`.
|
|
|
|
```ts
|
|
import { expect, test } from "bun:test";
|
|
|
|
test.skip("wat", () => {
|
|
// TODO: fix this
|
|
expect(0.1 + 0.2).toEqual(0.3);
|
|
});
|
|
```
|
|
|
|
## Setup and teardown
|
|
|
|
Perform per-test setup and teardown logic with `beforeEach` and `afterEach`.
|
|
|
|
```ts
|
|
import { expect, test } from "bun:test";
|
|
|
|
beforeEach(() => {
|
|
console.log("running test.");
|
|
});
|
|
|
|
afterEach(() => {
|
|
console.log("done with test.");
|
|
});
|
|
|
|
// tests...
|
|
```
|
|
|
|
Perform per-scope setup and teardown logic with `beforeAll` and `afterAll`. At the top-level, the _scope_ is the current file; in a `describe` block, the scope is the block itself.
|
|
|
|
```ts
|
|
import { expect, test, beforeAll, afterAll } from "bun:test";
|
|
|
|
let db: Database;
|
|
beforeAll(() => {
|
|
// connect to database
|
|
db = initializeDatabase();
|
|
});
|
|
|
|
afterAll(() => {
|
|
// close connection
|
|
db.close();
|
|
});
|
|
|
|
// tests...
|
|
```
|
|
|
|
## Matchers
|
|
|
|
Bun implements the following matchers. Full Jest compatibility is on the roadmap; track progress [here](https://github.com/oven-sh/bun/issues/1825).
|
|
|
|
{% table %}
|
|
|
|
- 🟢
|
|
- [`.not`](https://jestjs.io/docs/expect#not)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBe()`](https://jestjs.io/docs/expect#tobevalue)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toEqual()`](https://jestjs.io/docs/expect#toequalvalue)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeNull()`](https://jestjs.io/docs/expect#tobenull)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeUndefined()`](https://jestjs.io/docs/expect#tobeundefined)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeNaN()`](https://jestjs.io/docs/expect#tobenan)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeDefined()`](https://jestjs.io/docs/expect#tobedefined)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeFalsy()`](https://jestjs.io/docs/expect#tobefalsy)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeTruthy()`](https://jestjs.io/docs/expect#tobetruthy)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toContain()`](https://jestjs.io/docs/expect#tocontainitem)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toStrictEqual()`](https://jestjs.io/docs/expect#tostrictequalvalue)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toThrow()`](https://jestjs.io/docs/expect#tothrowerror)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toHaveLength()`](https://jestjs.io/docs/expect#tohavelengthnumber)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toHaveProperty()`](https://jestjs.io/docs/expect#tohavepropertykeypath-value)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.extend`](https://jestjs.io/docs/expect#expectextendmatchers)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.anything()`](https://jestjs.io/docs/expect#expectanything)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.any()`](https://jestjs.io/docs/expect#expectanyconstructor)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.arrayContaining()`](https://jestjs.io/docs/expect#expectarraycontainingarray)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.assertions()`](https://jestjs.io/docs/expect#expectassertionsnumber)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.closeTo()`](https://jestjs.io/docs/expect#expectclosetonumber-numdigits)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.hasAssertions()`](https://jestjs.io/docs/expect#expecthasassertions)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.objectContaining()`](https://jestjs.io/docs/expect#expectobjectcontainingobject)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.stringContaining()`](https://jestjs.io/docs/expect#expectstringcontainingstring)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.stringMatching()`](https://jestjs.io/docs/expect#expectstringmatchingstring--regexp)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.addSnapshotSerializer()`](https://jestjs.io/docs/expect#expectaddsnapshotserializerserializer)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.resolves()`](https://jestjs.io/docs/expect#resolves)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.rejects()`](https://jestjs.io/docs/expect#rejects)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveBeenCalled()`](https://jestjs.io/docs/expect#tohavebeencalled)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveBeenCalledTimes()`](https://jestjs.io/docs/expect#tohavebeencalledtimesnumber)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveBeenCalledWith()`](https://jestjs.io/docs/expect#tohavebeencalledwitharg1-arg2-)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveBeenLastCalledWith()`](https://jestjs.io/docs/expect#tohavebeenlastcalledwitharg1-arg2-)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveBeenNthCalledWith()`](https://jestjs.io/docs/expect#tohavebeennthcalledwithnthcall-arg1-arg2-)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveReturned()`](https://jestjs.io/docs/expect#tohavereturned)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveReturnedTimes()`](https://jestjs.io/docs/expect#tohavereturnedtimesnumber)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveReturnedWith()`](https://jestjs.io/docs/expect#tohavereturnedwithvalue)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveLastReturnedWith()`](https://jestjs.io/docs/expect#tohavelastreturnedwithvalue)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toHaveNthReturnedWith()`](https://jestjs.io/docs/expect#tohaventhreturnedwithnthcall-value)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toBeCloseTo()`](https://jestjs.io/docs/expect#tobeclosetonumber-numdigits)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeGreaterThan()`](https://jestjs.io/docs/expect#tobegreaterthannumber--bigint)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeGreaterThanOrEqual()`](https://jestjs.io/docs/expect#tobegreaterthanorequalnumber--bigint)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeLessThan()`](https://jestjs.io/docs/expect#tobelessthannumber--bigint)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeLessThanOrEqual()`](https://jestjs.io/docs/expect#tobelessthanorequalnumber--bigint)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toBeInstanceOf()`](https://jestjs.io/docs/expect#tobeinstanceofclass) (Bun v0.5.8+)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toContainEqual()`](https://jestjs.io/docs/expect#tocontainequalitem)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toMatch()`](https://jestjs.io/docs/expect#tomatchregexp--string)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toMatchObject()`](https://jestjs.io/docs/expect#tomatchobjectobject)
|
|
|
|
---
|
|
|
|
- 🟢
|
|
- [`.toMatchSnapshot()`](https://jestjs.io/docs/expect#tomatchsnapshotpropertymatchers-hint) (Bun v0.5.8+)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toMatchInlineSnapshot()`](https://jestjs.io/docs/expect#tomatchinlinesnapshotpropertymatchers-inlinesnapshot)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toThrowErrorMatchingSnapshot()`](https://jestjs.io/docs/expect#tothrowerrormatchingsnapshothint)
|
|
|
|
---
|
|
|
|
- 🔴
|
|
- [`.toThrowErrorMatchingInlineSnapshot()`](https://jestjs.io/docs/expect#tothrowerrormatchinginlinesnapshotinlinesnapshot)
|
|
|
|
{% /table %}
|