Jest

Unit and component testing. Adapts its configuration to the platform you selected.

adds it to an existing project · no account needed

Currentas published in v1.5.1

The rule

This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.

Queries

Find elements the way a user does: getByText, getByLabelText, getByRole.
getByTestId is a last resort. Reaching for it first produces tests that pass while the screen is unusable by anyone relying on a screen reader.
Anything async uses findBy*, which retries. getBy* does not, and a fixed setTimeout to compensate is a flake waiting to happen.

Mocking

Mock native modules and third-party SDKs in jest.setup.js.
Where this project wraps an SDK in a service, mock the service.
Never mock your own modules to make a test pass — that couples the test to the current file layout and it will break on a no-op refactor.
Reset mocks in beforeEach. A test that only passes in isolation is broken.

Structure

it('surfaces a retryable error when the token has expired', async () => {
  // arrange — the least setup that makes the scenario true
  // act     — one interaction
  // expect  — what a caller or user observes
});

One reason to fail per test, and a name that says which.

Do not

Do not commit it.only or it.skip.
Do not add snapshots nobody reads.
Do not test library behaviour — test this project's use of it.
Do not chase a coverage percentage; cover the paths that can be wrong.

6 formats, one per tool

Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.

.cursor/rules/jest.mdchand-written

---
description: Jest and React Native Testing Library conventions
globs: ["**/*.test.ts", "**/*.test.tsx", "**/__tests__/**", "jest.setup.js"]
alwaysApply: false
---

# Jest

## Queries

- Find elements the way a user does: `getByText`, `getByLabelText`, `getByRole`.
- `getByTestId` is a last resort. Reaching for it first produces tests that pass
  while the screen is unusable by anyone relying on a screen reader.
- Anything async uses `findBy*`, which retries. `getBy*` does not, and a fixed
  `setTimeout` to compensate is a flake waiting to happen.

## Mocking

- Mock native modules and third-party SDKs in `jest.setup.js`.
- Where this project wraps an SDK in a service, mock the **service**.
- Never mock your own modules to make a test pass — that couples the test to
  the current file layout and it will break on a no-op refactor.
- Reset mocks in `beforeEach`. A test that only passes in isolation is broken.

## Structure

```ts
it('surfaces a retryable error when the token has expired', async () => {
  // arrange — the least setup that makes the scenario true
  // act     — one interaction
  // expect  — what a caller or user observes
});
```

One reason to fail per test, and a name that says which.

## Do not

- Do not commit `it.only` or `it.skip`.
- Do not add snapshots nobody reads.
- Do not test library behaviour — test this project's use of it.
- Do not chase a coverage percentage; cover the paths that can be wrong.

Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.

What else this module writes

The rule is one file of several. Selecting Jest contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.

Dependencies

Depends on the rest of the stack — this module installs different packages depending on what else you select, so there is no single list to show.

Folders

src/test/factories/

Advisory history

Every time this rule turned out to be wrong, and what we did about it.

No corrections yet

This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.

Pro tells you the day a correction lands that affects a repo you actually have.

See what Pro adds →

Put this rule in a real project

The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.