Microservices REST API Test Automation Framework/Template

📄 Licensed for personal use only. Commercial/company use requires a paid license — see LICENSE.

A layered, multi-style framework for automating REST API tests across microservices — built on Cucumber 7 + TestNG + REST Assured, with Allure reporting, YAML-based per-environment configuration, and a HikariCP database layer for setup/verification.

---

Author

Salah Ghaleb — Software Development Engineer in Test (SDET)

📧 salahalsaif05@gmail.com

📧 salahalsaif.uni@gmail.com

🔗 LinkedIn

ISTQB®-certified:

• Certified Tester — Foundation Level (CTFL)
• Advanced Level — Test Automation Engineer (CT-TAE)
• Advanced Level — Test Analyst (CTAL-TA)

---

Project structure

microservices-rest-api-test-template/
├─ src/main/java/framework/
│  ├─ core/                         # Reusable, SUT-independent engine
│  │  ├─ api/                       #   HTTP layer: ApiCaller, ApiEndpoint, FluentResponse
│  │  │  ├─ payload/                #     ApiPayload marker + PayloadFactory
│  │  │  └─ reqspec/                #     RestAssuredSpecProvider, BaseUrlKey (base URL + Allure wiring)
│  │  ├─ config/
│  │  │  ├─ loader/                 #   ConfigLoader, @ConfigSource, PlaceholderResolver
│  │  │  └─ database/               #   DbConfig + HikariCP SqlConnectionPool
│  │  ├─ state/                     #   ScenarioContext, GlobalState, TypedContextKey, CoreContextKey
│  │  └─ utils/                     #   PojoValidator, PollingRetry, ParallelExecutor
│  └─ business/                     # SUT-specific implementations
│     ├─ config/
│     │  ├─ mappings/               #   Urls (typed base-URL config)
│     │  ├─ context/                #   ContextKey (SUT context keys)
│     │  └─ queries/                #   SystemServerSchemaKey + query helpers (e.g. UserQueries)
│     ├─ service/clients/           #   API clients, endpoint enums, SystemBaseUrlKey
│     │  └─ user/…                  #     User service: clients, DTOs (+ Mothers), UserServiceEndpoints
│     └─ api/flows/                 #   Multi-call flows (e.g. NewUserFlow) for preconditions
├─ src/main/resources/
│  ├─ config.yaml                   # Per-environment config: base URLs, DB, secrets via ${VAR:default}
│  └─ log4j2.xml
├─ src/test/java/api/tests/
│  ├─ BddTestRunner.java            # Cucumber⇄TestNG runner (features + glue roots)
│  ├─ bdd/step/definitions/
│  │  ├─ generic/                   #   Ready-made generic steps (base URL, payload, execute, assertions…)
│  │  ├─ wrapper/setup/             #   Example custom (wrapper) step definitions
│  │  └─ param/types/               #   ParameterTypes — custom Cucumber parameter types
│  └─ examples/                     # Example tests in four styles
│     ├─ zero/setup/                #   Zero-setup BDD        (no Java)
│     ├─ constants/setup/           #   Constants-setup BDD   (registered enums)
│     ├─ wrapper/setup/             #   Wrapper-setup BDD      (custom domain steps)
│     └─ custom/script/setup/       #   Plain TestNG scripts  (full code)
└─ src/test/resources/
   ├─ suites/                       # TestNG suites: zero, constants, wrapper, customScript
   └─ testNG.xml

Every package ships an in-repo manual/guide — see Documentation.

---

Features

• Multi-microservice by design. Clients are grouped per service, and each service maps to its own base-URL key — so a single suite can exercise many backends, each with its own host, endpoints, and config.

• Environment-aware configuration. One config.yaml holds per-environment values (base URLs, database, secrets) with ${VAR:default} placeholders resolved from environment variables — so secrets stay out of the repo and you switch environment with a single variable. Typed sections bind to Java records via @ConfigSource; ad-hoc values are read by path. → Config loader manual

• Four authoring styles, one framework. The same test can be written in any of these — a deliberate gradient from no-code to full-code that lets product owners, manual QAs, and engineers collaborate in one suite:

  • a. Zero-setup — pure Gherkin, no Java (similar in concept to the Karate DSL, but built in-house on Cucumber + REST Assured).
  • b. Constants-setup — URLs/endpoints/payloads registered as enums.
  • c. Wrapper — custom domain-readable Gherkin steps over Java.
  • d. Custom TestNG script — plain Java tests, full control.

  → About the examples

• Reusable client / flow / DTO layers. Typed API clients, request/response DTOs that use the object-mother pattern with sensible defaults, and flows that compose multiple client calls into reusable preconditions. → Clients · Flows · DTOs

• Fluent response wrapper. FluentResponse gives every client call an assert-then-extract flow — assert the status/body first, then deserialize into a typed object. → Clients manual

• A rich generic step library. Build and fire any request and assert on status, body, and headers straight from Gherkin — no Java required — including placeholder matchers, type checks, value storage/reuse, and polling with retry.

• Typed, scenario-aware state. ScenarioContext (per scenario, injected via Cucumber PicoContainer) and GlobalState (whole run) share data between steps through type-safe keys. For more info, see the wrapper setup guide.

• Allure reporting out of the box. Every request a client makes is auto-attached, and steps render as readable Given/When/Then phases.

• Parallel execution. ParallelExecutor runs an operation on many threads at once (race-condition / contention testing) and surfaces every failure. For more info, see the custom script setup guide.

• Polling with retry. PollingRetry handles eventually-consistent endpoints without brittle sleeps. For more info, see the custom script setup guide.

• Deep object validation. PojoValidator does deep, recursive response-object comparison with ignorable fields. For more info, see the request/response DTO manual.

• Database access & validation. Pooled MySQL / PostgreSQL access via HikariCP, scaling across multiple environments, multiple servers per environment, and multiple databases (schemas) per server — each addressed by a single typed key. Query the database to verify against the source of truth or extract values (ids, orderIds…) for requests. → Database manual

Not sure where to start? Begin with About the examples — it walks through the four test styles and links out to everything else you'll need. Every guide and manual is cross-linked, so you can just start reading, and whenever you hit something you want to understand, click it and it'll take you straight to that file or topic.

---

Documentation

Area	Guide / Manual
Choosing a test style	aboutExamples.md
Zero setup (BDD, no code)	Guide · Steps manual
Constants setup (registered enums)	Guide · Steps manual
Wrapper setup (custom steps)	Guide
Custom TestNG scripts	Guide
Configuration	Config loader manual
Database (MySQL / PostgreSQL)	Database manual
API clients	Clients manual
Endpoints	Endpoints manual
Request/response DTOs	DTO manual
Flows	Flows manual

The example tests run against the public Platzi Fake Store API — https://api.escuelajs.co/docs#.

---

Running tests & reports

The quickest start is mvn test. For how to group tests into suites, filter by tags/groups, run from the IDE, and generate the Allure report, see the running & grouping tests guide.