An OpenAPI document is a contract on paper. The server has not signed it yet. Every missing required field, every too-short string, every number below the documented minimum — those are the moments where the paper contract and the running server disagree, and you only find them by sending bad requests on purpose. That is the whole job of API Contract Stress Tester: read the contract, generate the boundary cases the contract itself implies, and ship them.
The interesting design choice is that boundary cases are not invented. They are derived. Given a field with minLength: 5, the contract implies a too-short case of length 4. Given maximum: 100, the contract implies a too-large case of 101. Given an enum: ["admin", "member"], the contract implies a value of __invalid_enum__. The tool reads the schema and walks a small grammar of edge cases by type — string, integer, number, boolean, array, object — and emits one boundary case per constraint per field. That grammar is the mental model this article is built around.
It is worth saying up front: this is not a load-testing tool. It does not spawn 10,000 virtual users or chart a latency curve. It is closer to a careful, exhaustive negative-test generator that respects the schema you already wrote. If you want the load curve, the obvious sibling is API Mock Server for the synthetic traffic layer; this tool focuses on the opposite question — what does the contract say is invalid, and does the server agree?
What the Tool Actually Walks
Boundary cases are not random. They are the complement of “what makes this field valid.” When you write type: integer, minimum: 18, the contract simultaneously asserts “values 18 and above are accepted” and — by implication — “values 17 and below should be rejected.” The tool’s job is to make that second half explicit and testable. Looking at the OpenAPI document operation by operation, for each path parameter, query parameter, header parameter, and JSON body field, it walks a small type-by-type case list:
- Strings — empty string when the field is effectively required, one character short of
minLength, one character pastmaxLength, and an__invalid_enum__placeholder for enum-bound strings. - Numbers — one unit below
minimum, one unit abovemaximum, and a value that lands outside any numeric enum. - Booleans — a literal string payload like
"not-a-boolean"sent where the schema demands a real boolean. - Arrays — a scalar where an array is documented, one fewer item than
minItems, and one more item thanmaxItems. - Objects — deletion of any field marked
required.
Each generated case carries a severity tag — info, warning, or critical — assigned by how badly the contract expects the server to reject it. A missing required field is critical because the contract calls the resource incomplete without it. An enum violation is critical because the contract explicitly lists the allowed set. A too-short string is warning because the contract defines the floor but the right HTTP status is one of several reasonable choices. An empty string on a non-required field is info because the contract is silent and you are probing the gray zone.
The output JSON shape makes this severity ladder explicit. Each case has id, endpoint, title, location, fieldPath, severity, and a fully-materialized requestPreview ready to be replayed against any HTTP client. If you tick Execute Real Requests and supply a Base URL, the tool adds an observed field to each case: the real HTTP status, the first 400 characters of the response body, and a boolean mismatch flag that fires when the server’s reply is not one of the statuses the OpenAPI responses block documents.
The maximum-cases-per-field knob, capped at six, is the practical guardrail. A schema with twenty fields and an aggressive enum set can otherwise produce hundreds of cases; six keeps the report scannable. If you want a tighter probe, drop it to one and you get the most pessimistic case per field; if you want full coverage, six gets you the entire grammar.
The Five Field Types and What They Imply
The mental model is most useful when you see the same grammar repeated across types. Each type has a “happy path” implied by the schema, and a small set of “unhappy paths” that are the schema’s own claim about how it can be broken.
For a string field, the happy path is “non-empty, length within bounds, value in enum.” The unhappy paths are empty, one under minLength, one over maxLength, and a non-enum value. The contract asks four questions of the server: does empty get a 400? Does too-short get a 400? Does too-long get a 400? Does an out-of-enum value get a 400? The tool emits one request per question. You answer them by reading the four observed statuses.
For a numeric field, the happy path is “within [minimum, maximum] and in the enum if any.” The unhappy paths are one below minimum, one above maximum, and a value that lands outside the numeric enum. Same shape: one question per implied constraint, one request per question. The interesting case is when a field declares both a numeric enum and a range — the contract is then asking two things at once and the tool emits both probes.
For an array, the happy path is “length within [minItems, maxItems] and items valid.” The unhappy paths are scalar where array is expected, one fewer item, and one more item. Note that array-item validity is not probed — if you want that, the contract says so by giving the array an items schema, and the tool recursively walks that schema’s fields. So a request body that is an array of user objects gets probed for array shape on the outer container, and the inner objects get probed field-by-field via the recursive walk.
For a boolean, the only meaningful unhappy path is “string where boolean is expected.” It is a smaller case list, and the severity is warning rather than critical because the contract does not explicitly require a 400 — it only requires a boolean. Some servers coerce, some reject; the tool flags it as worth checking but not as a contract violation.
For an object, the unhappy paths are field-by-field. Required fields get a deletion case (severity critical); non-required fields get the type-specific cases their schema declares. The recursive walk through nested objects means a deeply nested schema — say, a request body with an address object inside a user object — gets probed at every leaf, with fieldPath strings like body.address.zipcode that point you straight at the violated constraint.
How to Read the Mismatch Flag
The mismatch field is the part of the output that turns a test plan into a real diagnostic. When you supply a Base URL and tick Execute Real Requests, the tool sends each generated case and records the actual HTTP status. The mismatch flag fires when that observed status is not among the response codes the OpenAPI responses block documents for that operation.
That sounds simple, but the matching logic is smarter than a string equality check. An OpenAPI operation that documents "4XX" or "5XX" is matched against any status in that range, so a 422 from a server that documented "4XX" is not flagged. A documented "default" response matches anything. A 404 on a resource that documented only "200" and "default" is matched by the default clause. This is exactly the right behavior — it is how the OpenAPI 3.x spec intends ranges and defaults to be read — but it means a single contract mismatch usually shows up as one or two flagged cases, not twenty.
When you see mismatch: true, the next field to read is bodyPreview: the first 400 characters of the actual response body, included so you can tell at a glance whether the unexpected status came with a useful error message or with a generic stack trace. A 500 with no body and a 500 with a JSON error envelope look the same in the status column but mean very different things for your fix list.
This is where the tool starts to look like the validation cousin it actually is — a sibling to API Response Contract Validator, which checks response bodies against the documented schema, and a counterpart to API Breaking Changes Detector & Migration Planner, which checks whether two versions of an OpenAPI document introduce breaking changes at all. The three together form a contract testing triangle: the stress tester checks what the server rejects, the validator checks what it accepts, and the breaking-changes detector checks whether your spec even agrees with last month’s spec.
What Good OpenAPI Inputs Look Like
The quality of the output is bounded by the quality of the schema. A vague schema generates vague cases. The tool is at its sharpest when the OpenAPI document is explicit about every constraint — minLength and maxLength on strings, minimum and maximum on numbers, minItems and maxItems on arrays, enum on anything that has a closed set, and required lists on every object. The richer the schema, the more cases get generated, and the more useful the resulting probe list.
The opposite is also worth saying. If your OpenAPI document uses type: string with no length bounds, the only boundary case the tool can derive is the empty string. That is a fine case to test, but it is one case rather than three. The lesson is that this tool rewards schema authors who take the time to declare bounds; a schema with type: string everywhere will pass through it almost unchanged.
For real-world inputs, the OpenAPI samples hub has dozens of representative specs across REST, GraphQL, and event-driven APIs, each with realistic minLength, enum, and required declarations. The OpenAPI / Swagger samples hub covers the older Swagger 2.0 shapes that are still common in legacy services. If you are building or maintaining a contract-testing pipeline, these are the kinds of inputs you want to keep on hand — not toy schemas, but realistic examples that exercise the full grammar.
If your team already maintains Postman collections for manual QA, the Postman Collections samples hub pairs naturally with this tool: the collections cover the happy paths your team already tests by hand, and the boundary cases from this tool cover the unhappy paths nobody ever bothers to type. The two together give you a complete contract-testing surface with almost no extra work.
Offline Mode Versus Live Mode
The Base URL field is the toggle between two completely different workflows. Leave it blank, leave Execute Real Requests off, and the tool is a static case generator: it reads the schema and emits a JSON report listing every boundary case implied by the contract, with no network activity. This is the right mode for early development, when you are still designing the contract, or when you want a test plan to share with the team before any infrastructure is up.
Fill in a Base URL, tick the checkbox, and the tool becomes a live probe: it sends every generated case as an HTTP request, with the timeout you specified, with an optional Authorization Header for protected endpoints. The output is the same shape plus an observed block per case. This is the right mode for staging and pre-production, when you want to know whether the server’s actual rejection behavior matches the contract before you ship.
The Authorization Header is passed verbatim into the request, so any header value works — Bearer <token> for JWT, a static API key for legacy services, an HMAC signature for service-to-service. The header is applied uniformly across all generated cases, including the ones that delete a required field or send a malformed body. The tool does not attempt to authenticate before probing, so for endpoints behind a session you should generate a fresh token first and paste it in.
The timeout field, bounded between 500 ms and 30,000 ms, defaults to 8,000 ms — long enough for slow servers, short enough that a hung endpoint does not stall a CI job for minutes. If you are running this tool against a fleet of microservices from a build pipeline, the default timeout is the right starting point; bump it only if you have specific evidence that a particular endpoint needs more.
Where This Fits in the Test Pyramid
Boundary-case generation lives in an awkward middle layer. It is not a unit test — there is no function under test, just an HTTP endpoint. It is not a full end-to-end test — it does not drive a UI or simulate a user flow. It is not a load test — it sends one request per case, not thousands per second. It is closest to what people call contract testing, the layer that sits between unit and integration.
This is also where it pairs with sibling tools. API Doc Generator is the upstream half: it turns code or annotated comments into the OpenAPI document this tool reads. API Mock Server is the downstream half: it gives you a server that respects a contract before the real one exists, which means you can run these boundary cases against the mock first and then against the real server when it ships, comparing the two responses to find implementation drift. The three together — doc generator, stress tester, mock server — form a contract-first development loop where the OpenAPI document is the source of truth for everything else.
The Postman Collections samples hub is one practical bridge between this tool and an existing test suite. Postman collections cover the manual happy-path coverage your team has built up over months; this tool fills in the systematic unhappy-path coverage that nobody has time to write by hand. Running the Postman collection against staging gives you confidence that the documented flows still work; running this tool’s boundary cases against staging gives you confidence that the documented constraints are actually enforced.
The Grammar in One Sentence
If you remember nothing else: every constraint in your OpenAPI document implies its own negation. minLength: 5 implies a four-character case. maximum: 100 implies a 101 case. enum: [...] implies a value not in the list. required: ["email"] implies a request body with email deleted. The tool walks that implication graph, field by field, type by type, and emits the requests that prove the server agrees. There is no magic and no fuzzing — just a small grammar applied to a schema, repeated until every documented constraint has been questioned.
That grammar is why boundary-value testing earns its place in the test pyramid. It is exhaustive in a way that hand-written tests cannot be, it is reproducible in a way that exploratory testing cannot be, and it is grounded in the contract itself in a way that load testing cannot be. Paste an OpenAPI document into the tool, decide whether you want offline cases or live probes, and let the schema tell you where it can be broken. The mismatches that show up are the conversations worth having with whoever wrote the server.
For more contract-first tooling — schema validation, breaking-change detection, mock servers, doc generation — explore the rest of the elysiatools API development collection.
