Playwright API Automation Testing (Starter Project)

Using this as a template? Update the CI badge URL above and the clone URL in step 1 below to point at your own fork/repo — both currently point at the upstream template repo.

API Automation Testing Starter Project that utilize Playwright Framework.

Requires Node 20+. An .nvmrc is provided — run nvm use (or equivalent) before installing.

Getting started

To use this starter project for API testing, please follow the installation guide provided below.

1. Clone this repository

Clone this repository on your workspace with the following command:

git clone https://github.com/Whyu9-9/Playwright-API-Automation-Starter.git

2. Run npm install

Install the required npm package that needed to run the tools with the following command:

npm install

3. Setup your .env file

You will need to configure your .env file before running your tests. Copy the .env.example file, rename it, and fill in all the env variables. Contact your software engineer team to provide what you need.

A global setup (global-setup.ts) checks MAIN_API_URL, API_LOGIN_URL, PASSWORD, and either USERNAME or EMAIL before any test runs, and fails fast with a clear message if any are missing — instead of an opaque failure mid-test.

Architecture

• Fixtures (fixtures/api-fixtures.ts): a custom Playwright test that injects header, randomizer, and fileHandler — write test("...", async ({ request, header }) => { ... }) instead of manually new-ing helper classes in every spec.
• Response handling (helpers/response-handler.ts): expectStatus(response, 200) parses the JSON body and asserts the status in one call, with the actual body in the failure message.
• Contract checks: example specs validate the response shape with a zod schema (z.object({...}).parse(body)), not just one field — catches API shape drift, not just message-text regressions.
• Typed helpers: helpers/*.ts use real types (AuthType, FileKind, etc.) instead of any, so your editor gives real autocomplete when writing new specs.
• helpers/randomizer.ts generates unique test data from a local word list — no network dependency, so tests don't flake when a third-party API is slow or down.

Example modules

tests/example/** cover one pattern per HTTP method, each with a positive and negative scene:

• example (multipart) — file upload via POST
• example-unique-data — POST with a uniqueness constraint
• example-get — paginated GET with query params
• example-update — PUT
• example-delete — DELETE

These hit a placeholder process.env.insert_custom_env_url — swap it for your own .env variable before running them against a real API. They're patterns to copy from via npm run generate-test, not tests meant to pass out of the box (see TROUBLESHOOTING.md).

Available command to run

This is the list of command that are available for you to run on this project. Some of this command including the usage of tools inside this project

    # to copy necessary file before running npm run post-test command
    npm run pre-serve

   # to generate allure report
    npm run post-test

   # to start a web server on port 8081 that will show allure report
    npm run allure:serve

    # to run all available test cases on all available browser driver
    npm run test

    # to run all available test cases on single browser driver
    npm run test-single

    # to open Playwright's UI mode - visually step through requests/responses, great for debugging
    npm run test:ui

    #to run one specific test case on single browser driver (usually we use this for debugging API testing code to see if the code is already running well or not)
    #example: npx playwright test ecommerce/store-transaction/negative/scene2 --project=chromium
    npx playwright test {module}/{feature_name}/{negative/positive}/{scene+order} --project=chromium

    #to auto-generate API Testing data (run this before running auto-generate API testing code)
    npm run generate-data

    #to auto-generate API Testing code
    npm run generate-test

    # to lint the project with ESLint
    npm run lint

Documentation

Here is a list of documentation for easing your automation testing development

1. Playwright API Testing Documentation
2. Allure Playwright Documentation
3. Generate Template File Documentation
4. Typescript Documentation
5. Mimetype Documentation

Stuck on setup, generator quirks, or a CI/allure mismatch? Check TROUBLESHOOTING.md first.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to get set up, add a new test module via the generator, and what to check before opening a PR.

Authors and acknowledgment

This repository is created and maintained by: