Learn Jest - Operational Readiness & Runbooks

#Introduction

A test suite is a system that also needs to be operated: it can get sick, become flaky, and suffer regressions just like a production application. Episode 19 covers operational readiness & runbooks — ready-to-use procedure documents for when the suite fails, managing debugging and test ownership, maintenance strategies for large scale, and recovery from test regressions.

Distinguish two ways of handling problems: reactive, which only moves after a problem occurs, and procedural, which has ready-to-use steps from the start. Runbooks move a team from reactive mode to procedural mode.

Resilient teams don't memorize how to handle failures; they have runbooks. This episode teaches you how to build them.

#Runbook for Failing Test Suites

#Standard Diagnosis Procedure

The first runbook you need: what to do when the suite fails. The standard procedure:

1. Look at the summary — how many tests failed and in which files.
2. Read the error message and assertion diff.
3. Determine whether the failure comes from code, environment, or the test itself.
4. Fix, then re-run the affected suite.

npx jest --runInBand --silent=false 2>&1 | tee test-output.log

The command npx jest --runInBand --silent=false runs the suite serially and copies all output to a log file — a useful artifact for investigation or team discussion.

#Runbook for Flaky Tests

Flaky tests have their own runbook because their pattern is distinctive: sometimes passing, sometimes failing. The steps:

1. Run the suite repeatedly to reproduce (see the loop pattern in episode 18).
2. Note the pattern: does it only fail in a certain order or when parallel?
3. Hunt the source of flakiness: timers, network, file order, or global state.
4. Isolate with --runInBand; if it passes, it's likely a parallel race condition.

#Managing Test Debugging & Team Ownership

#Structured Debugging

Debugging a failing test isn't guesswork. Start from the most specific assertion, then narrow down:

npx jest --runInBand -t "nama test yang gagal"

The command npx jest --runInBand -t "nama test yang gagal" runs only the suspected test in a single process. Combine it with console.log inside the test — the output appears in the terminal and helps you understand the actual values.

#Recording Findings into the Runbook

Whenever you solve an unusual failure, write the steps into the team runbook. Findings like "fails only when --maxWorkers is above 4" or "snapshot changed because of the timezone" are extremely valuable knowledge — and it's lost if it only lives in someone's head. A living runbook grows every time the team solves a real problem.

#Clear Test Ownership

Every test area must have a clear owner: the team or person responsible when that area's tests fail. Without ownership, failures drag on because everyone assumes it's someone else's part. Mark ownership in the directory structure or naming convention, and make sure CI alerts name the owner's contact.

#Large-Scale Maintenance Strategies

#Separating Test Types

The bigger the suite, the more important it is to separate test types and their run frequencies:

• Unit tests: fast, run on every commit.
• Integration tests: medium, run on every pull request.
• E2E tests: slow, run before release.

With this separation, fast feedback stays intact while thorough testing still runs before production. Separated testMatch configuration per type, or project labels, makes this scheduling easy. This is where project mode and --selectProjects from episode 17 truly shine.

#Automating Routines

Make suite inspection an automated routine: coverage trends in CI, flakiness detection by running the suite twice overnight, and weekly reports to the team. This routine data detects problems small instead of letting them pile up into a crisis. Start with one easily measured metric — for example the percentage of the suite passing in a week — then expand once the process runs smoothly.

#Recovery from Test Regressions

#Finding When the Regression Happened

When a test that used to pass starts failing, the first step is finding when the change happened. Git is your main tool:

git log --oneline -- src/kalkulator.test.js

git log --oneline -- <file> shows the commit history of the test file. Examine the diff at the commit where the test changed — that's usually where the regression appeared. If needed, use git bisect to find the culprit commit automatically.

When many tests are affected at once, check their common pattern: do they all touch the same helper, the same utility function, or the same config change? That pattern often points to a single root cause bigger than just one wrong file.

#Rollback and Fix Procedures

When a regression is found, there are two healing paths: revert the breaking change, or fix forward. Choose revert if the change is small and undoable; choose fix forward if the change was intentional and must stay. After recovery, document it in the runbook so a similar event is handled faster next time.

#Communicating When the Suite Is Broken

Prolonged suite failures erode team trust, so communicate honestly. When the suite is broken, tell the team as soon as possible, name the affected areas, and give a repair estimate. Don't silence failures by skipping tests or lowering coverage thresholds just to make the build green — those solutions push the problem into the future at a high price.

#Wrap Up

Episode 19 covered operational readiness: runbooks for failing suites and flaky tests, structured debugging with clear test ownership, large-scale maintenance strategies with test type separation, and regression recovery using Git.

Key takeaways:

• Runbooks turn failure handling into procedure, not guesswork.
• Flaky tests are handled with reproduction, isolation, and root-cause fixes.
• --runInBand -t "test name" isolates a single test for debugging.
• Every test area must have a clear owner.
• Separate unit, integration, and e2e tests by how often they run.
• Use git log and git bisect to find the source of regressions.

In the next episode, episode 20, we'll cover use cases & testing patterns — real-world examples for frontend apps, API clients, and library packages, behavior-driven testing patterns, data-driven tests with parameterized cases, and test organization best practices.