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

npm i -D jest-joi

TypeScript

(e.g. via ts-jest)

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

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

JavaScript

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

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

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:

expect(value).toMatchSchema(schema);

Options may be passed as an optional second parameter:

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

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

// Simple mismatches describe the error:

test("Value should match schema", () => {
  const schema = Joi.string();
  const value = 3;
  expect(value).toMatchSchema(schema);
});

// [FAIL]  src/schema.spec.ts
//  ✕ Value should match schema
//
//    expect(received).toMatchSchema(schema)
//
//    Received: 3
//    Expected: Received must be a string

// Complex mismatches annotate the value:

test("Value should match schema", () => {
  const schema = Joi.object({
    a: Joi.string(),
  });
  const value = {
    a: false,
  };
  expect(value).toMatchSchema(schema);
});

// [FAIL]  src/schema.spec.ts
//  ✕ Value should match schema
//
//    expect(received).toMatchSchema(schema)
//
//    Received:
//    {
//      "a" [1]: false
//    }
//
//    [1] "a" must be a string

// Negated matches display the schema:

test("Value should not match schema", () => {
  const schema = Joi.string();
  const value = "a";
  expect(value).not.toMatchSchema(schema);
});

// [FAIL]  src/schema.spec.ts
//  ✕ Value should not match schema
//
//    expect(received).not.toMatchSchema(schema)
//
//    Received: "a"
//    Schema: { type: "string" }

// Options can be passed as a second argument:

test("Value should match schema with options", () => {
  const schema = Joi.object({});
  const value = {
    b: true,
  };
  const options = {
    allowUnknown: false,
  };
  expect(value).toMatchSchema(schema, options);
});

// FAIL  src/schema.spec.ts
//  ✕ Value should match schema with options (7ms)
//
//    expect(received).toMatchSchema(schema)
//
//    Received:
//    {
//      "b" [1]: true
//    }
//
//    [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()).

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

toBeSchema()

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

expect(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()).

expect(schema).toBeSchemaLike();