Jest Setup Files

setupFiles vs. setupFilesAfterEnv

setupFiles runs before the test framework itself is installed in the environment — it's meant for polyfills or environment variables that need to exist before Jest's globals (test, expect, etc.) are even available.

setupFilesAfterEnv (commonly referred to by its config key setupFilesAfterEnv) runs after the test framework is installed, so you can safely use expect, beforeEach, afterEach, and custom matcher extensions inside it. This is where most shared setup, like @testing-library/jest-dom matchers, gets registered.

// jest.config.js
module.exports = {
  setupFiles: ['<rootDir>/jest.env.js'],
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
};

// jest.setup.js
import '@testing-library/jest-dom';

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

jest.setup.js runs after Jest's globals exist, so afterEach() and matcher extensions work correctly here.

Registering Setup Files

// jest.config.js
module.exports = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
};

• Both options accept an array of file paths, run in order, before any test file.
• <rootDir> is a Jest token that resolves to your project's root directory.
• Use setupFiles for environment polyfills (like a TextEncoder shim).
• Use setupFilesAfterEnv for anything that touches Jest's expect/lifecycle globals.

Setup Files Cheat Sheet

When to use each Jest setup configuration option.

Registering Custom Matchers Globally

Libraries like @testing-library/jest-dom add extra matchers (.toBeVisible(), .toHaveTextContent()) by calling expect.extend() internally. Importing them once in a setupFilesAfterEnv file makes those matchers available in every test file, without repeating the import everywhere.

// jest.setup.js
import '@testing-library/jest-dom';

// any test file can now use extra matchers without importing them again
test('shows the welcome message', () => {
  render(<Welcome name="Ada" />);
  expect(screen.getByText('Welcome, Ada')).toBeVisible();
});

globalSetup and globalTeardown for Whole-Suite Resources

globalSetup and globalTeardown run exactly once for the entire test run (not once per file), making them the right place to start and stop a shared resource like a test database container used by every test file.

// jest.config.js
module.exports = {
  globalSetup: '<rootDir>/test/globalSetup.js',
  globalTeardown: '<rootDir>/test/globalTeardown.js',
};

Unlike setupFiles, these run in a separate context without access to expect or other Jest globals.

Common Mistakes

• Using setupFiles for code that calls expect.extend(), which needs the test framework to already be installed.
• Confusing globalSetup (once per run) with setupFilesAfterEnv (once per test file).
• Forgetting to add a matching globalTeardown and leaving a shared resource running after tests finish.
• Putting per-test resets (that belong in afterEach()) into a setup file that only runs once.

Key Takeaways

• setupFiles runs before Jest's test globals exist; use it for polyfills.
• setupFilesAfterEnv runs after Jest's globals exist; use it for custom matchers and shared hooks.
• globalSetup/globalTeardown run exactly once for the entire test run, ideal for shared infrastructure.
• Setup files keep repetitive configuration out of every individual test file.