Jest Joi

expect(value).toMatchSchema(schema);

Matchers for validating values against Joi schemas in Jest tests, with awesome error messages and TypeScript support

For a quick demo, head over to RunKit!

Setup

1npm i -D jest-joi

TypeScript

(e.g. via ts-jest)

1// jest.setup.ts
2// Note: Make sure this is within the scope of your TypeScript config!
3import { matchers } from "jest-joi";
4expect.extend(matchers);

1// jest.config.ts
2export default {
3  setupFilesAfterEnv: ["./jest.setup.ts"],
4};

JavaScript

1// jest.setup.js
2const jestJoi = require("jest-joi");
3expect.extend(jestJoi.matchers);

1// jest.config.js
2module.exports = {
3  setupFilesAfterEnv: ["./jest.setup.js"],
4};

For more configuration options, see the Jest configuration docs, especially the setupFilesAfterEnv property.

Usage

Just call the .toMatchSchema() matcher with the Joi schema to validate the value against:

1expect(value).toMatchSchema(schema);

Options may be passed as an optional second parameter:

1expect(value).toMatchSchema(schema, options);

When the value doesn't match the schema, Jest Joi will provide detailed error messages:

1// Simple mismatches describe the error:
2
3test("Value should match schema", () => {
4  const schema = Joi.string();
5  const value = 3;
6  expect(value).toMatchSchema(schema);
7});
8
9// [FAIL]  src/schema.spec.ts
10//  ✕ Value should match schema
11//
12//    expect(received).toMatchSchema(schema)
13//
14//    Received: 3
15//    Expected: Received must be a string

1// Complex mismatches annotate the value:
2
3test("Value should match schema", () => {
4  const schema = Joi.object({
5    a: Joi.string(),
6  });
7  const value = {
8    a: false,
9  };
10  expect(value).toMatchSchema(schema);
11});
12
13// [FAIL]  src/schema.spec.ts
14//  ✕ Value should match schema
15//
16//    expect(received).toMatchSchema(schema)
17//
18//    Received:
19//    {
20//      "a" [1]: false
21//    }
22//
23//    [1] "a" must be a string

1// Negated matches display the schema:
2
3test("Value should not match schema", () => {
4  const schema = Joi.string();
5  const value = "a";
6  expect(value).not.toMatchSchema(schema);
7});
8
9// [FAIL]  src/schema.spec.ts
10//  ✕ Value should not match schema
11//
12//    expect(received).not.toMatchSchema(schema)
13//
14//    Received: "a"
15//    Schema: { type: "string" }

1// Options can be passed as a second argument:
2
3test("Value should match schema with options", () => {
4  const schema = Joi.object({});
5  const value = {
6    b: true,
7  };
8  const options = {
9    allowUnknown: false,
10  };
11  expect(value).toMatchSchema(schema, options);
12});
13
14// FAIL  src/schema.spec.ts
15//  ✕ Value should match schema with options (7ms)
16//
17//    expect(received).toMatchSchema(schema)
18//
19//    Received:
20//    {
21//      "b" [1]: true
22//    }
23//
24//    [1] "b" is not allowed

Matchers

Jest Joi includes matchers both for validating values against a schema, and for validating schemas themselves.

toMatchSchema()

Pass a value to expect() to validate against the schema. The schema may be either a Joi schema object or a schema literal (which will be compiled using Joi.compile()).

1expect(value).toMatchSchema(schema, options?);

toBeSchema()

Pass a value to expect() to validate whether it's a Joi schema.

1expect(schema).toBeSchema();

toBeSchemaLike()

Pass a value to expect() to validate whether it's a Joi schema or a schema literal (a value that can be compiled using Joi.compile()).

1expect(schema).toBeSchemaLike();