Skip to content

plan.md

Latest commit

 

History

History
395 lines (282 loc) · 11.5 KB

plan.md

File metadata and controls

395 lines (282 loc) · 11.5 KB
Raw

Rest Assured Java API Automation Learning Framework Plan

Project Intent

This repository is a standalone learning project for API automation with Java and Rest Assured. It should teach concepts from first principles, then evolve into a mature framework through small, inspectable module checkpoints.

The learner should be able to understand the final framework by walking the Git history from Module 01 to Module 20. No framework layer should appear before the module has taught the problem that layer solves.

Fixed Decisions

Area Decision
Language Java 21 LTS
Build tool Maven
API automation library Rest Assured
Test runner TestNG
JUnit scope documentation-only comparison appendix
Primary framework/capstone API Restful Booker
Early simple APIs Zippopotam.us or JSONPlaceholder when useful
JSON mapping teach Gson and Jackson, use Jackson in final framework
Assertions Rest Assured/Hamcrest, TestNG, AssertJ
Test data JSON, CSV, Excel with Apache POI
Schema validation Rest Assured JSON schema validator
Mocking/stubbing focused WireMock module
Logging Log4j2 and Rest Assured filters
Reporting Allure and Extent
CI/CD GitHub Actions executable workflow, Jenkins documentation
BDD scope documentation-only API BDD appendix
Java package namespace com.learning.api

Learning Standards

This project is standalone. Do not assume the learner remembers concepts from the Selenium or Python API repositories.

Each module should explain the concepts it introduces:

  • Java syntax and OOP ideas used by the code.
  • HTTP/API concepts used by the test.
  • Rest Assured syntax and object model.
  • TestNG lifecycle, grouping, parameters, listeners, or context when used.
  • Framework design decisions and boundaries.

Code comments should be intentionally rich because this is a learning project. Production-style restraint is less important than making syntax and framework intent clear for the learner.

Documentation Standard

Each module should use the Selenium framework documentation style:

  • 00-module-overview.md
  • focused concept guides such as 01-topic-name.md
  • exercises.md with hints and expected outcomes
  • 99-interview-review.md when the module introduces interview-relevant concepts

Module docs should include:

  • what the module builds.
  • why the module exists now.
  • learning flow diagrams when useful.
  • concepts covered.
  • files introduced or changed.
  • code walkthroughs with accurate paths.
  • what is intentionally deferred.
  • quality gate commands.
  • readiness standard before the next module.

Git Strategy

Invariants

  • main is always a completed checkpoint.
  • each module branch starts from main.
  • work happens on the active module branch.
  • a completed module branch is not reused for later work.
  • modules are linear.
  • future-module implementation is not added early.
  • each completed module gets a tag named module-XX-complete.

Branch Names

Use module-XX-name, for example:

  • module-01-java-api-foundation
  • module-07-crud-operations-restful-booker
  • module-18-allure-extent-reporting

Commit Style

Use small educational checkpoints:

module-04: add BDD request anatomy guide
module-04: add first Rest Assured GET examples
module-04: add exercises and interview review
module-04: mark module complete

The initial scaffold commit is:

chore: scaffold Rest Assured learning framework

Module Completion Rule

Before marking any module complete, perform a deep final review of that module's implementation, tests, documentation, examples, comments, and exercises.

Confirm the module does not skim over:

  • Java syntax introduced in that module.
  • Rest Assured syntax and request/response flow.
  • TestNG behavior introduced in that module.
  • framework boundaries and design decisions.
  • learner exercises and expected outcomes.

If gaps are found before the module checkpoint, repair them before creating the final module-complete checkpoint.

Keep Git history linear and educational. Repairs found during the module should be folded into the module's natural progression before completion, not pushed into a later branch or left as obvious afterthought work.

Only tag module-XX-complete after the deep review passes.

Source Organization Direction

Do not create the final source tree too early. The project should grow as the curriculum teaches each layer.

Final direction:

