/\
       /  \      E2E Tests (10%)
      /----\     Slow, expensive, fewer
     /      \
    /--------\   Integration Tests (20%)
   /          \  Test component interactions
  /------------\
 /              \ Unit Tests (70%)
/__________________\ Fast, isolated, many

npm install --save-dev jest @types/jest supertest

// package.json
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",       // Re-runs tests when files change -- invaluable during development
    "test:coverage": "jest --coverage"   // Generates a coverage report showing which lines are untested
  },
  "jest": {
    "testEnvironment": "node",           // Use Node.js globals (not browser/jsdom)
    "coverageDirectory": "coverage",
    "collectCoverageFrom": [
      "src/**/*.js",
      "!src/**/*.test.js"               // Exclude test files from coverage calculation
    ],
    "coverageThreshold": {
      "global": {
        "branches": 80,                  // If coverage drops below 80%, the test run fails.
        "functions": 80,                 // This acts as a ratchet -- coverage can only go up,
        "lines": 80,                     // never down, preventing gradual erosion of test quality.
        "statements": 80
      }
    }
  }
}

// math.js
const add = (a, b) => a + b;
const subtract = (a, b) => a - b;
const multiply = (a, b) => a * b;
const divide = (a, b) => {
  if (b === 0) throw new Error('Cannot divide by zero');
  return a / b;
};

module.exports = { add, subtract, multiply, divide };

// math.test.js
const { add, subtract, multiply, divide } = require('./math');

// describe() groups related tests together -- think of it as a chapter heading.
// Nesting describe blocks creates a hierarchy: module > function > scenario.
describe('Math functions', () => {
  describe('add', () => {
    // test() (aliased as it()) defines a single test case.
    // The string should read as a sentence: "it should add two positive numbers."
    test('should add two positive numbers', () => {
      // expect().toBe() is the core assertion: "I expect this value to be that value."
      expect(add(2, 3)).toBe(5);
    });

    test('should add negative numbers', () => {
      expect(add(-2, -3)).toBe(-5);
    });

    // Test edge cases -- zero is a common source of bugs (off-by-one, falsy checks)
    test('should add zero', () => {
      expect(add(5, 0)).toBe(5);
    });
  });

  describe('divide', () => {
    test('should divide two numbers', () => {
      expect(divide(10, 2)).toBe(5);
    });

    // Testing error cases is just as important as testing success cases.
    // Wrap the throwing call in a function so Jest can catch and inspect the error.
    test('should throw error when dividing by zero', () => {
      expect(() => divide(10, 0)).toThrow('Cannot divide by zero');
    });
  });
});

describe('Jest Matchers', () => {
  // Equality -- toBe() uses Object.is (strict reference equality).
  // For primitives this works like ===. For objects, it checks if they
  // are the SAME object in memory, not just structurally identical.
  test('exact equality', () => {
    expect(2 + 2).toBe(4);
  });

  // toEqual() does a DEEP comparison of structure and values.
  // Use it for objects and arrays -- toBe() would fail here because
  // the two objects are different references even though they look identical.
  test('object equality', () => {
    expect({ name: 'John' }).toEqual({ name: 'John' });
  });

  // Truthiness
  test('truthy/falsy', () => {
    expect(null).toBeNull();
    expect(undefined).toBeUndefined();
    expect('value').toBeDefined();
    expect(true).toBeTruthy();
    expect(false).toBeFalsy();
  });

  // Numbers
  test('number comparisons', () => {
    expect(10).toBeGreaterThan(5);
    expect(10).toBeGreaterThanOrEqual(10);
    expect(5).toBeLessThan(10);
    // toBeCloseTo() is essential for floating-point math.
    // 0.1 + 0.2 === 0.30000000000000004 in JavaScript (IEEE 754 quirk),
    // so toBe(0.3) would FAIL. toBeCloseTo accounts for this rounding.
    expect(0.1 + 0.2).toBeCloseTo(0.3);
  });

  // Strings
  test('string matching', () => {
    expect('Hello World').toMatch(/World/);
    expect('Hello World').toContain('World');
  });

  // Arrays
  test('array matching', () => {
    expect([1, 2, 3]).toContain(2);
    expect(['a', 'b', 'c']).toHaveLength(3);
    expect([{ id: 1 }, { id: 2 }]).toContainEqual({ id: 1 });
  });

  // Objects
  test('object matching', () => {
    expect({ a: 1, b: 2 }).toHaveProperty('a');
    expect({ a: 1, b: 2 }).toHaveProperty('a', 1);
    expect({ a: 1, b: 2 }).toMatchObject({ a: 1 });
  });

  // Exceptions
  test('exception matching', () => {
    expect(() => { throw new Error('fail'); }).toThrow();
    expect(() => { throw new Error('fail'); }).toThrow('fail');
    expect(() => { throw new Error('fail'); }).toThrow(Error);
  });
});

