Kizu is a fast, minimalist test runner for TypeScript and JavaScript, with a small, easy-to-learn API that lets you focus on your tests — not your tooling.

Designed to help you write simple, readable, and maintainable tests.

Features

🚀 Fast & Reliable

• Multi-process parallel test runner. Each test file is run in its own process/runtime for performance and isolation benefits. Use on a multicore machine for best results.
• Optimized for speed and simplicity.
• Minimal dependencies.

😀 Easy to Use

• Very simple functional assertion API. No need to learn a DSL or framework.
• One assertion method does it all: assert.equal() handles primitives, objects, arrays, Maps, Sets, and even RegExp pattern matching!
• Built-in powerful diff visualization tool
• Clean, organized output.
• Failed tests are easy to find, grouped at the end of the output.
• Errors or unhandled promise rejections are buffered and grouped under the test file in the output. This helps you know where they came from.
• Clean stack traces with no extra noise.

🛡 Defensive

• Uncaught errors and unhandled promise rejections will cause the test to fail.
• Any spec files without tests, or tests without assertions, result in a failed test.
• Strict and deep equality comparison by default.

🔒 Out-of-the-box Typescript support

• No special configuration needed, and no plugins to install.
• Works great with c8 for code coverage.
• Handles compilation errors gracefully.

✨ Powerful assert.equal() - One Assertion to Rule Them All

The assert.equal() method is incredibly versatile and handles most of your testing needs:

• Primitive comparison: Numbers, strings, booleans, null, undefined
• Deep object equality: Compares nested objects, arrays, Maps, and Sets
• RegExp pattern matching: Test string values against RegExp patterns in the expected value
• Mixed comparisons: Combine exact values and RegExp patterns in the same object
• Visual diffs: Beautiful, detailed output when assertions fail
• Type safety: Full TypeScript support with proper type checking

Note: assert.equal() compares values by value (deep equality), not by reference.

This single assertion method eliminates the need for multiple specialized assertion methods or complex mocking while providing powerful, flexible testing capabilities.

Quick Examples

For more examples, see the examples and src folders.

# Run all tests in the src directory and its subdirectories, and only show failures in the output.
npx kizu 'src/**/*.test.ts' --fail-only
# Run a specific test file
npx kizu 'src/example.test.ts'

// example.test.ts

import {test} from 'kizu';

// Basic test
function greet(name: string): string {
  return `hello, ${name}`;
}

test('greet', (assert) => {
  assert.equal(greet('world'), 'hello, world');
});

// Deep object comparison
test('user object', (assert) => {
  const actual = {
    name: 'John',
    age: 30,
    email: 'john@example.com',
    preferences: {
      theme: 'dark',
      notifications: true
    }
  };
  
  const expected = {
    name: 'John',
    age: 30,
    email: 'john@example.com',
    preferences: {
      theme: 'dark',
      notifications: true
    }
  };
  
  assert.equal(actual, expected); // Deep equality comparison
});

// RegExp pattern matching ✨ NEW!
test('email validation', (assert) => {
  const email = 'user@example.com';
  
  // Match email pattern
  assert.equal(email, /^[^@]+@[^@]+\.[^@]+$/);
  
  // Match domain
  assert.equal(email, /@example\.com$/);
  
  // Match username
  assert.equal(email, /^user@/);
});

// Complex data structures
test('complex data', (assert) => {
  const actual = {
    users: [
      { name: 'Alice', email: 'alice@company.com' },
      { name: 'Bob', email: 'bob@company.com' }
    ],
    metadata: {
      count: 2,
      lastUpdated: '2024-01-15'
    }
  };
  
  const expected = {
    users: [
      { name: 'Alice', email: /@company\.com$/ }, // RegExp in nested objects!
      { name: 'Bob', email: /@company\.com$/ }
    ],
    metadata: {
      count: 2,
      lastUpdated: /^\d{4}-\d{2}-\d{2}$/ // Date pattern
    }
  };
  
  assert.equal(actual, expected);
});

// Error handling
function throwError(): never {
  throw new Error('oops');
}

test('throwError', (assert) => {
  assert.throws(() => throwError(), /oops/);
});

// Async test
async function fetchData(): Promise<string> {
  return Promise.resolve('data');
}

test('fetchData', async (assert) => {
  const data = await fetchData();
  assert.equal(data, 'data');
});

Table of Contents

• Quick Start
• CLI
• Test API
• Visual Diff Tool
• Example Tests
• Best Practices
• Inspiration, Philosophy & Attribution
• FAQ
• Support, Feedback, and Contributions
• Sponsorship
• License

Getting Started

To install and get started with kizu, see our Getting Started guide. See the examples and src folders for more examples.

Support, feedback, and contributions

• Star this repo if you like it!
• Submit an issue with your problem, feature request or bug report
• Issue a PR against main and request review. Make sure all tests pass and coverage is good.
• Write about this project in your blog, tweet about it, or share it with your friends!

Sponsorship

Aeroview is a lightning-fast, developer-friendly, AI-powered logging IDE. Get started for free at https://aeroview.io.

Want to sponsor this project? Reach out.

Related projects

• cjs-mock: NodeJS module mocking for CJS (CommonJS) modules for unit testing purposes.
• autorel: Automate semantic releases based on conventional commits. Similar to semantic-release but much simpler.
• brek: A powerful yet simple configuration library for Node.js. It’s structured, typed, and designed for dynamic configuration loading, making it perfect for securely managing secrets (e.g., AWS Secrets Manager).
• jsout: A Syslog-compatible, small, and simple logger for Typescript/Javascript projects.