Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 30 ยท Getting Started

describe, it and Test Organization

Group Jest tests with describe, choose between it and test, use skip, only and todo, name tests so failures read clearly, and structure each test as arrange-act-assert.

A single test is easy to read. Two hundred tests in one file are not, unless they are organized. Jest gives you describe to group related tests, it and test to define them, and modifiers such as skip, only and todo to control which ones run. This lesson shows how to use them and, just as important, how to name and shape tests so a failure tells you what broke without opening the code.

The previous lesson, Your First Jest Test, introduced test and expect.

Real versus stand-in. The Jest code in plain blocks is real and read-only. The runnable TryIt builds a miniature describe/it runner with nesting, skip, only and todo, to show the mechanism. Jest's real implementation is far more capable, but the behavior shown here matches how these features are used.

describe: grouping tests

describe(name, fn) creates a block. Tests inside it belong to that group, and Jest prints the group name in front of each test name.

JavaScript
const { formatPrice } = require("./price");

describe("formatPrice", () => {
  test("adds a currency symbol", () => {
    expect(formatPrice(5)).toBe("$5.00");
  });

  test("keeps two decimals", () => {
    expect(formatPrice(5.5)).toBe("$5.50");
  });

  test("rounds to the nearest cent", () => {
    expect(formatPrice(2.456)).toBe("$2.46");
  });
});

When a test fails, the report shows formatPrice โ€บ rounds to the nearest cent. The group name plus the test name should read like a sentence: "formatPrice rounds to the nearest cent". If it does not read like a sentence, rename something.

The function you pass to describe runs immediately, while Jest is collecting tests, and it must be synchronous. Do not return a promise from it and do not do real work there (like reading a database). Put real work in the tests or in hooks, which we cover in Setup and Teardown Hooks.

Nesting

describe blocks can nest, which is useful when one unit has several behaviors that each have several cases.

JavaScript
describe("Cart", () => {
  describe("addItem", () => {
    test("adds a new line", () => { /* ... */ });
    test("increases quantity for a repeated item", () => { /* ... */ });
  });

  describe("total", () => {
    test("is zero for an empty cart", () => { /* ... */ });
    test("sums price times quantity", () => { /* ... */ });
  });
});

A failure there is reported as Cart โ€บ total โ€บ is zero for an empty cart. Do not nest more than two or three levels. Deep trees are hard to read and hide the setup that each test relies on.

How a report is named

describe The unit or feature, such as Cart.
Nested describe A method or situation, such as total.
test or it One specific behavior, in plain words.

Read together, the names should form a sentence.

1 / 2

it versus test

it is an alias of test. They behave identically. Choose one style per project and keep it.

  • describe("Cart", () => { it("starts empty", ...) }) reads naturally as "Cart, it starts empty".
  • test("starts empty", ...) reads well for top-level tests that are not in a describe.

Because they are the same function, it.skip, it.only and it.todo exist alongside test.skip, test.only and test.todo.

skip, only and todo

JavaScript
test.skip("charges tax for EU customers", () => {
  // temporarily disabled; reported as skipped
});

test.only("rounds to two decimals", () => {
  // while this exists, other tests in the same FILE are skipped
});

test.todo("supports gift cards");
  • skip keeps the test in the report as "skipped" so it is not forgotten. The aliases xit, xtest and xdescribe do the same. Use it for a short while with a comment saying why. A suite full of skipped tests is a suite nobody trusts.
  • only is for focusing while you work. If any test in a file uses only, the other tests in that file are skipped (tests in other files still run). Aliases: fit, ftest, fdescribe. Never commit one: it silently turns off the rest of the file and CI will still show green.
  • todo takes only a name, no function. It appears in the report as a to-do item and is a good way to list the cases you plan to cover.

describe.skip and describe.only apply the same idea to a whole group. For finding one test from the command line without editing code, use the -t flag from The Jest CLI and Watch Mode.

A runner that groups and controls tests

Run this stand-in, then try adding .only to a test and see what happens to the others. The report prints each test with its describe path, the way Jest does.

JS describe, skip, only and todo

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Now change it("is zero for an empty cart" to it.only(...). Every other test turns into "skipped", including the one that fails. This is exactly why a forgotten .only is dangerous: the suite goes green because most of it did not run.

Naming tests well

Test names are documentation that is checked on every run. Good names describe the behavior and the condition, not the implementation.

Weak Better
test("works") test("returns an empty array when the input is empty")
test("test total") test("total sums price times quantity")
test("handles error") test("throws a RangeError when the quantity is negative")
test("calls helper") test("sends a welcome email to a new user")

A good rule: if a test fails in CI at 3 a.m., the name alone should tell the person on call what business rule broke.

Arrange, act, assert

Keep each test body in three visible parts. Blank lines between them help.

JavaScript
test("applies a 10% coupon to the subtotal", () => {
  // arrange
  const cart = createCart();
  cart.add({ name: "Book", price: 20, qty: 2 });

  // act
  cart.applyCoupon("SAVE10");

  // assert
  expect(cart.total()).toBe(36);
});

Also aim for one reason to fail per test. A test with ten unrelated assertions tells you only that "something" broke. Several expect calls are fine when they describe one behavior (for example the fields of one returned object). When they describe different behaviors, split them into separate tests.

Where to put test files

Two layouts are common, and Jest supports both:

  • Next to the code: src/cart.js and src/cart.test.js. Easy to find and move together.
  • In a __tests__ folder: src/__tests__/cart.test.js. Keeps source folders tidy.

Pick one per project. Mixing them makes tests hard to find.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How does Jest label a failing test that is nested as describe('Cart') > describe('total') > test('is zero for an empty cart')?

    Jest joins the describe names and the test name, separated by a chevron, so failures show the full path.
  2. 2. What is the difference between it and test?

    They are the same function. Pick one style and use it consistently.
  3. 3. You leave test.only in a file and push it. What happens to the other tests in that file?

    When a file contains an only test, Jest skips the others in that file. This hides coverage loss, so never commit .only.
  4. 4. What is test.todo for?

    test.todo takes only a name and shows up in the report as a reminder; it has no body to run.
  5. 5. Which is the best test name?

    A good name states the behavior and the condition, so a failing name explains itself.

Summary

  • describe groups tests; names combine into a path such as Cart โ€บ total โ€บ is zero.
  • it and test are identical; pick one style.
  • skip disables a test visibly, only focuses within a file (never commit it), todo lists tests to write.
  • Describe bodies run immediately and must be synchronous.
  • Name tests by behavior and condition, keep them independent, and use arrange, act, assert with one reason to fail.

Next: The Jest CLI and Watch Mode.