Design, test, refactor, review, estimate and run software the way professional teams do.

Software Engineering Practices

## Why it matters

Automated tests let you change code without fear. A good suite tells you in seconds that a change broke something, long before a user does. You have already written simple tests that call a function and compare the result. Real code is harder: it reads the clock, sends email, calls APIs and writes to databases. This lesson shows how to test that kind of code quickly and reliably by replacing slow or unpredictable parts with **test doubles**.

## What makes a good unit test

A unit test checks one small piece of behaviour in isolation. Good unit tests are:

- **Fast:** milliseconds each, so you run them all the time.
- **Deterministic:** the same result on every run, on every machine. No real network, no real clock, no randomness you do not control.
- **Focused:** one behaviour per test, with a name that says what it checks.
- **About behaviour, not implementation:** they check what the function returns or does, not which private helpers it called.

Most tests follow **Arrange, Act, Assert**:

```javascript
test("adds tax to the subtotal", () => {
  const cart = { subtotal: 100 };          // Arrange
  const total = totalWithTax(cart, 0.08);  // Act
  expect(total).toBe(108);                 // Assert
});
```

Tools such as Jest, Vitest and Node's built-in `node:test` provide `test` and `expect`. The ideas in this lesson apply to all of them.

## Test doubles

A **test double** stands in for a real dependency during a test. The names are used loosely in practice, but the distinctions are useful:

| Double | What it does | Example |
|---|---|---|
| **Stub** | Returns canned answers | a clock whose `now()` always returns 9:00 |
| **Fake** | A working but simplified implementation | an in-memory array instead of a database |
| **Spy** | Records how it was called | a mailer that stores every message it was asked to send |
| **Mock** | A spy with built-in expectations that fail the test | "expect `send` to be called once with these arguments" |

You can only use a double if the code lets you swap the dependency in. That is **dependency injection**: pass collaborators as parameters instead of importing globals.

```javascript
// Hard to test: uses the real clock and the real mailer.
function sendDueRemindersHard(tasks) {
  const now = new Date();
  for (const t of tasks) if (t.dueAt <= now) realMailer.send(t.owner, t.title);
}

// Easy to test: the clock and the mailer are injected.
function sendDueReminders(tasks, clock, mailer) {
  const now = clock.now();
  let sent = 0;
  for (const t of tasks) {
    if (!t.done && new Date(t.dueAt) <= now) {
      mailer.send(t.owner, "Reminder: " + t.title);
      sent += 1;
    }
  }
  return sent;
}
```

Now a test can build a stub clock and a spy mailer in two lines each:

```javascript
const clock = { now: () => new Date("2026-10-23T09:00:00Z") };
const mailer = { sent: [], send(to, subject) { this.sent.push({ to, subject }); } };

const tasks = [
  { owner: "ada@example.com", title: "Pay invoice", dueAt: "2026-10-22T12:00:00Z", done: false },
  { owner: "bob@example.com", title: "Plan sprint", dueAt: "2026-10-30T12:00:00Z", done: false },
];

const count = sendDueReminders(tasks, clock, mailer);
// count === 1, and mailer.sent[0].to === "ada@example.com"
```

The test runs in microseconds, never emails anybody, and gives the same answer next year because the clock is frozen.

## Does your test actually catch bugs?

A test that always passes is worse than no test, because it gives false confidence. One way to check a test is to break the code on purpose and see whether the test fails. Change `<=` to `<`, or delete the `!t.done` condition, and run the suite. If everything is still green, the test is missing a case. Automated tools do this at scale (**mutation testing**, for example Stryker for JavaScript), but doing it by hand on an important function is a quick, honest review of your own tests.

Edge cases worth a test of their own: an empty list, a value exactly on the boundary (due *exactly* now), items that should be skipped (already done), and invalid input.

## Where unit tests stop

Unit tests with doubles prove that your logic is right *given* that the dependencies behave as the double says. They do not prove the real database or email service behaves that way. That is the job of a smaller number of **integration tests** (your code plus a real or containerised dependency) and a few **end-to-end tests** (the whole app, driven like a user). Teams often picture this as a pyramid: many unit tests, fewer integration tests, a handful of end-to-end tests.