api-testing-rest-assured-framework/
|-- README.md
|-- plan.md
|-- CLAUDE.md
|-- AGENTS.md
|-- pom.xml
|-- testng.xml
|-- docs/
|   `-- module-XX-name/
|-- src/
|   |-- main/java/com/learning/api/
|   |   |-- framework/
|   |   |-- models/
|   |   |-- payloads/
|   |   |-- clients/
|   |   |-- config/
|   |   `-- utils/
|   `-- test/
|       |-- java/com/learning/api/tests/
|       |   |-- learning/
|       |   |-- restfulbooker/
|       |   |-- base/
|       |   |-- dataproviders/
|       |   |-- listeners/
|       |   `-- wiremock/
|       `-- resources/
|           |-- config/
|           |-- schemas/
|           `-- testdata/
|-- test-data/
|-- reports/
`-- .github/workflows/

Rules:

  • early learning-only Java examples live under src/main/java/com/learning/api/examples/moduleXX/.
  • raw Rest Assured concept tests live under src/test/java/com/learning/api/tests/learning/.
  • reusable framework code lives under src/main/java/com/learning/api/framework/ and related responsibility packages.
  • Restful Booker framework tests live under src/test/java/com/learning/api/tests/restfulbooker/.
  • do not duplicate framework snapshots module by module.
  • once real framework classes exist, evolve them in place and document the changes in that module.

Learning-only Java files use _NN_ prefixes as a reading-order aid. The numbering is local to the folder that contains the learning files, so each module example folder or learning-test folder starts again from _01_. Do not continue numbering from one folder into the next. Mature framework classes such as config readers, request spec factories, API clients, service layers, payload builders, listeners, reports, and utilities do not use _NN_ prefixes.

External Reference Repositories

These repositories are references only. Do not vendor them, copy them wholesale, or treat their source as this project's source code.

Rest Assured Concepts Reference

  • URL: https://github.com/PramodDutta/ATB10xAPIAutomationPrograms
  • Use for:
    • BDD vs non-BDD Rest Assured style.
    • GET, POST, PUT, PATCH, DELETE examples.
    • TestNG examples.
    • assertions.
    • payload management with strings, maps, POJOs, Gson, and Jackson.

Rest Assured Framework Reference

  • URL: https://github.com/PramodDutta/APIAutomationFramworkATB10x
  • Use for:
    • BaseTest style setup.
    • RequestSpecBuilder.
    • endpoint constants.
    • payload manager ideas.
    • POJO response mapping.
    • AssertJ/TestNG assertion helpers.
    • Restful Booker CRUD and integration flows.

Local Framework Style References

  • Selenium Java framework:
    • primary reference for module depth, documentation structure, comments, branch checkpoints, and enterprise framework progression.
  • Python API framework:
    • reference for API testing topic coverage and API curriculum thinking.

20-Module Curriculum

Module 01 - Java API Automation Foundation

Purpose:

  • Introduce Java syntax and OOP ideas needed before Rest Assured appears.
  • Use API-shaped examples such as request data, response summaries, status codes, and test case descriptions.

Implementation:

  • Maven and source code may be introduced in this module's implementation pass, not in the planning scaffold.
  • No Rest Assured dependency yet.

Module 02 - HTTP, REST, JSON, and API Testing Basics

Purpose:

  • Teach HTTP methods, URLs, headers, status codes, request bodies, response bodies, JSON objects/arrays, and API test thinking.

Implementation:

  • Concept-first docs.
  • Small Java examples may model HTTP concepts without real network calls.

Module 03 - Maven, TestNG, and Rest Assured Setup

Purpose:

  • Add the real Java test project setup.
  • Introduce Maven dependency management and TestNG test discovery.
  • Add Rest Assured dependency for the first time.

Module 04 - Rest Assured BDD Style Request Anatomy

Purpose:

  • Teach given(), when(), then() as a fluent API.
  • Explain baseUri, basePath, query parameters, headers, logging, and status validation.

Module 05 - Rest Assured Non-BDD Style and Core Objects

Purpose:

  • Teach RequestSpecification, Response, and ValidatableResponse.
  • Compare fluent BDD style with object-oriented step-by-step style.

Module 06 - Response Validation, Assertions, and Extraction

Purpose:

  • Teach Hamcrest body checks, TestNG assertions, AssertJ assertions, JSONPath, extraction, headers, content type, and response time checks.

Module 07 - CRUD Operations with Restful Booker

Purpose:

  • Move to the primary framework API.
  • Cover create, read, update, partial update, delete, positive and negative flows.

Module 08 - Payload Construction, POJOs, Gson, and Jackson

Purpose:

  • Compare raw string payloads, maps, POJOs, Gson, and Jackson.
  • Standardize on Jackson for future framework modules.

Module 09 - TestNG for API Automation

Purpose:

  • Teach TestNG annotations, priorities, groups, parameters, dependencies, data providers, suites, and API test lifecycle.

Module 10 - Authentication, Tokens, Cookies, and Stateful Flows

Purpose:

  • Implement Restful Booker token creation.
  • Teach token extraction, cookie auth, protected operations, and stateful API flow risks.
  • Document Basic, Bearer, API key, and OAuth2 concepts.

Module 11 - Framework Foundation: Config, Base API Test, Request Specs

Purpose:

  • Introduce reusable configuration, BaseApiTest, common request specs, and environment handling.

Module 12 - Endpoint Constants and API Client/Service Layer

Purpose:

  • Move endpoint paths and repeated request logic out of tests.
  • Introduce API client/service boundaries.

Module 13 - Domain POJOs, Payload Builders, and Jackson Mapping

Purpose:

  • Mature request and response modeling.
  • Introduce payload builders and domain mapping boundaries.

Module 14 - Data-Driven Testing with JSON, CSV, and Excel

Purpose:

  • Teach external test data strategy.
  • Implement JSON, CSV, and Excel readers with TestNG data providers.

Module 15 - Schema Validation and Contract Boundaries

Purpose:

  • Add JSON schema validation.
  • Explain contract testing boundaries and what schema tests can and cannot prove.

Module 16 - Logging, Rest Assured Filters, and Safe Diagnostics

Purpose:

  • Add Log4j2 and Rest Assured filters.
  • Teach request/response logging, correlation, and secret redaction.

Module 17 - WireMock and Controlled Negative/Error Testing

Purpose:

  • Add controlled stubs for error scenarios that public APIs cannot reliably provide.
  • Explain service virtualization boundaries.

Module 18 - Allure and Extent Reporting

Purpose:

  • Add Allure annotations/results and Extent reporting.
  • Attach useful API diagnostics without leaking secrets.

Module 19 - Parallel Execution, Stability, GitHub Actions, and Jenkins Docs

Purpose:

  • Teach API test isolation for parallel runs.
  • Add executable GitHub Actions workflow.
  • Add Jenkins learning documentation.

Module 20 - Capstone, Portfolio Packaging, JUnit Appendix, and BDD Appendix

Purpose:

  • Package the complete framework for portfolio presentation.
  • Add final architecture review, runbook, interview talking points, and docs-only JUnit/BDD appendices.