A smoke test is a short, shallow pass over the things a build must be able to do before anyone spends time on it. Can it start. Can somebody sign in. Does the main page render. Does a record save. If any of those fail, the build is rejected and nobody looks further, because everything after that would be testing a build that was never worth testing.

It is deliberately not thorough. Thoroughness is what the rest of the suite is for, and running it against a broken build wastes a day proving in forty ways that sign-in is down.

Where the name comes from

From hardware, and the story is literal. You assemble a board, you power it up, and you watch for smoke. If it smokes, there is no point measuring anything: the fault is gross and immediate and the board goes back. Plumbers use the same phrase for pumping smoke through pipes to find leaks before the walls go up.

Software borrowed it for the same reason. A build that cannot sign a user in has produced smoke, and the correct response is to stop.

What a smoke test is not

Three terms get used interchangeably in standups and they are three different things.

Smoke test
Is this build worth testing at all? Broad and shallow, run first, on every build
Regression test
Did anything that used to work stop working? Deep and slow, run when there is time

A sanity test is the third: a narrow check that one specific fix actually works, run after a change lands rather than before testing starts. Smoke is broad and shallow; sanity is narrow and shallow; regression is broad and deep.

The practical difference is what happens when one fails. A failed regression test is a bug to file. A failed smoke test is a decision: this build stops here.

What goes in one

The rule that keeps a smoke suite useful is that everything in it must be something whose failure makes further testing pointless. That is a much shorter list than it first appears.

A typical suite for a web application:

1. The application starts and the home page returns 200
2. A known user can sign in
3. The main list loads and shows data
4. One record can be created and read back
5. A signed-in user can sign out

Five checks, a minute or two, and no assertions about behaviour beyond “this happened at all”. No edge cases, no validation messages, no permission matrices. Every one of those belongs in the suite that runs afterwards.

Two failure modes worth naming, because both are common. A suite that grows to eighty checks is no longer a smoke test, it is a slow regression suite wearing the wrong name, and people start skipping it. A suite that tests only the home page is not one either: it will pass on a build where nothing else works.

When it runs, and who looks at it

On every build, before anything else, and automatically. A smoke test somebody has to remember to run is one nobody runs on the afternoon it would have mattered.

The usual arrangement is a stage in continuous integration that runs after the deploy to a test environment and gates everything downstream. If it fails, the pipeline stops, the build is not promoted, and the team is told immediately - within minutes of the commit, while the person who wrote it still remembers what they changed.

That immediacy is most of the value. The same defect found a day later costs someone an hour of reconstruction before they can even begin.

Writing your first one

Start from the shortest path a real user takes through your product, and check only that each step completes.

  • Pick five things, not fifty. If you cannot argue that a failure makes further testing pointless, it is not a smoke check.
  • Use a known account and known data. A smoke test that depends on whatever happens to be in the database will fail for reasons that are not about the build.
  • Assert existence, not correctness. “The invoice total is 45.00” belongs elsewhere. “An invoice page rendered” belongs here.
  • Keep it under five minutes. The moment it costs more than that, somebody will move it out of the critical path, and then it stops gating anything.
  • Fail loudly. A red pipeline nobody is told about is a green pipeline with extra steps.

When it fails

A failed smoke test is not a bug report. It is a signal that one is needed, and the two are easy to confuse: “smoke test 3 failed” tells the person picking it up nothing about what happened.

What they need is the same thing any defect needs - what was expected, what happened instead, in which environment, with whatever the browser or the runner recorded at the time. Our guide to writing a bug report that gets fixed is the long version, and its template is a file you can hand to whoever is on triage.

For a failure a person hits by hand rather than one the pipeline caught, the context is the part that usually goes missing.

Session Replay

Free Chrome extension. One click on the page that is misbehaving captures the screenshot, the console and the network log, and hands you a link to paste into the ticket.

Get the extension

The short version

A smoke test answers one question: is this build worth anybody’s time? Five checks, run first, run always, and a failure stops the line rather than filling the tracker. Everything else you want to know about the build is a question worth asking only after this one has been answered yes.