Jest Testing Best Practices

Quick Start

import { run } from "../src/api";

describe("interpreter", () => {
  it("evaluates arithmetic expressions", () => {
    expect(run("2 + 3")).toBe(5);
  });

  it("handles errors gracefully", () => {
    expect(() => run("undefined_var")).toThrow(/undefined/i);
  });
});

Core Principles

• Arrange-Act-Assert: Structure tests clearly
• One assertion focus: Test one behavior per test
• Descriptive names: Use "should" or behavior-based naming
• Isolation: Tests should not depend on each other

Testing Patterns

Interpreter Tests

describe("builtins", () => {
  describe("map", () => {
    it("transforms each element", () => {
      const code = `[1, 2, 3] /> map((x) -> x * 2)`;
      expect(run(code)).toEqual([2, 4, 6]);
    });

    it("passes index as second argument", () => {
      const code = `["a", "b"] /> map((x, i) -> i)`;
      expect(run(code)).toEqual([0, 1]);
    });
  });
});

Parser Tests

describe("parser", () => {
  it("parses pipe expressions", () => {
    const ast = parse("x /> fn");
    expect(ast.body[0]).toMatchObject({
      type: "ExprStmt",
      expression: {
        type: "PipeExpr",
        left: { type: "Identifier", name: "x" },
        right: { type: "Identifier", name: "fn" }
      }
    });
  });
});

Async Tests

it("resolves async operations", async () => {
  const result = await run(`
    let fetch = () -> delay(10) /> then(() -> "done") #async
    await fetch()
  `);
  expect(result).toBe("done");
});

Snapshot Tests

it("formats code consistently", () => {
  const formatted = format("let x=1+2");
  expect(formatted).toMatchSnapshot();
});

Configuration

// jest.config.js
module.exports = {
  preset: "ts-jest",
  testEnvironment: "node",
  testMatch: ["**/__tests__/**/*.test.ts"],
  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.d.ts"],
};

Reference Files

• references/mocking.md - Mocking strategies
• references/async-testing.md - Async test patterns