Jest Basics

How Jest Discovers and Runs Tests

By default, Jest looks for any file ending in .test.js, .spec.js, or any file inside a folder named __tests__. When you run the jest command, it scans your project for matching files, loads each one in an isolated environment, and executes every test() block it finds.

Jest injects global functions like test, describe, expect, beforeEach, and afterEach automatically, so you do not need to import them manually in plain JavaScript projects (though importing them explicitly from @jest/globals is also supported and recommended for ESM/TypeScript clarity).

// math.js
function add(a, b) {
  return a + b;
}
module.exports = { add };

// math.test.js
const { add } = require('./math');

test('add(2, 3) returns 5', () => {
  expect(add(2, 3)).toBe(5);
});

A typical Jest setup: the source file exports a function, and the matching test file imports it and asserts on its behavior.

Default Project Layout

my-project/
  src/
    math.js
    math.test.js
  package.json
  jest.config.js

• Test files usually sit next to the code they test, or inside __tests__ folders.
• package.json typically has a "test": "jest" script so npm test runs the suite.
• jest.config.js is optional; Jest works with sensible defaults if it's absent.
• Jest automatically provides an isolated test environment per file, so tests don't leak state.

Jest Basics Cheat Sheet

The essential vocabulary you need before writing your first test file.

test() and Its Alias it()

Jest provides test() as the primary function for defining a test case, and it() as an identical alias. Both take a description string and a callback function containing the test logic. Teams often use test() for standalone tests and it() inside describe() blocks because "it should do X" reads naturally.

test('formats a currency value', () => {
  expect(formatCurrency(9.5)).toBe('$9.50');
});

it('formats a currency value', () => {
  expect(formatCurrency(9.5)).toBe('$9.50');
});

Both blocks behave identically; it is purely a naming convenience.

Running Jest from the Command Line

Once Jest is installed, you can run your entire suite with npx jest, run a single file with npx jest math.test.js, or filter tests by name with npx jest -t "add". Most projects wire this into npm test for convenience.

• npx jest — run every test file Jest can find.
• npx jest path/to/file.test.js — run a single file.
• npx jest -t "keyword" — run only tests whose name matches.
• npx jest --watch — re-run relevant tests automatically on save.

Common Mistakes

• Naming test files without .test. or .spec. and wondering why Jest never finds them.
• Forgetting to export functions from source files, so tests cannot import them.
• Writing one giant test file instead of one test file per source module.
• Not adding a "test": "jest" script, forcing everyone to remember the raw CLI command.

Key Takeaways

• Jest automatically discovers .test.js/.spec.js files or anything inside __tests__.
• test() and it() are identical; pick one convention and stay consistent.
• expect() combined with a matcher is how every assertion is written.
• The Jest CLI supports running all tests, a single file, or a filtered subset by name.