# What CI Testing Actually Is

Picture the moment you open a pull request. You push your branch, the page loads, and there's a small
spinner next to your commit that turns into a green check or a red X. Most people learn to read that
check long before they understand it - green good, red bad, merge when green. That's fine for surviving,
but the moment a check goes red for a reason you can't reproduce, the mystery becomes a problem.

## The mental model: a tireless teammate who runs your tests

**What it actually is.** *CI* - continuous integration - is, for our purposes, a **server that
automatically runs your test suite every time anyone pushes code.** That's the whole core idea. Not a
person. Not your laptop. A machine that wakes up on every push, grabs your code, runs the tests, and
reports back: passed or failed.

📝 **Terminology.** *CI* stands for *continuous integration* - the practice of merging everyone's work
together often and checking it automatically each time. The *server* that does the checking is the
**CI server** (or *CI runner*). Common ones: GitHub Actions, GitLab CI, CircleCI, Jenkins. They differ
in setup but do the same job.

**Why people get this wrong.** The common picture is that CI is some elaborate, mysterious deployment
robot. It can grow into that - but the heart of it is humble: it runs the same `npm test` or `pytest`
or `cargo test` you already run, just on a fresh machine, automatically, every time. If you can run
your tests in a terminal, you already understand 90% of what CI does. The other 10% is *where* and
*when* it runs.

**What it does in real life.** Every push triggers a fresh run. You don't click anything. You don't
remember to do it. The robot doesn't get tired, doesn't skip the slow test because it's late, and
doesn't forget. That reliability is the entire point - humans forget to run tests; the server never does.

```mermaid
flowchart TD
  Push[You push a branch] --> Wake[CI server wakes up]
  Wake --> Clean[1. grab a clean machine]
  Clean --> Code[2. download your code]
  Code --> Deps[3. install dependencies]
  Deps --> Test[4. run the test suite]
  Test --> Report[Report back to your PR: green or red]
```

## The green check is the gate

**What it actually is.** That check next to your pull request is the CI server's verdict, posted right
where the team makes the merge decision. Green means *every test passed on a clean machine.* Red means
*at least one failed* - and you can click in to see exactly which one.

**Why this matters more than it looks.** The check isn't just information; on most teams it's a **gate.**
A repository can be configured so the merge button stays disabled until the check is green. That single
setting changes the social contract of the team: nobody can merge broken code into `main`, not even by
accident, not even the person who set up the project. The rule is enforced by a machine, so it applies
to everyone equally.

```text
   Pull request: "Add cart subtotal"

      ✓  Tests passed (142 passed)            ← green: merge button is enabled
   ─────────────────────────────────────
      ✗  Tests failed (1 failed, 141 passed)  ← red: merge button is blocked
```

💡 **Key point.** CI testing turns "we *should* run the tests before merging" (a hope) into "you
*cannot* merge unless the tests pass" (a guarantee). The value isn't the tests - you already had those.
The value is that they now run automatically and block bad merges.

## Why this beats "it passed on my machine"

You've heard the phrase, maybe said it. The tests pass for you, fail for someone else, and the argument
goes in circles. CI ends that argument, because it removes *your machine* from the equation entirely.

Here's why your machine lies to you, gently and constantly:

- **You have things installed that you forgot about.** A global tool, a specific language version, an
  environment variable set months ago. Your tests quietly depend on it. The new teammate doesn't have
  it, and neither does the CI server.
- **You didn't commit everything.** A new file you forgot to `git add`, a dependency you installed
  locally but never wrote into `package.json`. It works for you because it's *on your disk* - not
  because it's *in the repository.*
- **Your machine is in a particular state.** A database left running from yesterday, a cache, a built
  artifact. The next person starts from nothing.

**What CI does about it.** The CI server starts from a **clean, empty machine every single time.** It
has nothing installed that you didn't declare. It has nothing on disk except exactly what's committed to
the repository. So if your tests pass in CI, they pass *from a clean checkout of what's actually in the
repo* - which is the only state that matters, because it's the state every teammate and every deploy
starts from.

🪖 **War story.** A teammate once spent a morning convinced a colleague had broken the build "out of
nowhere." The tests passed on his machine, failed in CI. The culprit: a config file he'd created weeks
earlier, used in every test, and never committed - it lived on his laptop and nowhere else. For him the
suite was green forever; for the clean CI machine, and for every new hire, it had never passed once. CI
didn't break anything. It told the truth his laptop had been hiding.

⚠️ **Gotcha.** "It passed on my machine" and "it passed in CI" are answers to *different questions.*
Yours answers "does it work in my exact setup?" CI answers "does it work from a clean copy of the
repo?" When they disagree, **CI is almost always the one to trust** - because a clean checkout is what
production gets, not your laptop.

**Why this saves you later.** Once you internalize that CI runs from a clean room, red checks stop
feeling like personal attacks and start being useful clues. A test green for you and red in CI is rarely
the universe being unfair - it's almost always *something on your machine that isn't in the repo.*

## Recap

1. **CI is a server that automatically runs your test suite** on every push and pull request - the same
   tests you run locally, just on a fresh machine, every time, without anyone remembering to.
2. **The green/red check on a PR is the server's verdict**, posted where the merge decision happens.
3. Teams turn that check into a **gate**: the merge button stays blocked until tests pass, so broken
   code can't reach `main`.
4. CI beats "it passed on my machine" because it **starts from a clean checkout** - nothing installed,
   nothing on disk except what's committed - which is the only state that actually matters.