fauji

A lightweight testing framework for JavaScript. (Note: Still under development)

Usage Guide

Writing Tests

You do not need to import describe, test, expect, or hooks in each test file—they are available as globals, just like in Jest!

Create a test file (e.g., example.test.js):

describe('Math', () => {
  beforeAll(() => {
    // setup code
  });

  beforeEach(() => {
    // per-test setup
  });

  test('adds numbers', () => {
    expect(1 + 2).toBe(3);
  });

  test('object equality', () => {
    expect({ a: 1, b: 2 }).toEqual({ a: 1, b: 2 });
  });

  afterEach(() => {
    // per-test teardown
  });

  afterAll(() => {
    // teardown code
  });
});

Running Tests

Use the CLI to run your tests:

npx fauji --dir ./tests --pattern test.js --name math --watch

• --dir or -d: Test directory (default: current directory)
• --pattern or -p: Test file pattern (default: test.js)
• --name or -n: Filter test files by name
• --watch or -w: Watch mode (reruns tests on file changes)

Matchers

A matcher is a method that lets you test values. The following matchers are available:

expect(5).toBe(5);
expect([1, 2, 3]).toContain(2);
expect({ foo: 'bar' }).toHaveProperty('foo', 'bar');
expect(() => { throw new Error('fail'); }).toThrow();

Custom Matchers

You can add your own matchers:

addMatchers({
  toBeDivisibleBy(received, expected) {
    return received % expected === 0;
  }
});

expect(10).toBeDivisibleBy(2);

Fake Timers

Fauji provides a Jest-like fake timers API for controlling time-based code in your tests. This is useful for testing code that uses setTimeout, setInterval, or Date.

describe('timer tests', () => {
  beforeEach(() => useFakeTimers());
  afterEach(() => useRealTimers());

  test('setTimeout call count', () => {
    setTimeout(() => {}, 100);
    setTimeout(() => {}, 200);
    expect(getTimerCallCount('setTimeout')).toBe(2);
    expect(getTimerCalls('setTimeout')[0][1]).toBe(100);
  });
});

Mocking and Spying

const { spy, stub, mock, fn } = require('fauji');

test('spy on function', () => {
  const add = (a, b) => a + b;
  const addSpy = spy(add);
  addSpy(1, 2);
  expect(addSpy.calls.length).toBe(1);
  expect(addSpy.calls[0]).toEqual([1, 2]);
});

test('stub method', () => {
  const obj = { foo: () => 1 };
  const fooStub = stub(obj, 'foo', () => 42);
  expect(obj.foo()).toBe(42);
  fooStub.restore();
});