Learn integration testing

An integration test checks that the pieces of your system work together. An API writes to a database, a browser shows the response, or a message reaches its handler. These lessons teach you to write those tests with ProtoTest and understand them when they fail.

Plan for about 5 to 10 minutes of reading per lesson. Running the examples may take longer. Some lessons ask you to run or change sample code. Others walk through recorded results.

You need no ProtoTest experience to start. The reference holds the details when you want them.

New here? Start with Run the sample suite. For an introduction to the problems these lessons address, read Why integration tests get hard. Forgot a word? The Vocabulary explains each one in a sentence and links the lesson that teaches it.

The tracks

Start with track 1, then choose a track whose prerequisites you have covered. Each card lists them under Needs. Follow the lessons within a track in order, and check each lesson for tools or earlier work it needs.

1. 1StartAbout 30 minutes

   Run the sample suite, write your first test, and see in the viewer why a test failed.

   1. Install and run
   2. Write your first test
   3. Read the trace

   Needs: The .NET 10 SDK and the .NET 8 runtimes

2. 2Write good integration testsAbout 1 hour

   Set up the host once, add integrations, sign a test in as a user, and give each test its own data that is cleaned up afterwards.

   1. Capabilities and the host
   2. One host, one lifetime
   3. Add and remove an integration
   4. Sign in as a test user
   5. Give each test its own state
   6. What a test leaves behind
   7. When not to compose

   Needs: Start

3. 3Across boundariesAbout 45 minutes

   Test an API, a database, a browser, messages and generated files, each from the same kind of test.

   1. Call an API and check its shape
   2. Write over REST, read over GraphQL
   3. Check what the application stored
   4. Drive the browser with a page object
   5. Follow a message through a broker
   6. Check a generated file

   Needs: Start

4. 4Reliable testsAbout 30 minutes

   Replace sleeps and shared state: move the test clock, wait until a service is ready, run tests in parallel safely, and poll a read that lags.

   1. Move the test clock
   2. Wait for readiness, not for time
   3. Parallel safety
   4. Wait for a lagging read

   Needs: Write good integration tests

5. 5Understand failuresAbout 75 minutes

   Find why a test failed, diagnose a flaky test, tell findings from failures, gate a run, read contract coverage and keep the evidence from CI.

   1. A failure tour
   2. Read a failing trace
   3. The trace as a feedback loop
   4. Diagnose a flaky test
   5. Findings
   6. Run gates
   7. Contract coverage
   8. Archive and reports
   9. Evidence in CI

   Needs: Start

6. 6Real systemsAbout 35 minutes

   Run the same suite on containers, through Aspire and against a deployed stack, and break things on purpose.

   1. Containers
   2. Aspire topology
   3. Published mode
   4. Fault injection

   Needs: Reliable tests. An OpenCSMS checkout is optional.

7. 7Extend ProtoTestAbout 50 minutes

   Write your own attributes, provisioners, page objects and integrations, and work through a failure with a coding agent.

   1. Attributes
   2. Create test data
   3. Model a screen
   4. Write an integration
   5. Swap a dependency
   6. The evidence loop with an agent

   Needs: Write good integration tests

How a lesson works

The track lessons follow the same shape:

1. The problem, in a few sentences.
2. Do it, step by step, with real code and what you should see.
3. What happened, explained after you have seen it.
4. Check yourself, one question with the answer behind a button.
5. Remember, the two or three lines worth keeping.

The links at the bottom point to the next lesson or another track to explore.

The sample behind the lessons

The lessons use Northstar.ProtoTest, the sample suite in this repository. It tests one application across its API, database, browser, messages and generated files. It includes deliberate failure drills that you enable when a lesson asks for them.

Run it with dotnet test samples/Northstar.ProtoTest. Many lessons also link to recorded traces you can read without running anything. Some ask you to inspect the trace from your own run.

The Real systems track uses a second suite, OpenCSMS, which runs on containers and real processes. It lives in its own repository, MSeys/OpenCsms. Those lessons also work as a read-through of its recorded runs.