jest-testing

Files (1)

• SKILL.md

SKILL.md (first lines)

## When to Use

- Writing or refactoring unit and integration tests with Jest.
- Setting up mocking strategies for modules, functions, or APIs.
- Testing async code (Promises, async/await, timers).
- Testing React components alongside `@testing-library/react`.
- Configuring Jest for TypeScript, coverage, or CI environments.
- Debugging flaky or slow tests.

## Critical Patterns

- **Arrange-Act-Assert:** Every test follows three clear phases — set up state, perform the action,
  verify the outcome. No mixing.
- **Test Behavior, Not Implementation:** Assert on observable outcomes (return values, DOM changes,
  thrown errors), not internal function calls.
- **Isolate with Mocking:** Mock external dependencies (APIs, databases, file system) but NOT the
  unit under test. Over-mocking hides real bugs.
- **One Assertion Focus Per Test:** Each `it` block should test one logical behavior. Multiple
  assertions are fine if they verify the same behavior.
- **Deterministic Tests:** No reliance on real time, network, or random values. Use fake timers,
  mocked fetch, and seeded data.
- **Clean Up After Yourself:** Reset mocks in `afterEach`. Avoid shared mutable state between tests.

## Code Examples

### Basic Test Structure

```typescript
describe("UserService", () => {
  let service: UserService;

  beforeEach(() => {
    service = new UserService();
  });

  afterEach(() => {
    jest.restoreAllMocks();
  });

  describe("findById", () => {
    it("returns user when found", async () => {
      // Arrange
      const mockUser = { id: "1", name: "Alice" };
      jest.spyOn(db, "query").mockResolvedValue(mockUser);

      // Act
      const result = await service.findById("1");

      // Assert
      expect(result).toEqual(mockUser);
    });

    it("throws NotFoundError when user does not exist", async () => {
      jest.spyOn(db, "query").mockResolvedValue(null);

      await expect(service.findById("999")).rejects.toThrow(NotFoundError);
    });
  });
});
```

### Common Matchers

```typescript
// Equality
expect(value).toBe(primitive);           // strict equality (===)
expect(value).toEqual(object);           // deep equality
expect(value).toStrictEqual(object);     // deep equality + type checking

// Truthiness
expect(value).toBeTruthy();
expect(value).toBeFalsy();
expect(value).toBeNull();
expect(value).toBeUndefined();
expect(value).toBeDefined();

// Numbers
expect(value).toBeGreaterThan(3);
expect(value).toBeCloseTo(0.3, 5);       // floating point

// Strings
expect(value).toMatch(/regex/);
expect(value).toContain("substring");

// Arrays / Iterables
expect(array).toContain(item);
expect(array).toHaveLength(3);
expect(array).toEqual(expect.arrayContaining([1, 2]));

// Objects
expect(obj).toHaveProperty("key", "value");
expect(obj).toMatchObject({ name: "Alice" }); // partial match

// Exceptions
expect(() => fn()).toThrow(ErrorType);
expect(() => fn()).toThrow("message");
```

### Mocking Strategies

```typescript
// 1. jest.fn() — create a standalone mock function
const mockCallback = jest.fn();
mockCallback.mockReturnValue(42);
mockCallback.mockResolvedValue({ data: "ok" }); // async

expect(mockCallback).toHaveBeenCalledTimes(1);
expect(mockCallback).toHaveBeenCalledWith("arg1", "arg2");

// 2. jest.spyOn() — spy on existing methods (preserves original unless mocked)
const spy = jest.spyOn(Math, "random").mockReturnValue(0.5);
// ... test code ...
spy.mockRestore(); // restore original

// 3. jest.mock() — mock entire modules
jest.mock("../services/emailService", () => ({
  sendEmail: jest.fn().mockResolvedValue({ sent: true }),
}));

From dallay/agents-skills, MIT.

More from dallay/agents-skills