Simplify API testing with declarative YAML-based test suites

Tired of rewriting the same scaffolding for every API test? A .NET developer found a better way. By shifting API testing to a declarative YAML format, they cut boilerplate while keeping tests flexible and maintainable.

The problem with repetitive API test scripts

API integration tests often follow a familiar pattern: create a test class, set up an HttpClient, deserialize responses, write custom matchers for dynamic fields like IDs and timestamps, and repeat for each endpoint. The real logic in these tests is minimal—just a method, path, input data, and expected output—but the surrounding ceremony grows with every new endpoint.

For a project with a sizable REST API, this duplication became unsustainable. Each new endpoint required another test class, fixture, and boilerplate setup. The developer realized most of the effort wasn’t about testing behavior but about managing infrastructure. What if the test could focus solely on the essential information and let the framework handle the rest?

A declarative approach to API testing

That insight led to the creation of ConfIT, a .NET library that lets you define API tests in YAML (or JSON) and delegates execution, mock setup, response validation, and variable passing to the library itself. The approach replaces repetitive code with a clean, data-driven format.

A typical test in ConfIT looks like this:

CreateUser:
  tags: [smoke]
  api:
    request:
      method: POST
      path: /api/users
      body:
        name: Alice
        email: alice@example.com
    response:
      statusCode: 201
      matcher:
        semantic:
          id: isUuid
        extract:
          userId: $.body.id

GetUser:
  api:
    request:
      method: GET
      path: /api/users/{{userId}}
    response:
      statusCode: 200
      body:
        name: Alice
        email: alice@example.com
      matcher:
        ignore: [createdAt]

The placeholder {{userId}} automatically pulls the extracted value from the first response, eliminating the need for custom processors. The matcher block replaces most handwritten assertions with built-in rules like isUuid, isIsoDate, and greaterThan(n). Fields marked as ignore are excluded from validation, letting you focus on what matters.

One test file, two testing modes

ConfIT’s most practical feature is its ability to run the same YAML file in two modes without duplicating test suites. In component tests, the service runs in-process with dependencies mocked via WireMock. In integration tests, everything runs end-to-end.

Setting up a component test suite previously required significant boilerplate. Now it’s reduced to a concise fixture:

public TestSuiteFixture()
  => _suite = SuiteBootstrapper.ForComponent<Startup>(
       "suite.config.yaml",
       onStarted: svc => new DbInitializer(svc.GetRequiredService<AppDbContext>()).Seed());

public TestSuiteContext Context => _suite.Context;

Configuration details like authentication, mock server URLs, and folder paths live in suite.config.yaml. The only C# code left is project-specific seeding logic, which genuinely varies by implementation.

Beyond testing: documentation in disguise

The YAML test files evolved into an unexpected asset. New engineers can read them to grasp API behavior without diving into code. QA teams can add test cases without touching C# files. During code reviews, reviewers see data, not logic, making reviews faster and more precise.

Of course, ConfIT isn’t a silver bullet. Tests with complex stateful flows or heavy conditional logic still belong in traditional code. It’s designed for the bulk of CRUD-style APIs where repetition outweighs complexity.

Broad compatibility and growing recognition

ConfIT targets .NET 9 and .NET 10, and supports non-.NET services through an AppLauncher mode. It can boot external processes via shell commands and interact via HTTP, letting the same YAML files work for Go, Node.js, or Python services.

The project recently gained visibility on the ThoughtWorks Technology Radar in the Assess ring, praised for reducing duplication between component and integration tests—the exact problem it was built to solve.

A lightweight path forward

If your team spends more time maintaining test scaffolding than writing meaningful assertions, a declarative approach like ConfIT could be worth exploring. It won’t replace every test scenario, but for routine API validation, it can shift the balance from boilerplate to behavior.