// userService.js
const fetchUser = async (id) => {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) throw new Error('User not found');
  return response.json();
};

const fetchUserCallback = (id, callback) => {
  setTimeout(() => {
    if (id === 0) callback(new Error('User not found'), null);
    else callback(null, { id, name: 'John' });
  }, 100);
};

// userService.test.js
describe('Async Testing', () => {
  // Pattern 1: async/await -- the cleanest and most common approach.
  // Just mark the test function as async and use await normally.
  test('async function success', async () => {
    const user = await fetchUser(1);
    expect(user).toHaveProperty('name');
  });

  // Testing that an async function REJECTS (throws).
  // Note: you must await the expect() call -- forgetting the await
  // is a classic bug that makes the test always pass.
  test('async function error', async () => {
    await expect(fetchUser(999)).rejects.toThrow('User not found');
  });

  // Pattern 2: Promises -- return the promise chain from the test.
  // Jest waits for the returned promise to settle before finishing.
  test('promise resolves', () => {
    return expect(fetchUser(1)).resolves.toHaveProperty('name');
  });

  // Pattern 3: Callbacks -- use the 'done' parameter.
  // Jest will wait until done() is called. If done() is never called
  // (e.g., the callback is not invoked), the test times out and fails.
  test('callback success', (done) => {
    fetchUserCallback(1, (err, user) => {
      expect(err).toBeNull();
      expect(user.name).toBe('John');
      done(); // Signal to Jest that the async work is complete
    });
  });
});

// jest.fn() creates a "spy" function that records every call
const mockFn = jest.fn();

mockFn('hello');
mockFn('world');

// Verify the mock was called correctly
expect(mockFn).toHaveBeenCalled();
expect(mockFn).toHaveBeenCalledTimes(2);
expect(mockFn).toHaveBeenCalledWith('hello');
expect(mockFn).toHaveBeenLastCalledWith('world');

// Control what the mock returns
const mockAdd = jest.fn()
  .mockReturnValue(10)          // Default return for all calls
  .mockReturnValueOnce(5);      // Override for just the first call

expect(mockAdd()).toBe(5);  // First call returns the "once" value
expect(mockAdd()).toBe(10); // Subsequent calls use the default

// Provide a full implementation for the mock
const mockMultiply = jest.fn((a, b) => a * b);
expect(mockMultiply(3, 4)).toBe(12);

// emailService.js
const sendEmail = async (to, subject, body) => {
  // Real implementation sends email via SendGrid, SES, etc.
};

module.exports = { sendEmail };

// user.test.js

// jest.mock() replaces EVERY export of the module with a jest.fn() stub.
// This must be called at the top level, before any imports that use the module.
// Jest hoists it above all imports automatically.
jest.mock('./emailService');
const { sendEmail } = require('./emailService');
const { registerUser } = require('./userService');

describe('User registration', () => {
  beforeEach(() => {
    // Clear call history between tests -- without this, assertions like
    // toHaveBeenCalledTimes(1) would accumulate across tests
    sendEmail.mockClear();
    // Tell the mock to resolve with a success response
    sendEmail.mockResolvedValue({ success: true });
  });

  test('should send welcome email on registration', async () => {
    await registerUser({ email: 'test@example.com', name: 'Test' });
    
    // Verify the email service was called exactly once
    expect(sendEmail).toHaveBeenCalledTimes(1);
    // Verify it was called with the right arguments.
    // expect.stringContaining() and expect.any() are "asymmetric matchers" --
    // they let you assert on the shape of arguments without exact matching.
    expect(sendEmail).toHaveBeenCalledWith(
      'test@example.com',
      expect.stringContaining('Welcome'),
      expect.any(String)
    );
  });
});

// Automatically mock all module functions
jest.mock('axios');
const axios = require('axios');

test('fetch data', async () => {
  axios.get.mockResolvedValue({ data: { id: 1, name: 'John' } });
  
  const user = await getUser(1);
  expect(user.name).toBe('John');
  expect(axios.get).toHaveBeenCalledWith('/api/users/1');
});

