Learn Jest - Core Concepts & Architecture

#Introduction

In episode 1 you learned why Jest is the chosen framework. Now it's time to understand how it works from the inside. Episode 2 dissects Jest's architecture into three main parts: the test runner, the assertion library, and the mocking engine. Understanding this architecture makes you not just proficient at using the API, but also aware of why an error appears and how Jest thinks.

We'll also study the test lifecycle — setup, execution, and teardown — along with the rules for discovering test files and the structure of basic configuration. This is the technical foundation used in almost every remaining episode.

#The Three Main Parts of Jest's Architecture

#Test Runner

The test runner is the engine that finds test files, runs them, and collects the results. Jest uses a worker architecture: each test file runs in a separate process so environments are isolated across files — one failing file doesn't bring down others, and state doesn't leak between tests.

Because each test file runs in an isolated environment, Jest can apply mechanisms such as a per-file global test timeout and automatic cleanup. As a consequence, global variables defined in one test file aren't visible in another test file. This is one of the reasons Jest is so stable on large codebases.

#Assertion Library

The assertion library is the part that provides the expect function and a set of matchers such as toBe, toEqual, and toContain. When an assertion fails, Jest composes a clear error message — comparing the actual and expected values with an easy-to-read diff.

You can extend this assertion library via expect.extend() to create custom matchers, which we'll cover in episode 16. For now, remember that every assertion always takes the form expect(actualValue).matcher(expectedValue).

#Mocking Engine

The mocking engine lets you replace functions, modules, and timers. With jest.fn() you create fake functions whose calls can be tracked, and with jest.mock() you replace an entire module with a fake version. These three parts work together: the runner isolates files, the assertion evaluates results, and mocking creates a controlled environment.

The three parts working in one test

test("assertion checks the mocking result", () => {
  const calc = jest.fn(() => 42);
  const result = calc();
  expect(calc).toHaveBeenCalledTimes(1);
  expect(result).toBe(42);
});

jest.fn(() => 42) creates a mock function that returns 42, then expect(calc).toHaveBeenCalledTimes(1) verifies the function was actually called once, and expect(result).toBe(42) confirms the return value is correct.

#Test Lifecycle

#Setup, Execution, and Teardown

Each test file goes through three phases:

• Setup: preparation before tests run, via beforeAll and beforeEach.
• Execution: running the body of test or it.
• Teardown: cleanup after tests, via afterAll and afterEach.

Setup and teardown functions play a big role in episode 4. For now, remember the order: beforeAll and afterAll run once per file, while beforeEach and afterEach run before and after every individual test. This order determines how you structure heavy initialization and thorough cleanup.

#Per-File Isolated Environment

Because each file runs in its own environment, Jest can manage test lifetimes — the default timeout is 5 seconds per test. If a test takes longer than that, Jest marks it failed due to timeout rather than assertion. This is often the main cause of "tests suddenly failing" in large suites.

The default timeout can be changed per test with the third argument, or globally through the testTimeout configuration option. A good habit: raise the timeout explicitly only for tests that are genuinely heavy, rather than raising the default for all tests.

#Test File Discovery Rules

#Naming and Directory Conventions

Jest discovers test files automatically with three default patterns:

• Any file inside a __tests__ directory.
• Files whose name ends in .test.js, .spec.js, or variants like .test.tsx, .spec.ts.
• Files that have .test or .spec appended to their name.

These rules can be changed via the testMatch and testPathIgnorePatterns options in the configuration. The default conventions are sufficient for most projects, and applying the same pattern across the whole codebase makes test file discovery predictable.

npx jest --listTests

The command npx jest --listTests lists the files that will be run — a quick way to confirm your naming conventions are correct before the suite runs. If a test file doesn't appear in this list, its name doesn't match the default patterns.

#Basic Configuration and jest.config.js

#Two Ways to Store Configuration

Jest configuration can be written in a jest.config.js file, in a jest block in package.json, or using a TypeScript variant such as jest.config.ts. A separate file is easier to read and share, while a jest block in package.json suits small projects.

Basic jest.config.js

module.exports = {
  testEnvironment: "node",
  clearMocks: true,
  collectCoverage: false,
  coverageDirectory: "coverage",
  testMatch: ["**/__tests__/**/*.[jt]s?(x)", "**/?(*.)+(spec|test).[jt]s?(x)"],
};

The option testEnvironment: "node" determines the default environment — Node.js for most backend projects, and jsdom for projects that need a DOM like React. clearMocks ensures mocks are reset between tests so state doesn't leak.

#Frequently Used Options

Besides testEnvironment, there are several options you'll encounter often in the coming episodes:

• moduleNameMapper: maps path aliases or CSS modules.
• setupFilesAfterEnv: files run after the test framework is installed.
• testTimeout: changes the default per-test timeout.
• maxWorkers: controls the number of parallel workers.

Don't worry about memorizing all of them now. What matters is understanding that Jest configuration is just a JavaScript object — easy to read, easy to test, and easy to control from the command line.

#Wrap Up

Episode 2 opened Jest's black box: a test runner that isolates each file in its own worker, an assertion library that produces easy-to-read errors, a mocking engine that creates a controlled environment, the setup-execution-teardown lifecycle, test file discovery rules, and the structure of basic configuration.

Key takeaways:

• Jest consists of three parts: the test runner, the assertion library, and the mocking engine.
• Each test file runs in an isolated environment with a default timeout of 5 seconds.
• beforeAll and afterAll run once; beforeEach and afterEach run per test.
• Jest finds files automatically via __tests__, .test, and .spec.
• Configuration can live in jest.config.js or a jest block in package.json.
• testEnvironment chooses between node and jsdom.

In the next episode, episode 3, we'll fully install and configure Jest in Node.js and TypeScript projects — adding Jest, writing test scripts, organizing folder structure, and reading CLI output correctly. Make sure you understand episode 2's configuration before continuing.