E2E Test Suite

End-to-end test suite for the RestCountries API using Playwright, covering API contract validation and UI testing across multiple viewport sizes.

---

Stack

Tool	Version	Role
Playwright	^1.43	Browser automation + API testing
JavaScript	ES2020	No transpilation needed
Chromium	latest	Primary browser for UI tests
Firefox	latest	Cross-browser validation

---

Structure

tests-e2e/
├── tests/
│   ├── helpers/
│   │   └── countries.js          # Shared constants and required field list
│   ├── api/
│   │   └── countries.spec.js     # API tests (18 scenarios)
│   └── ui/
│       └── website.spec.js       # UI tests (homepage, docs, responsiveness)
├── .github/
│   └── workflows/
│       └── e2e-tests.yml         # CI/CD — API and UI jobs run in parallel
├── playwright.config.js          # Three projects: API and UI (Chromium, Firefox)
└── package.json

---

Setup

npm install
npx playwright install chromium firefox

Downloads the browsers used for UI tests. Only needs to run once.

---

How to run

npm test               # all tests (API + UI on both browsers)
npm run test:api       # API tests only
npm run test:ui        # UI tests on Chromium + Firefox
npm run test:ui:chrome # UI tests on Chromium only
npm run test:ui:firefox # UI tests on Firefox only
npm run test:headed    # UI tests with visible Chromium browser
npm run test:debug     # step-by-step inspector
npm run report         # open HTML report after a run

---

Scenarios covered

API (tests/api/countries.spec.js) — 18 tests

Status & Availability

• ✅ Status 200 for a valid country name
• ✅ Content-Type application/json
• ✅ Response time under 5 seconds

Schema Validation

• ✅ All required fields present: name, cca2, cca3, capital, region, population, languages, currencies, flags
• ✅ name object has common and official string fields
• ✅ flags object has valid png and svg URLs
• ✅ capital is a non-empty array
• ✅ population is a positive number

Data Integrity

• ✅ Brazil is in the Americas region
• ✅ Germany is in the Europe region
• ✅ Brazil cca3 code is BRA
• ✅ Lookup by alpha code returns matching country
• ✅ latlng contains exactly two valid coordinates (latitude −90/90, longitude −180/180)

Search Endpoints

• ✅ Search by name returns an array
• ✅ Search by region returns multiple countries
• ✅ Search by language (portuguese) returns multiple countries
• ✅ Search by alpha code returns exactly one country
• ✅ Field filter (?fields=name,capital,population) returns only requested fields and excludes others

Error Handling

• ✅ Status 404 for a non-existent country name
• ✅ Status 404 for an invalid alpha code
• ✅ Error body contains a message field
• ✅ Status 400 when calling /all without fields parameter

UI (tests/ui/website.spec.js) — Chromium + Firefox

Homepage

• ✅ Correct page title
• ✅ Main heading visible
• ✅ Navigation links present
• ✅ No JavaScript errors on load

Docs

• ✅ Docs page loads and URL matches /#api
• ✅ Page references v3 API version

Responsiveness

• ✅ Mobile (375×812)
• ✅ Tablet (768×1024)
• ✅ Desktop (1440×900)

All UI scenarios run twice — once on Chromium and once on Firefox.

---

Technical decisions

Playwright for both API and UI testing — Playwright's request context handles HTTP calls natively, with the same assertion library used for browser tests. This keeps the entire E2E layer in one tool.

Three separate projects in playwright.config.js — API, UI — Chromium and UI — Firefox are defined as distinct Playwright projects with separate testMatch patterns. This allows running each independently, and maps to two separate CI jobs (API and UI) that run in parallel. The UI job runs both browsers in the same job.

retries: 1 in config — E2E tests against real external services are inherently flaky due to network variability. One automatic retry reduces false negatives without masking real failures — a second consecutive failure is almost certainly a real bug.

screenshot, video and trace on failure — all three are configured to retain-on-failure. Screenshots and videos are uploaded as CI artifacts, making it possible to debug UI failures without re-running locally.

Field filter test — the test for ?fields=name,capital,population explicitly asserts that flags and region are undefined in the response. This verifies that the API's projection feature works correctly in both directions — including what it returns and what it excludes.

/all without fields as an error test — the RestCountries API requires ?fields=... when calling /all, returning 400 otherwise. This is documented as an intentional API design decision and tested explicitly as an error handling scenario.

Language search uses full name instead of ISO code — the initial implementation used lang/pt (ISO 639-1 code), which returned an unexpected response. Testing revealed the endpoint expects the full language name (lang/portuguese). The test was corrected and the finding documented.

for...of loop for multi-location tests — instead of duplicating viewport tests, a for...of loop over an array of [label, width, height] tuples generates one test per viewport. Same pattern used in the responsiveness suite.

---

CI/CD

The GitHub Actions workflow runs automatically on every push to main or develop and on pull requests to main. API and UI jobs run in parallel. The UI job installs both Chromium and Firefox and runs all UI scenarios on both browsers. The Playwright HTML report and screenshots are uploaded as artifacts after each run and retained for 15 days.