Skip to content

Commit 30bd4ba

Browse files
aslavchevaslavchev
committed
docs: add ADR-001 and framework approach documentation
ADR-001 records the Playwright + TypeScript decision over REST Assured. APPROACH.md documents how Ivan Davidov's article series was adapted for GitHub API testing, including what was customized.
1 parent 4e5a5c6 commit 30bd4ba

4 files changed

Lines changed: 128 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,7 @@ node_modules/
77
/playwright/.cache/
88
/playwright/.auth/
99
env/.env.*
10-
!env/.env.example
10+
!env/.env.example
11+
12+
# Internal
13+
docs/review-log.md

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,9 @@ tests/
6262
issues.api.spec.ts # CRUD /repos/{owner}/{repo}/issues
6363
labels.api.spec.ts # CRUD /repos/{owner}/{repo}/labels
6464
search.api.spec.ts # GET /search/repositories
65+
docs/
66+
adr/ADR-001-playwright-typescript.md # Why Playwright + TypeScript
67+
APPROACH.md # How the framework was built (credits Ivan Davidov)
6568
.github/
6669
workflows/playwright-ci.yml
6770
actions/

‎docs/APPROACH.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Framework Approach
2+
3+
This framework was built by following [Ivan Davidov's 10-article Playwright series](https://idavidov.eu/roadmap), adapting his Conduit demo app approach to target GitHub's REST API.
4+
5+
## Why follow a structured series?
6+
7+
Building a framework from scratch without a proven reference leads to ad-hoc decisions. Ivan's series provides a battle-tested architecture: fixtures for dependency injection, Zod for schema validation, composite actions for CI, and a clear separation between request logic and test logic. Following it ensured every architectural choice has documented rationale behind it.
8+
9+
## What was followed as-is
10+
11+
| Article | Topic | Applied |
12+
|---------|-------|---------|
13+
| 1 | Initial Playwright setup | Yes — same scaffolding |
14+
| 2 | User snippets (VS Code) | Yes — IDE config |
15+
| 3 | Environment variables with dotenv | Yes — multi-environment support |
16+
| 4 | Design pattern (POM with getters + methods) | Partially — no UI pages, but same fixture pattern |
17+
| 5 | POM as fixture + auth user session | Partially — fixtures yes, storageState not needed (API-only) |
18+
| 6 | UI tests | No — API-only, no UI target |
19+
| 7 | API fixtures (plain-function, schemas, types-guards, fixture) | Yes — same 4-file architecture |
20+
| 8 | API tests | Yes — 5 suites covering auth, repos, search, issues, labels |
21+
| 9 | CI/CD with GitHub Actions | Yes — same composite actions, blob reports, GitHub Pages |
22+
| 10 | ESLint + Prettier + Husky | Yes — same toolchain |
23+
24+
## What was customized
25+
26+
**API-only, no UI tests.** Ivan's series targets a Conduit demo app with both UI and API. This framework targets GitHub's REST API exclusively. No page objects, no storageState, no browser install in CI.
27+
28+
**Lint gate before tests.** Ivan's pipeline runs smoke tests first. This pipeline adds an ESLint check as the first job — if code doesn't pass lint, tests don't run. Cheaper feedback before expensive test execution.
29+
30+
**Always upload blob reports.** Ivan's pipeline uploads reports only on failure. This pipeline always uploads them because the merge and deploy jobs need blobs from every run to produce the live GitHub Pages report.
31+
32+
**Docker for local execution.** Not covered in Ivan's series. Added a Dockerfile so tests can run in a consistent environment locally without installing Node or Playwright dependencies on the host machine.
33+
34+
**6 Zod schemas instead of 3.** Ivan validates User, Error, and Article responses. This framework validates User, Repo, Issue, Label, SearchResult, and Error — matching the GitHub API endpoint groups under test (users, repos, issues, labels, search).
35+
36+
**Token auth instead of login flow.** Ivan's auth setup calls POST /api/users/login to get a token at runtime, then saves a browser session via storageState. This framework uses a pre-generated GitHub Personal Access Token from the .env file. No login call, no browser session needed.
37+
38+
## Articles referenced
39+
40+
1. [Initial Setup](https://idavidov.eu/building-playwright-framework-step-by-step-initial-setup) — Setting the foundation for a professional framework
41+
2. [Create User Snippets](https://idavidov.eu/building-playwright-framework-step-by-step-create-user-snippets) — Boosting productivity with snippets in IDEs
42+
3. [Setup Environment Variables](https://idavidov.eu/building-playwright-framework-step-by-step-setup-environment-variables) — Managing sensitive data and configurations securely
43+
4. [Setup Design Pattern](https://idavidov.eu/building-playwright-framework-step-by-step-setup-design-pattern) — Structuring your project for maintainability
44+
5. [Implementing POM as Fixture and Auth User Session](https://idavidov.eu/building-playwright-framework-step-by-step-implementing-pom-as-fixture-and-auth-user-session) — Advanced Page Object Model usage and handling state
45+
6. [Implementing UI Tests](https://idavidov.eu/building-playwright-framework-step-by-step-implementing-ui-tests) — Writing robust end-to-end UI scenarios
46+
7. [Implementing API Fixtures](https://idavidov.eu/building-playwright-framework-step-by-step-implementing-api-fixtures) — Setting up reusable API components
47+
8. [Implementing API Tests](https://idavidov.eu/building-playwright-framework-step-by-step-implementing-api-tests) — Validating backend logic directly
48+
9. [Implementing CI/CD](https://idavidov.eu/building-playwright-framework-step-by-step-implementing-cicd) — Automating execution with continuous integration pipelines
49+
10. [ESLint and Husky in Playwright](https://idavidov.eu/never-commit-broken-code-again-a-guide-to-eslint-and-husky-in-playwright) — Enforcing code quality automatically

‎docs/adr/ADR-001-playwright-typescript.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# ADR-001: Playwright + TypeScript for GitHub API Testing
2+
3+
**Status:** Accepted | **Date:** 2026-03-09
4+
5+
---
6+
7+
## Context and Problem Statement
8+
9+
Need an automated API test framework for GitHub's REST API. The framework must handle token-based authentication, JSON response validation, and CRUD test coverage across multiple endpoint groups (users, repos, issues, labels, search). It should support CI execution with public reporting and be extensible to UI testing if a suitable target is added later.
10+
11+
---
12+
13+
## Decision Drivers
14+
15+
- No additional HTTP libraries — framework must handle API calls natively
16+
- Compile-time safety — catch contract violations before tests run, not during
17+
- Extensible to UI testing without migrating to a second tool
18+
- Industry relevance — Playwright appears in job descriptions more frequently than REST Assured for modern QA roles
19+
20+
---
21+
22+
## Decision
23+
24+
Use Playwright with TypeScript for API testing against GitHub's REST API.
25+
26+
---
27+
28+
## Considered Options
29+
30+
| Option | Pros | Cons | Verdict |
31+
| ------ | ---- | ---- | ------- |
32+
| **Playwright + TypeScript** | Built-in API client, fixtures for DI, type safety, modern async/await | Async patterns require learning, less common in enterprise Java environments | ✅ Chosen |
33+
| **REST Assured + Java** | Familiar from a prior project, strong API validation DSL | Java-only, no built-in UI testing path, already have a project with it | ❌ Already demonstrated |
34+
35+
---
36+
37+
## Key Decision Factors
38+
39+
**Built-in API support without extra dependencies.** Playwright provides `APIRequestContext` out of the box. No need for Axios, node-fetch, or supertest. The same framework handles both API and UI testing, so adding UI tests later requires zero additional tooling.
40+
41+
**Fixtures as dependency injection.** Playwright's fixture system injects the API request context into every test automatically. Tests declare what they need (`async ({ apiRequest }) =>`), and the framework provides it. This eliminates manual setup in every test file and mirrors how modern backend frameworks handle DI.
42+
43+
**TypeScript + Zod for two layers of validation.** TypeScript catches structural errors at compile time (wrong property name, missing field). Zod validates the actual API response shape at runtime (field exists, correct type, not null when expected). Without TypeScript, Zod still works but you lose IDE autocomplete and compile-time checks.
44+
45+
---
46+
47+
## Consequences
48+
49+
**Positive:**
50+
- Zod schemas serve as living API contract documentation
51+
- Fixtures eliminate boilerplate setup in every test file
52+
- Same framework supports future UI test expansion without migration
53+
- Built-in HTML reporting with GitHub Pages deployment
54+
55+
**Trade-offs:**
56+
- TypeScript's async/await and type system require learning investment (mitigated by structured article series as a guide)
57+
- Playwright is less common in enterprise Java environments (acceptable for an API-focused framework)
58+
59+
---
60+
61+
## Confirmation
62+
63+
- All API tests import `test` from the custom fixture (`api-request-fixture.ts`), not from `@playwright/test` directly. `expect` is still imported from Playwright.
64+
- Every test suite validates response shape with a Zod schema before asserting values
65+
- `tsconfig.json` has `strict: true` enabled
66+
- No `any` types in the codebase (enforced by ESLint rule `@typescript-eslint/no-explicit-any`)
67+
68+
---
69+
70+
**References:** [Playwright API Testing Docs](https://playwright.dev/docs/api-testing) | [Zod Documentation](https://zod.dev/) | [Ivan Davidov's Playwright Series](https://idavidov.eu/roadmap)
71+
72+
**Last Updated:** 2026-03-21

0 commit comments

Comments
 (0)