## Common mistakes

- Mocking everything, including simple pure functions, so tests only repeat the implementation.
- Asserting on internal details (which helper was called) instead of the result, so every refactor breaks tests.
- Using the real clock or `Math.random()` in tests, causing failures that come and go ("flaky" tests).
- Never seeing a test fail. Write it, then break the code once to prove it can.

## Recap

- Fast, deterministic, focused tests; Arrange, Act, Assert.
- Inject dependencies so tests can pass in stubs, fakes and spies.
- Check your tests by breaking the code on purpose.
- Unit tests for logic, a few integration and end-to-end tests for the real wiring.

## Try it

In the **Do** tab, build a stub clock and a spy mailer, implement reminder logic, and write a test that catches a buggy version.


Write fast, deterministic unit tests by injecting stubs and spies, and check that your tests catch bugs.

Testing in depth

Introduction To Testing In JavaScript With Jest

Unit Tests and Test Doubles like Mocks, Stubs & Fakes

## Why it matters

**Refactoring** means changing the structure of code without changing what it does. You refactor so the next change is easier: so a new feature fits cleanly, a bug is easier to find, or a teammate can understand the code in minutes instead of hours. The key word is *without changing what it does*. A refactor that quietly changes behaviour is a bug, and the only reliable way to know you have not changed behaviour is a set of tests that you run after every small step.

## Code smells: signs a refactor would help

A **code smell** is a surface sign that something deeper may be wrong. It is a prompt to look, not proof of a problem.

- **Long function:** you have to scroll, and comments separate the "sections".
- **Deep nesting:** `if` inside `if` inside `for`, so it is hard to see which conditions lead where.
- **Magic numbers and strings:** `0.0825`, `"G"`, `365` with no name.
- **Duplicated logic:** the same rule written in two places that must change together.
- **Long parameter list:** five positional arguments that callers mix up.
- **Unclear names:** `d`, `tmp`, `data2`, `doStuff`.

## The safe loop

1. **Make sure tests cover the behaviour.** If the code has none, write **characterization tests** first: call the existing code with representative inputs and record what it returns *today*, even if it looks odd. Those tests pin down current behaviour.
2. **Make one small change.** Rename a variable. Extract one function. Replace one magic number with a constant.
3. **Run the tests.** Green: commit, or at least keep going. Red: undo the step; it was not a pure refactor.
4. **Repeat.**

Small steps feel slow but are fast overall, because when a test fails you know exactly which change caused it. Keep refactoring commits separate from behaviour changes so reviewers can check each one easily.

## Worked example

Here is a legacy shipping function:

```javascript
function ship(w, c, p) {
  let r = 0;
  if (c === "US") {
    if (p) {
      r = 0;
    } else {
      if (w > 10) { r = 5 + (w - 10) * 0.5; } else { r = 5; }
    }
  } else {
    if (w > 10) { r = 15 + (w - 10) * 1.5; } else { r = 15; }
  }
  return r;
}
```

**Step 1, characterization tests.** Before touching anything, record what it returns:

```javascript
ship(4, "US", false)   // 5
ship(14, "US", false)  // 7
ship(14, "US", true)   // 0
ship(4, "FR", true)    // 15   (premium does not apply abroad, today)
ship(14, "FR", false)  // 21
```

**Step 2, rename for meaning.** `w` becomes `weightKg`, `c` becomes `country`, `p` becomes `isPremium`. Run the tests.

**Step 3, name the numbers.** Pull the rates into one place:

```javascript
const RATES = {
  domestic: { base: 5, perExtraKg: 0.5 },
  international: { base: 15, perExtraKg: 1.5 },
};
const FREE_WEIGHT_KG = 10;
```

**Step 4, extract the repeated rule and flatten with guard clauses.**