// Manual mock implementation
jest.mock('axios', () => ({
  get: jest.fn(() => Promise.resolve({ data: {} })),
  post: jest.fn(() => Promise.resolve({ data: {} }))
}));

npm install --save-dev supertest

// app.js (export app without listening -- this is the critical pattern)
const express = require('express');
const app = express();

app.use(express.json());

app.get('/api/users', (req, res) => {
  res.json([{ id: 1, name: 'John' }]);
});

app.get('/api/users/:id', (req, res) => {
  const id = parseInt(req.params.id);
  if (id === 999) return res.status(404).json({ error: 'Not found' });
  res.json({ id, name: 'John' });
});

app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  if (!name || !email) {
    return res.status(400).json({ error: 'Name and email required' });
  }
  res.status(201).json({ id: 1, name, email });
});

module.exports = app;

// app.test.js
const request = require('supertest');
const app = require('./app');

describe('User API', () => {
  describe('GET /api/users', () => {
    test('should return all users', async () => {
      const response = await request(app)
        .get('/api/users')
        .expect('Content-Type', /json/)
        .expect(200);

      expect(response.body).toBeInstanceOf(Array);
      expect(response.body.length).toBeGreaterThan(0);
    });
  });

  describe('GET /api/users/:id', () => {
    test('should return user by id', async () => {
      const response = await request(app)
        .get('/api/users/1')
        .expect(200);

      expect(response.body).toHaveProperty('id', 1);
      expect(response.body).toHaveProperty('name');
    });

    test('should return 404 for non-existent user', async () => {
      await request(app)
        .get('/api/users/999')
        .expect(404);
    });
  });

  describe('POST /api/users', () => {
    test('should create new user', async () => {
      const newUser = { name: 'Jane', email: 'jane@example.com' };
      
      const response = await request(app)
        .post('/api/users')
        .send(newUser)
        .expect(201);

      expect(response.body).toMatchObject(newUser);
      expect(response.body).toHaveProperty('id');
    });

    test('should return 400 for invalid data', async () => {
      await request(app)
        .post('/api/users')
        .send({ name: 'Jane' }) // Missing email
        .expect(400);
    });
  });
});

// Setup test database
const mongoose = require('mongoose');
const { MongoMemoryServer } = require('mongodb-memory-server');

let mongoServer;

beforeAll(async () => {
  // Spin up an isolated MongoDB instance -- takes 1-2 seconds on first run
  // (it caches the binary after the first download)
  mongoServer = await MongoMemoryServer.create();
  await mongoose.connect(mongoServer.getUri());
});

afterAll(async () => {
  // Tear down cleanly -- always disconnect before stopping the server
  await mongoose.disconnect();
  await mongoServer.stop();
});

beforeEach(async () => {
  // Clear all collections before each test to ensure test isolation.
  // Without this, data from one test leaks into the next, causing
  // flaky failures that are extremely hard to debug.
  const collections = mongoose.connection.collections;
  for (const key in collections) {
    await collections[key].deleteMany({});
  }
});

describe('User Model', () => {
  test('should create user', async () => {
    const user = await User.create({
      name: 'John',
      email: 'john@example.com',
      password: 'password123'
    });

    expect(user._id).toBeDefined();
    expect(user.name).toBe('John');
    expect(user.password).not.toBe('password123'); // Should be hashed
  });

  test('should not create user without email', async () => {
    await expect(
      User.create({ name: 'John', password: 'password123' })
    ).rejects.toThrow();
  });
});

# Generate coverage report
npm test -- --coverage

# Output shows four metrics per file:
# % Stmts   -- percentage of statements executed
# % Branch  -- percentage of if/else branches taken (the hardest to get high)
# % Funcs   -- percentage of functions called at least once
# % Lines   -- percentage of executable lines hit
# Uncovered -- exact line numbers with zero coverage (your to-do list)
# ----------|---------|----------|---------|---------|-------------------
# File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
# ----------|---------|----------|---------|---------|-------------------
# All files |   85.71 |    83.33 |     100 |   85.71 |
#  math.js  |     100 |      100 |     100 |     100 |
#  user.js  |   71.43 |    66.67 |     100 |   71.43 | 15-17
# ----------|---------|----------|---------|---------|-------------------

src/
├── services/
│   ├── userService.js
│   └── userService.test.js    # Co-located: test lives next to source
├── models/
│   └── User.js
└── __tests__/                  # Separate: organized by test type
    ├── integration/
    │   └── userApi.test.js     # Tests that hit real endpoints
    └── unit/
        └── userModel.test.js   # Tests that run in isolation