Bupkis: Basic Usage

This guide covers the fundamentals of using BUPKIS for assertions in your tests.

Installation

Install BUPKIS as a development dependency:

npm install bupkis -D
Copy

Prerequisites

BUPKIS requires Node.js version ^20.19.0 || ^22.12.0 || >=23.

The library supports both ESM and CommonJS module systems, so you can use it with any modern Node.js project setup.

Importing

BUPKIS provides different import strategies depending on your needs:

Quick Start: Just Expect

If you want to start using assertions immediately with the built-in library:

import { expect } from 'bupkis';
Copy

Full Import: Building Custom Assertions

For creating custom assertions and accessing all utilities:

import {
  expect,
  expectAsync,
  createAssertion,
  createAsyncAssertion,
  use,
  z,
} from 'bupkis';
Copy

Namespace Imports

You can also import organized namespaces:

import { expect, assertion, guards, schema, util, error } from 'bupkis';

// Use assertion creation utilities
const myAssertion = assertion.createAssertion(['to be rad'], z.boolean());

// Use type guards
if (guards.isString(value)) {
  // value is guaranteed to be a string
}
Copy

Basic Assertion Usage

BUPKIS uses a natural language API instead of method chaining. Here's how it works in a typical test:

import { expect } from 'bupkis';

describe('Basic assertions', () => {
  it('should validate types', () => {
    expect('hello', 'to be a string');
    expect(42, 'to be a number');
    expect(true, 'to be a boolean');
  });

  it('should validate values', () => {
    expect(5, 'to equal', 5);
    expect('hello world', 'to contain', 'world');
    expect([1, 2, 3], 'to have length', 3);
  });

  it('should support negation', () => {
    expect(42, 'not to be a string');
    expect('hello', 'not to equal', 'goodbye');
  });

  it('should work with objects', () => {
    const user = { name: 'Alice', age: 30 };

    expect(user, 'to be an object');
    expect(user, 'to have property', 'name');
    expect(user, 'to satisfy', { name: 'Alice' });
  });
});
Copy

Assertion Errors

When an assertion fails, BUPKIS throws a standard AssertionError that's compatible with all major testing frameworks. Here are real examples of what these errors look like:

Simple Type Mismatch

expect(42, 'to be a string');
// AssertionError: Assertion "{unknown} 'to be a string'" failed: Invalid input: expected string, received number
// actual: 42
// expected: []
Copy

Value Comparison

expect('hello', 'to equal', 'goodbye');
// AssertionError: Expected 'hello' to equal 'goodbye'
// actual: hello
// expected: goodbye
Copy

Array Length Mismatch

expect([1, 2, 3], 'to have length', 5);
// AssertionError: Assertion "{array} 'to have length' {number}" failed for arguments: [ [ 1, 2, 3 ], 'to have length', 5 ]
Copy

Complex Object Validation

const user = { name: 'Alice', age: 30, role: 'user' };
expect(user, 'to satisfy', {
  name: 'Bob',
  age: 25,
  role: 'admin',
  department: 'engineering',
});
// AssertionError: Assertion "{object}! 'to satisfy' / 'to be like' {object}" failed: ; department: Invalid input: expected string, received undefined
// actual: {
//   "name": "Alice",
//   "age": 30,
//   "role": "user"
// }
// expected: {
//   "name": "Bob",
//   "age": 25,
//   "role": "admin",
//   "department": "engineering"
// }
Copy

Error Properties

All BUPKIS assertion errors include these standard properties:

• name: Always 'AssertionError' for compatibility with testing frameworks
• message: Human-readable description of what went wrong
• actual: The value that was tested (when available)
• expected: The expected value or pattern (when available)

The error messages are powered by Zod's validation system, providing detailed context about exactly why an assertion failed.

Next Steps

• About Assertions - Learn more about Assertions
• Custom Assertions - Learn how to create your own assertion types

The natural language approach makes tests more readable and self-documenting. Instead of remembering method names like toBeInstanceOf() or toHaveProperty(), you write what you mean: 'to be an instance of' or 'to have property'.