```javascript
function weightCharge(weightKg, rate) {
  const extra = Math.max(0, weightKg - FREE_WEIGHT_KG);
  return rate.base + extra * rate.perExtraKg;
}

function ship(weightKg, country, isPremium) {
  if (country === "US" && isPremium) return 0;
  const rate = country === "US" ? RATES.domestic : RATES.international;
  return weightCharge(weightKg, rate);
}
```

Run the tests after each step. All five still pass, so behaviour is unchanged. The new version has no nesting, every number has a name, and the next change ("raise the international base to 18") is one edit in one place.

Notice what we did *not* do: we did not "fix" the rule that premium does not apply abroad. Maybe it is a bug, maybe it is policy. A refactor keeps it; changing it is a separate, deliberate change with its own test and its own commit.

## Common refactorings

| Smell | Refactoring |
|---|---|
| Long function | Extract function |
| Deep nesting | Guard clauses (return early) |
| Magic number | Replace with named constant |
| Unclear name | Rename variable or function |
| Long parameter list | Pass one options object |
| Duplicated logic | Extract shared function (when the copies must change together) |

Most editors automate rename and extract function safely across files. Use those tools rather than search-and-replace.

## Common mistakes

- Refactoring without tests and "checking by eye".
- Mixing a refactor and a feature in one commit, so a reviewer cannot tell which line changed behaviour.
- Fixing odd behaviour mid-refactor without asking whether something depends on it.
- Refactoring code nobody needs to change. Improve the code you are about to work in.

## Recap

- Refactor = same behaviour, better structure. Tests are what make it safe.
- No tests? Write characterization tests that record today's behaviour first.
- Small steps, run tests after each, separate commits for refactors and fixes.

## Try it

In the **Do** tab, refactor a tangled pricing function while a set of characterization checks keeps you honest.


Spot code smells and refactor in small steps while characterization tests keep behaviour the same.

Refactoring

What is Refactoring, and why is it so important?

Refactoring JavaScript code into tiny, pure, composable functions

Create a folder `debug-lab`, run `npm init -y`, add `"type": "module"` to `package.json`, and create `cart.js` with three functions: `findProduct(catalog, id)` that returns `catalog.find((p) => p.id === id)`, `lineTotal(item, product)` that returns `item.qty * product.price`, and `cartTotal(cart, catalog)` that sums `lineTotal` over every item. Export each one with `export function`.

Create `run.js` that calls `cartTotal` with a catalog of two products and a cart of three items, where one item's `productId` is not in the catalog. Run `node run.js` and copy the full error output into a notes file.

Read the stack trace from the top: write down the error type, the message, and the first frame (file, line and column) in your own code. Then find the frame that called it.

Add one structured log line in `cartTotal` before the crash point, for example `console.log(JSON.stringify({ level: "warn", msg: "product not found", productId: item.productId }))`, run again and confirm the log line points at the cause.

Write your hypothesis in one sentence in your notes (what input causes the failure and why).

Write a failing test with Node's built-in runner: create `cart.test.js` using `import test from "node:test"` and `import assert from "node:assert/strict"`, call `cartTotal` with the bad cart, and assert the behaviour you want (for example, the missing item is skipped and the total of the other items is returned). Run `node --test` and see it fail.

Fix the cause in `cartTotal` (not by wrapping everything in try/catch), run `node --test` until it passes, and keep the warn log so the problem stays visible.

Commit the test and the fix together with a message that describes the bug, for example `fix(cart): skip items whose product no longer exists`.

## Why it matters

On your own machine you can pause code in a debugger and inspect every variable. In production you usually cannot. A user reports "checkout is broken", and what you have is an error message, a **stack trace** and some **logs**. Debugging production issues is the skill of turning those clues into a reproducible bug, a fix and a test that keeps it fixed. It is a large part of what working engineers do, and it rewards a calm, methodical approach over clever guessing.

## Reading a stack trace

When a JavaScript error is thrown and not caught, Node prints the error and the chain of function calls that led to it:

```text
TypeError: Cannot read properties of undefined (reading 'price')
    at lineTotal (/app/src/cart.js:14:20)
    at Array.reduce (<anonymous>)
    at cartTotal (/app/src/cart.js:20:22)
    at handleCheckout (/app/src/routes/checkout.js:31:17)
    at Layer.handle (/app/node_modules/express/lib/router/layer.js:95:5)
```

