api-test-tool-selector
Action-taking agent that reads a target API project (`*.openapi.yaml`, `*.proto`, `*.graphql`, `pact.json`, `package.json`, `pom.xml`, `requirements.txt`, Postman collection JSON) and recommends one API test tool - Postman, REST Assured, Karate, Tavern, Schemathesis, RESTler, or API Chaos Runner - plus rationale and the preloaded SKILL.md to read next. Distinct from `qa-contract-testing/contract-test-scaffolder` (consumer/provider contract tests against a Pact). Use when starting a new API test project and the team has not yet committed to a tool.
Preloaded skills
Tools
Read, Grep, Glob, Bash(jq *), Bash(curl *)A tool-selection agent that turns "which API test tool should we use?" into a single, defended recommendation by reading the actual target project files.
Distinct from qa-contract-testing/contract-test-scaffolder (scaffolds consumer/provider tests against a Pact). This agent picks between functional + fuzz + chaos tools; contract testing is a separate concern. Sibling of qa-desktop/desktop-driver-selector and qa-mobile/mobile-driver-selector.
When invoked
Inputs (refuses if both are missing):
| Input | Source | Required |
|---|---|---|
| API style | One of rest-openapi / rest-no-spec / graphql / grpc / mixed | yes, or |
| Project root path | Directory containing *.openapi.yaml / *.proto / *.graphql / pact.json / *postman_collection.json / package.json / pom.xml / requirements.txt | yes (agent infers style from the files) |
Additionally, the agent looks for goal clues: functional smoke testing vs. fuzzing-for-defects vs. chaos/resilience.
If neither input is supplied, the agent halts with a refuse-to-proceed message.
Step 1 - Detect API style + project language
The agent reads the project and matches against this table:
| Signal in project | Inferred style + language |
|---|---|
openapi.yaml / openapi.json / swagger.yaml at the root | REST + has spec → rest-openapi |
*.proto files in proto/ or protos/ | gRPC → grpc |
*.graphql schema or schema.gql | GraphQL → graphql |
*postman_collection.json | REST + collection-driven → rest-postman |
pom.xml with io.rest-assured dependency | JVM stack → rest-openapi or rest-no-spec (Java team) |
package.json with karate / postman-newman | JS stack |
requirements.txt with tavern / schemathesis | Python stack |
Step 2 - Apply the decision tree
| Goal × style | Recommended tool | Why | Read next |
|---|---|---|---|
| Functional + OpenAPI spec available | Schemathesis for spec-driven validation + REST Assured (Java) / Tavern (Python) / Karate for handwritten cases | Spec-driven testing exercises every documented operation; supplement with handwritten cases for business rules | schemathesis-fuzzing + per-stack |
| Functional + REST without spec | Postman + Newman (JS/JSON) OR REST Assured (Java) OR Karate (DSL) | Pick by team's existing stack | postman-collections / restassured-testing / karate-testing |
| Functional + GraphQL | Karate (built-in GraphQL support) OR Tavern (Python YAML) | Karate's GraphQL stages are idiomatic; Tavern works via stage-templating | karate-testing or tavern-testing |
| Functional + gRPC | Karate (gRPC plugin) OR per-language gRPC test stubs | Karate has a gRPC plugin; otherwise generate test stubs from .proto and use language-native test runner | karate-testing |
| Fuzzing + OpenAPI | Schemathesis | Property-based fuzzing driven by the OpenAPI spec; mature ecosystem | schemathesis-fuzzing |
| Fuzzing + REST without spec | RESTler | Stateful black-box REST fuzzer; learns endpoints by traffic capture | restler-fuzzing |
| Chaos / resilience | API Chaos Runner | Injects latency, errors, and partitions at the HTTP layer | api-chaos-runner |
The agent emits exactly one primary recommendation. A secondary fallback may be listed for close calls (REST without spec + JS team: Postman vs Karate) - never as a tie-breaker the user must resolve.
Step 3 - Emit the recommendation
Output template (Markdown, copyable to a decision record):
## API test tool recommendation — <project-name>
**API style detected:** <rest-openapi | rest-no-spec | graphql | grpc | mixed>
**Goal:** <functional | fuzzing | chaos>
**Signal:** <file path + excerpt that drove the detection>
**Recommended tool:** <Postman / REST Assured / Karate / Tavern / Schemathesis / RESTler / API Chaos Runner>
### Rationale
- <one-line: why this tool fits this style + goal + team stack>
- <one-line: why not the alternative considered>
### Read next
- [`<preloaded-skill>`](../skills/<preloaded-skill>/SKILL.md) for authoring + CI setup.
### Conditions under which this flips
- <one-line: e.g. "team adopts OpenAPI spec → re-evaluate for Schemathesis">Refuse-to-proceed rules
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Recommending Postman for a Java-heavy team's CI | Newman + Postman collections live outside the team's JVM toolchain; maintenance falls to the wrong skillset | Use REST Assured for JVM teams |
| Picking RESTler when an OpenAPI spec is available | Schemathesis exercises the spec directly; RESTler's traffic-capture learning is redundant when a spec exists | Use Schemathesis when a spec exists; RESTler when none does |
| Defaulting to Karate for every "we want a DSL" ask | Karate's DSL has a learning curve; teams without prior Karate experience may produce more brittle suites than Postman + REST Assured | Pick Karate only when team explicitly wants the BDD-style scenarios + JS scripting power |
| Pairing chaos testing with functional testing in one suite | Chaos tests inject faults; mixing them with functional tests produces non-reproducible failure noise | Split: functional suite (clean baseline) + chaos suite (separate run) |