Unit testing evaluates a small software unit independently of its external dependencies. For API work, it isolates controllers or linting rules so failures identify a specific conformance or consistency problem without exercising the entire application stack. section 7.2.2 section 10.1.2
Apply the technique through focused fixtures and explicit assertions:
- Test a controller with Spring MockMvc and Rest Assured, validate its response against an OpenAPI definition, and assert the expected status code. section 7.2.2
- Mock controller dependencies when necessary, then cover both happy paths such as 2xx responses and sad paths such as 4xx and 5xx responses. section 7.2.2
- For a custom linting rule, isolate the rule under test, use a small API-definition fixture, and assert the returned diagnostic messages. section 10.1.2
- Pair valid and invalid scenarios so the test verifies both accepted definitions and the precise error message, path, and severity for violations. section 10.1.2
Controller schema test
A ControllerSchemaTest uses standaloneSetup(new ProductsApiController()), sends GET /v1/catalog/products/{id}, validates the response against product-catalog-v1-0.oas.yaml, and expects status 200. Running the test reports missing fields when the OpenAPI definition is incomplete. The test runs quickly, but it does not exercise API-gateway behavior such as an invalid API-key response. section 7.2.2
Custom linting rule test
A valid fixture gives a GET operation the operationId retrieveUsers and expects no errors. An invalid fixture gives it listUsers and expects an error stating that GET operationIds must start with retrieve or download, at the path paths /v1/users get operationId, with error severity. section 10.1.2
Listing 7.2 Product controller schema test
package com.acmepetsupplies.productcatalog;
import com.acmepetsupplies.productcatalog.controller.ProductsApiController;
import org.junit.Test;
import org.springframework.boot.test.context.SpringBootTest;
import static com.atlassian.oai.validator.mockmvc
.OpenApiValidationMatchers.openApi;
import static io.restassured.module.mockmvc.RestAssuredMockMvc.given;
@SpringBootTest
public class ControllerSchemaTest {
@Test
public void testGetProductController() {
given()
.standaloneSetup(
new ProductsApiController()) #1
.when()
.get
("/v1/catalog/products/612b4280-b5c0-4ad5-bce7-ede7ab2b90fc")
.then()
.assertThat()
.expect(openApi()
.isValid("../product-catalog-v1-0.oas.yaml")) #2
.statusCode(200);
}
}
Use the complete controller test listing to inspect isolated setup, the request, OpenAPI validation matcher, and status assertion. section 7.2.2
Listing 10.1 Unit tests for the custom linting rule
import { DiagnosticSeverity } from '@stoplight/types';
import testRule from '../__helpers__/helper'; #1
testRule( 'operationId-get-should-follow-naming-convention', [
{
scenarioName: 'Valid case: GET operations should have an
operationId starting with retrieve or download',
apiDefinition: { #2
openapi: '3.1.0',
info: { version: '1.0' },
paths: {
'/v1/users': {
get: {
operationId: 'retrieveUsers', #3
}
}
}
},
expectedErrors: [], #4
},
Use the linting-rule listing to inspect the compact scenario structure, API-definition fixture, and expected diagnostic collection. section 10.1.2