Read it like this:

1. **The first line is the error type and message.** `TypeError: Cannot read properties of undefined (reading 'price')` means some code did `x.price` while `x` was `undefined`.
2. **The next line is where it was thrown:** function `lineTotal`, file `src/cart.js`, line 14, column 20.
3. **Each line below is the caller of the one above.** `cartTotal` called `lineTotal` (through `reduce`), and the route handler called `cartTotal`.
4. **Skip frames from libraries** (`node_modules`, `<anonymous>`, framework internals) and find the first and last frames in *your* code. The bug is usually in your code, near those frames.

So the question becomes: why did `cartTotal` pass `undefined` to `lineTotal`? Open `cart.js` at line 20 and look at what it iterates over.

## Reading logs

Logs tell you what happened *before* the error. Good production logs are structured (one JSON object per line) and carry a **request id**, so you can filter every line from the failing request:

```text
{"level":"info","time":"2026-10-23T09:14:02Z","requestId":"r-7f3a","msg":"checkout started","userId":118,"items":3}
{"level":"warn","time":"2026-10-23T09:14:02Z","requestId":"r-7f3a","msg":"product not found","productId":"sku-404"}
{"level":"error","time":"2026-10-23T09:14:02Z","requestId":"r-7f3a","msg":"checkout failed","err":"Cannot read properties of undefined (reading 'price')"}
```

The `warn` line is the clue: a product in the cart no longer exists, the lookup returned `undefined`, and `lineTotal` crashed on it. Useful questions while reading logs:

- **When did it start?** Compare with the time of the last deploy or configuration change.
- **Who is affected?** Every request, one user, one region, one browser?
- **What is different** about the failing requests compared with the successful ones?

## A method that works

1. **Gather facts.** Error message, stack trace, logs for one failing request, time it started, recent changes.
2. **Form a hypothesis** that explains all the facts: "carts containing a deleted product crash checkout."
3. **Reproduce it locally**, ideally as a failing automated test: a cart with an item whose product is missing.
4. **Fix the cause**, not just the symptom. Here the right behaviour might be to drop the missing item and show a message, rather than wrapping everything in `try/catch` and hiding the error.
5. **Run the test** (now green) and the rest of the suite.
6. **Check in production** after the deploy: the error rate in the logs or dashboard should fall.

If you cannot form a hypothesis, narrow the search. **Bisect**: if it worked in last week's release and fails in today's, `git bisect` can find the commit that introduced the bug in a handful of steps by testing halfway points. **Add logging** around the suspect area and deploy it, then wait for the next occurrence.

## Mitigate first, fix second

When users are affected, the first priority is to stop the damage. Rolling back the last deploy or turning off a feature flag is often faster and safer than writing a fix under pressure. Then debug calmly. The incidents lesson in this course covers this in more depth.

## Common mistakes

- Reading only the error message and skipping the stack trace and logs.
- Changing several things at once, so you cannot tell which change fixed it.
- "Fixing" by catching and ignoring the error, so the bug hides and corrupts data later.
- Not writing a test for the bug, so it comes back.
- Logging secrets or personal data while debugging. Logs are often kept for months and seen by many people.

## Recap

- A stack trace reads top-down from where the error was thrown to the outermost caller; focus on frames in your own code.
- Structured logs with a request id show what led up to the error.
- Facts, hypothesis, reproduce as a test, fix the cause, verify in production.
- Under pressure, mitigate first (roll back, disable the feature), then fix.

## Try it

In the **Do** tab, reproduce a real bug from a stack trace on your own machine, then fix it under a test.


Turn a stack trace and logs into a hypothesis, a failing test and a fix.

Debugging production issues

Debugging with stack traces | Intro to CS - Python | Khan Academy

12 Logging BEST Practices in 12 minutes

Write fast, deterministic unit tests with test doubles, refactor safely under tests, and debug production issues from logs and stack traces.