README — PeopleTester

🧪 PeopleTester

Simple, powerful, and beautiful test framework for Node.js

GitHub npm MIT License

✨ Features

• 50+ Matchers — toBe, toEqual, toThrow, toContain, and more
• Hooks — beforeEach and afterEach for clean test setup
• Async Support — Full support for Promises and async/await
• Skip Tests — Skip specific tests with .skip flag
• Beautiful Output — Colorful CLI reports with chalk
• JSON Reports — Export test results to JSON files
• Self-Testing — 100% test coverage with self-tests
• TypeScript — Full type definitions included

📦 Installation

npm install @thispeoplestudio/peopletester

🚀 Quick Start

import PeopleTester from '@thispeoplestudio/peopletester';

const tester = new PeopleTester();

tester.describe('Math Operations', 'Testing basic arithmetic', () => {
    tester.it('addition', '2 + 2 should equal 4', () => {
        tester.expect(2 + 2).toBe(4);
    });

    tester.it('multiplication', '3 * 3 should equal 9', () => {
        tester.expect(3 * 3).toBe(9);
    });
});

await tester.run();
await tester.saveToFile('test-report.json');

📊 Matchers Reference

Basic Matchers

Matcher

Description

toBe(expected)

Strict equality (===)

toEqual(expected)

Deep equality for objects/arrays

toStrictEqual(expected)

Deep equality with type checking

Numeric Matchers

Matcher

Description

toBeGreaterThan(expected)

actual > expected

toBeGreaterThanOrEqual(expected)

actual >= expected

toBeLessThan(expected)

actual < expected

toBeLessThanOrEqual(expected)

actual <= expected

toBeCloseTo(expected, precision?)

Floating point comparison

toBeFinite()

Check if number is finite

toBeInteger()

Check if number is integer

toBeNaN()

Check if value is NaN

toBePositive()

Check if number is positive

toBeNegative()

Check if number is negative

Logical Matchers

Matcher

Description

toBeTruthy()

Check if value is truthy

toBeFalsy()

Check if value is falsy

toBeDefined()

Check if value is not undefined

toBeUndefined()

Check if value is undefined

toBeNull()

Check if value is null

Object Matchers

Matcher

Description

toBeInstanceOf(expected)

Check if value is instance of class

toHaveProperty(property, value?)

Check if object has property

toMatchObject(expected)

Check if object matches partial structure

Array Matchers

Matcher

Description

toContain(expected)

Check if array contains value

toContainEqual(expected)

Check if array contains equal object

toHaveLength(expected)

Check array length

toBeEmpty()

Check if array/object/string is empty

String Matchers

Matcher

Description

toMatch(pattern)

Check if string matches regex or substring

toContainString(expected)

Check if string contains substring

toStartWith(expected)

Check if string starts with prefix

toEndWith(expected)

Check if string ends with suffix

Function Matchers

Matcher

Description

toThrow(expected?)

Check if function throws error

toThrowError(expected?)

Alias for toThrow

toHaveReturned()

Check if function returned

toHaveReturnedWith(expected)

Check if function returned specific value

Promise Matchers

Matcher

Description

toResolve()

Check if Promise resolves

toReject()

Check if Promise rejects

toRejectWith(expected)

Check if Promise rejects with specific error

Negation

Matcher

Description

.not

Inverts any matcher: expect(2).not.toBe(3)

📚 API Reference

describe(name, description, callback)

Groups tests together.

tester.describe('User Service', 'Tests for user service', () => {
    // tests here
});

it(name, description, callback)

Defines a test case.

tester.it('getUser', 'Should return user by ID', () => {
    tester.expect(getUser(1)).toEqual({ id: 1, name: 'John' });
});

beforeEach(callback)

Runs before each test in the current describe block.

tester.beforeEach(() => {
    database.clear();
});

afterEach(callback)

Runs after each test in the current describe block.

tester.afterEach(() => {
    cleanup();
});

expect(actual)

Creates a matcher object.

tester.expect(2 + 2).toBe(4);

run()

Executes all registered tests.

const results = await tester.run();

saveToFile(filename)

Saves test results as JSON file.

await tester.saveToFile('test-report.json');

📝 Usage Examples

Basic Tests

tester.describe('Basic Math', 'Tests for basic math operations', () => {
    tester.it('should add numbers correctly', '2 + 2 should equal 4', () => {
        tester.expect(2 + 2).toBe(4);
    });

    tester.it('should multiply numbers correctly', '3 * 3 should equal 9', () => {
        tester.expect(3 * 3).toBe(9);
    });
});

Object Tests

tester.describe('Objects', 'Testing object comparisons', () => {
    const user = { id: 1, name: 'John', age: 30 };

    tester.it('should match object structure', 'User should have correct properties', () => {
        tester.expect(user).toMatchObject({ name: 'John', age: 30 });
        tester.expect(user).toHaveProperty('id', 1);
    });

    tester.it('should deep equal', 'Users should be equal', () => {
        tester.expect({ id: 1, name: 'John' }).toEqual({ id: 1, name: 'John' });
    });
});

Async Tests

tester.describe('Async', 'Testing asynchronous code', () => {
    tester.it('should handle promises', 'Promise should resolve', async () => {
        const result = await fetchData();
        tester.expect(result).toBe('data');
    });

    tester.it('should handle errors', 'Promise should reject', async () => {
        await tester.expect(fetchError()).toRejectWith('Network error');
    });
});

Using Hooks

let counter = 0;

tester.describe('With Hooks', 'Testing beforeEach and afterEach', () => {
    tester.beforeEach(() => {
        counter = 0;
    });

    tester.afterEach(() => {
        tester.expect(counter).toBe(1);
    });

    tester.it('should increment counter', 'Counter should be 1', () => {
        tester.expect(counter).toBe(0);
        counter++;
        tester.expect(counter).toBe(1);
    });
});

📄 License

MIT — feel free to use, modify, and distribute.

Made with ❤️ by This People Studio