assert-json-object

🧪 Fluent, chainable assertions for JSON structures with dot-path access.

✨ Features

• Assert deeply nested JSON properties using dot-paths (e.g. "foo.bar[0].baz")
• Type and value assertions
• Predicate-based assertions
• Negation (not) support
• Soft assertion mode: collect all errors instead of throwing immediately
• TypeScript support
• 🪶 Zero dependencies

📦 Install

npm install assert-json-object

🚀 Usage

import { assertJson } from "assert-json-object";

const data = {
  user: {
    name: "Alice",
    age: 30,
    tags: ["admin", "editor"],
    address: { city: "NYC" },
  },
};

const assertion = assertJson(data);

assertion
  .toHaveKey("user.name")
  .toBeType("user.age", "number")
  .toMatchValue("user.address.city", "NYC")
  .not.toHaveKey("user.password");
// No error thrown

Soft Assertion Mode

Collect all assertion errors and inspect them later:

const assertion = assertJson(data, { soft: true });

assertion
  .toHaveKey("user.name")
  .toBeType("user.age", "string") // error
  .toMatchValue("user.address.city", "LA") // error
  .not.toHaveKey("user.name"); // error

console.log(assertion.getErrors());

⚙️ API

assertJson(data, options?)

• data: The JSON object to assert on.
• options.soft (optional): If true, enables soft assertion mode.

Returns a JsonAssertion instance.

Assertion Methods

| Method | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | .toHaveKey(path) | Asserts that the given dot-path exists. | | .toBeType(path, type) | Asserts the value at path is of the given type (string, number, boolean, object, array, undefined, null). | | .toMatchValue(path, expected) | Asserts the value at path equals the expected value (deep equality). | | .toSatisfy(path, predicate) | Asserts the value at path satisfies the predicate function. | | .not | Negates the next assertion. | | .getErrors() | Returns an array of errors (only in soft mode). |

✅ Examples

Basic

assertJson({ foo: 1 }).toHaveKey("foo").toBeType("foo", "number");
// No error thrown

Negation

assertJson({ foo: 1 }).not.toHaveKey("bar");
// No error thrown

assertJson({ foo: 1 }).not.toHaveKey("foo");
// Throws: Error: Expected key 'foo' not to exist

Array Indexing

const data = { arr: [{ id: 1 }, { id: 2 }] };
assertJson(data).toHaveKey("arr[1].id").toMatchValue("arr[0].id", 1);
// No error thrown

assertJson(data).toHaveKey("arr[2].id");
// Throws: Error: Expected key 'arr[2].id' to exist

Soft Assertion

const assertion = assertJson({ foo: 1 }, { soft: true });
assertion.toHaveKey("foo").toBeType("foo", "string"); // error

console.log(assertion.getErrors().length);
// Output: 1

console.log(assertion.getErrors()[0].message);
// Output: Expected 'foo' to be type 'string', but got 'number'

🧩 More Examples

Type and Value Checks

const data = { a: 123, b: "hello", c: null, d: [1, 2], e: { x: 1 } };

assertJson(data)
  .toBeType("a", "number")
  .toBeType("b", "string")
  .toBeNull("c")
  .toBeType("d", "array")
  .toBeType("e", "object")
  .toBeDefined("a")
  .toBeTruthy("b")
  .toBeFalsy("c");

Array and String Containment

const data = { arr: [1, 2, 3], str: "hello world" };

assertJson(data).toContainValue("arr", 2).toContainValue("str", "world").not.toContainValue("arr", 5);

Numeric Comparisons

const data = { score: 42 };

assertJson(data)
  .toBeGreaterThan("score", 10)
  .toBeLessThan("score", 100)
  .not.toBeGreaterThan("score", 100)
  .not.toBeLessThan("score", 10);

One Of / Enum

const data = { status: "pending" };

assertJson(data).toBeOneOf("status", ["pending", "done", "failed"]).not.toBeOneOf("status", ["archived"]);

Custom Predicate

const data = { value: 15 };

assertJson(data)
  .toSatisfy("value", (v) => typeof v === "number" && v % 5 === 0)
  .not.toSatisfy("value", (v) => v < 0);

🔎 More Matchers

| Method | Description | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | .toHaveKey(path) | Asserts that the given dot-path exists. | | .not.toHaveKey(path) | Asserts that the given dot-path does NOT exist. | | .toBeType(path, type) | Asserts the value at path is of the given type (string, number, boolean, object, array, undefined, null). | | .toBeDefined(path) | Asserts the value at path is defined (not undefined). | | .toBeNull(path) | Asserts the value at path is null. | | .toBeTruthy(path) | Asserts the value at path is truthy. | | .toBeFalsy(path) | Asserts the value at path is falsy. | | .toMatchValue(path, expected) | Asserts the value at path equals the expected value (deep equality). | | .toContainValue(path, value) | Asserts the value at path (array or string) contains the given value. | | .toBeGreaterThan(path, number) | Asserts the value at path is a number greater than the given number. | | .toBeLessThan(path, number) | Asserts the value at path is a number less than the given number. | | .toBeOneOf(path, [values]) | Asserts the value at path matches any value in the provided array (deep equality). | | .toSatisfy(path, predicate) | Asserts the value at path satisfies the predicate function. | | .not | Negates the next assertion. | | .getErrors() | Returns an array of errors (only in soft mode). |

📄 License

MIT © jaktestowac.pl

Powered by jaktestowac.pl team!