kizu

Kizu is a screamingly fast, minimalist test runner for TypeScript and JavaScript. It has 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 that do not slow you down.

Features

🚀 Fast & Reliable

• Fast, 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 even better results!
• Optimized for speed and simplicity.
• Minimal dependencies.

😀 Easy to Use

• Very simple functional assertion API. No need to learn a DSL or framework.
• Powerful assert.equal() assertion method handles primitives, deep objects, arrays, Maps, Sets, and even RegExp pattern matching. Uses strict equality and comparison by value. Helps keep your tests simple and readable.
• Built-in powerful diff visualization tool to help you debug failed assertions.
• 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.
• Automatically detects and uses your project's tsconfig.json and uses tsx for TypeScript compilation.
• Works great with c8 for code coverage out of the box (see getting started).
• Handles compilation errors gracefully.

⚛️ TSX/JSX Support

• Full support for TypeScript (TSX) and JavaScript (JSX) files
• Works with React, Preact, Solid, and other JSX-based frameworks
• Built-in React Testing Library integration with jsdom environment
• Type-safe testing with full TypeScript support

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 and show all output
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: '[e-mail]',
    hobbies: ['reading', 'coding', 'hiking'],
    preferences: {
      theme: 'dark',
      notifications: true
    }
  };
  const expected = {
    name: /^[A-Za-z]+$/,
    age: /^\d+$/,
    email: /^[^@]+@[^@]+\.[^@]+$/,
    hobbies: ['reading', 'coding', 'hiking'],
    preferences: {
      theme: 'dark',
      notifications: true
    }
  };
  
  assert.equal(actual, expected); // Complex & deep strict object comparison by value, type-safe, and with regular expressions!
});

// 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');
});

// React component testing
import React, { useState } from 'react';
import { render, screen, fireEvent, cleanup } from '@testing-library/react';

function Counter({ initialValue = 0 }) {
  const [count, setCount] = useState(initialValue);
  return (
    <div>
      <span>Count: {count}</span>
      <button onClick={() => setCount(count + 1)}>+</button>
    </div>
  );
}

test('Counter component', (assert) => {
  render(<Counter initialValue={5} />);
  
  assert.equal(screen.getByText('Count: 5').textContent, 'Count: 5');
  
  fireEvent.click(screen.getByText('+'));
  assert.equal(screen.getByText('Count: 6').textContent, 'Count: 6');
  
  cleanup();
});

Table of Contents

• Installation & Setup
• ESM Support
• TSX/JSX Support
• CLI
• Assertion 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.