Playwright API tests: interfaces, ApiHelper and a fixture

// Crud operation
import { test, expect } from '@playwright/test';
import { logger } from '@utils/logger';

interface BookingPayload {
    firstname: string;
    lastname: string;
    totalprice: number;
    depositpaid: boolean;
    bookingdates: BookingDates;
    additionalneeds: string;
}

interface BookingDates {
    checkin: string;
    checkout: string;
}

interface AuthTokenResponse {
    token: string;
}

interface CreateBookingResponse {
    bookingid: number;
    booking: BookingPayload;
}

interface BookingFlowState {
    token?: string;
    bookingId?: number;
}

test.describe.serial('Restful Booker CRUD API', () => {

    const headers = {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
    };

    const payload : BookingPayload = {
        firstname: 'Pramod',
        lastname: 'Dutta',
        totalprice: 111,
        depositpaid: true,
        bookingdates: {
            checkin: '2018-01-01',
            checkout: '2019-01-01',
        },
        additionalneeds: 'Breakfast',
    };

    const bookingFlowState: BookingFlowState = {};

     test('TC#1 @p0 - Create token', async ({ request }) => {
        await test.step('Create token', async () => {
            const responseData = await request.post('/auth', {
                headers,
                data: {
                    username: process.env.BOOKER_USERNAME,
                    password: process.env.BOOKER_PASSWORD,
                },
            });


        expect(responseData.status()).toBe(200);
        const data = await responseData.json() as AuthTokenResponse;
        expect(data.token).toBeTruthy();
        bookingFlowState.token = data.token;

        });
    });


     test('TC#2 @p0 - Create booking', async ({ request }) => {

        await test.step('Create booking', async () => {
            const responseData = await request.post('/booking', {
                headers,
                data: payload,
            });

            expect(responseData.status()).toBe(200);
            const data = await responseData.json() as CreateBookingResponse;
            expect(data.bookingid).toBeTruthy();
            expect(data.booking.firstname).toBe(payload.firstname);
            expect(data.booking.lastname).toBe(payload.lastname);

            bookingFlowState.bookingId = data.bookingid;
            logger.info(`Created booking id for CRUD flow: ${bookingFlowState.bookingId}`);
        });
    });

    test('TC#3 @p0 - Update booking', async ({ request }) => {


        await test.step('Update booking', async () => {

            const token = bookingFlowState.token;
            const bookingId = bookingFlowState.bookingId;
            if (!token || !bookingId) {
                throw new Error('Create token and create booking tests must pass before update booking.');
            }

             const responseData = await request.put(`/booking/${bookingId}`, {
                headers: {
                    ...headers,
                    Cookie:`token=${token}`
                },
                data: payload,
            });

            expect(responseData.status()).toBe(200);
            const data = await responseData.json() as BookingPayload;
            expect(data.firstname).toBe(payload.firstname);
            expect(data.lastname).toBe(payload.lastname);

            logger.info(`Updated booking id ${bookingId}: ${data.firstname} ${data.lastname}`);

        });
   });

});

/**
 * ## API Helper Ts
 * - APIs Helper is a **simple type of a class**
 * - which can help you to make a different type of HTTP
 * - GET, POST, PATCH,PUT, DELETE
 * - Generic Fn, which can used by any TestCase
 */

import { Page, APIRequestContext, APIResponse } from '@playwright/test';

export type ApiContext = Page | APIRequestContext;
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';

// Request Modifiction
export interface ApiRequestOptions {
    url: string;
    method: HttpMethod;
    headers?: Record<string, string>;
    data?: unknown; // payload, body
    params?: Record<string, string>;
    timeout?: number;
}

export interface RetryOptions {
    condition: (response: APIResponse) => Promise<boolean> | boolean
    pollingInterval?: number;
    retryCount?: number;
}


export class ApiHelper {
    private context: ApiContext;

    constructor(context: ApiContext) {
        this.context = context;
    }


    private getRequest(): APIRequestContext {
        if ('request' in this.context) {
            return this.context.request;
        }
        return this.context;
    }

    // example1 -  https://example.com
    // example2 -  https://example.com/ param :  param1=abc&param2=xyz return-.  https://example.com/param1=abc&param2=xyz
    // exmaple3 - https://example.com/, params :  /student/1 -> https://example.com/student/1
    // builturl(example1)
    private buildUrl(url: string, params?: Record<string, string>): string {
        if (!params) return url;
        const searchParams = new URLSearchParams(params);
        return `${url}?${searchParams.toString()}`;
    }

     /**
    * Perform an HTTP API request
    */
    async callApi(options: ApiRequestOptions): Promise<APIResponse> {
        const { url, method, headers, data, params, timeout } = options;
        const request = this.getRequest();
        const fullUrl = this.buildUrl(url, params);

        switch (method) {
            case 'GET':
                return await request.get(fullUrl, { headers, timeout });
            case 'POST':
                return await request.post(fullUrl, { headers, data, timeout });
            case 'PUT':
                return await request.put(fullUrl, { headers, data, timeout });
            case 'DELETE':
                return await request.delete(fullUrl, { headers, timeout });
            case 'PATCH':
                return await request.patch(fullUrl, { headers, data, timeout });
            default:
                // `method` is `never` here: the switch above is exhaustive over HttpMethod.
                throw new Error(`Unsupported HTTP method: ${String(method)}`);
        }
    }

    /**
     * Call API with retry logic
     */

    async callApiWithRetry(
        options: ApiRequestOptions,
        retryOptions: RetryOptions,
    ): Promise<APIResponse> {
        const { condition, pollingInterval = 5000, retryCount = 3 } = retryOptions;
        let lastResponse: APIResponse | null = null;

        for (let attempt = 1; attempt <= retryCount; attempt++) {
            lastResponse = await this.callApi(options);

            if (await condition(lastResponse)) {
                return lastResponse;
            }

            if (attempt < retryCount) {
                await new Promise(resolve => setTimeout(resolve, pollingInterval));
            }
        }

        return lastResponse!;
    }

/**
     * Convenience method for GET requests
     */
    async get(url: string, options?: Omit<ApiRequestOptions, 'url' | 'method'>): Promise<APIResponse> {
        return this.callApi({ url, method: 'GET', ...options });
    }
    /**
     * Convenience method for POST requests
     */
    async post(url: string, data?: unknown, options?: Omit<ApiRequestOptions, 'url' | 'method' | 'data'>): Promise<APIResponse> {
        return this.callApi({ url, method: 'POST', data, ...options });
    }

    /**
     * Convenience method for PUT requests
     */
    async put(url: string, data?: unknown, options?: Omit<ApiRequestOptions, 'url' | 'method' | 'data'>): Promise<APIResponse> {
        return this.callApi({ url, method: 'PUT', data, ...options });
    }

    /**
     * Convenience method for DELETE requests
     */
    async delete(url: string, options?: Omit<ApiRequestOptions, 'url' | 'method'>): Promise<APIResponse> {
        return this.callApi({ url, method: 'DELETE', ...options });
    }

    /**
     * Convenience method for PATCH requests
     */
    async patch(url: string, data?: unknown, options?: Omit<ApiRequestOptions, 'url' | 'method' | 'data'>): Promise<APIResponse> {
        return this.callApi({ url, method: 'PATCH', data, ...options });
    }

    /**
     * Parse JSON response with type safety
     */
    async parseJsonResponse<T>(response: APIResponse): Promise<T> {
        return await response.json() as T;
    }

    /**
     * Check if response is successful (2xx status)
     */
    isSuccess(response: APIResponse): boolean {
        const status = response.status();
        return status >= 200 && status < 300;
    }
    /**
     * Check if response is successful (2xx status)
     */
    isFailureClient(response: APIResponse): boolean {
        const status = response.status();
        return status >= 400 && status < 500;
    }

import { test, expect } from '@playwright/test';
import { ApiHelper } from '@utils/ApiHelper';
import { createLogger } from '@utils/logger';


const log = createLogger('create-booking');

interface CreateBookingResponse {
    bookingid: number;
    booking: {
        firstname: string;
        lastname: string;
        totalprice: number;
        depositpaid: boolean;
    };
}

interface BookingPayload {
    firstname: string;
    lastname: string;
    totalprice: number;
    depositpaid: boolean;
    bookingdates: BookingDates;
    additionalneeds: string;
}

interface BookingDates {
    checkin: string;
    checkout: string;
}

test.describe('@P0 @regression Level 2 (ApiHelper) - POST create booking', () => {
    test('POST /booking creates a booking and echoes it back', async ({ request }, testInfo) => {

        const api = new ApiHelper(request);

        const payload: BookingPayload = {
            firstname: 'Helper',
            lastname: 'Creator',
            totalprice: 640,
            depositpaid: false,
            bookingdates: { checkin: '2026-04-01', checkout: '2026-04-10' },
            additionalneeds: 'Breakfast',
        };

        let body: CreateBookingResponse;

            // Step 1 - send the create request
        await test.step('POST /booking with a new booking payload', async () => {
            log.info(`Step 1: POST /booking for ${payload.firstname} ${payload.lastname} (price ${payload.totalprice})`);
            const response = await api.post('/booking', payload);

            log.info(`Step 1: server responded with status ${response.status()}`);
            expect(api.isSuccess(response)).toBe(true);
            body = await api.parseJsonResponse<CreateBookingResponse>(response);
        });

         // Step 2 - verify the server echoed the booking back
        await test.step('Verify the created booking is echoed back', async () => {
            log.info(`Step 2: verifying booking id ${body.bookingid} echoes the payload`);
            expect(body.bookingid).toBeGreaterThan(0);
            expect(body.booking.firstname).toBe(payload.firstname);
            expect(body.booking.totalprice).toBe(payload.totalprice);
            log.info(`Step 2: booking ${body.bookingid} verified OK`);
        });





    })
});

import { test, expect } from '@playwright/test';
import { ApiHelper } from '@utils/ApiHelper';

test.describe('@P0 @regression Level 2 (ApiHelper) - PUT update booking', () => {
    test('PUT /booking/{id} replaces the booking with a Cookie token', async ({ request }) => {
        const api = new ApiHelper(request);
        // 1. Token.
        const authRes = await api.post('/auth', { username: '<username>', password: '<password>' });
        const { token } = await api.parseJsonResponse<{ token: string }>(authRes);
        expect(token).toBeTruthy();

         // 2. Create something to update.
        const created = await api.post('/booking', {
            firstname: 'Before',
            lastname: 'Helper',
            totalprice: 100,
            depositpaid: false,
            bookingdates: { checkin: '2026-05-01', checkout: '2026-05-05' },
        });
        const { bookingid } = await api.parseJsonResponse<{ bookingid: number }>(created);
        // 3. PUT with the Cookie header.
        const response = await api.put(
            `/booking/${bookingid}`,
            {
                firstname: 'After',
                lastname: 'Helper',
                totalprice: 880,
                depositpaid: true,
                bookingdates: { checkin: '2026-05-02', checkout: '2026-05-09' },
                additionalneeds: 'Extra bed',
            },
            { headers: { Cookie: `token=${token}` } },
        );

        expect(api.isSuccess(response)).toBe(true);
        const updated = await api.parseJsonResponse<{ firstname: string; totalprice: number }>(
            response,
        );
        expect(updated.firstname).toBe('After');
        expect(updated.totalprice).toBe(880);
    });
});

// All the payloads which we have 
// create
// How you can serialize or deserialize your responses 
// You can perform a JSON schema validation. 
// How you can basically perform the json path plus 
// Now you can similarly use auth or even JWT token, whatever 

import { APIResponse } from '@playwright/test';
import { ApiHelper, ApiContext } from '@utils/ApiHelper';

export interface BookingDates {
    checkin: string;
    checkout: string;
}

export interface Booking {
    firstname: string;
    lastname: string;
    totalprice: number;
    depositpaid: boolean;
    bookingdates: BookingDates;
    additionalneeds?: string;
}
export interface CreateBookingResponse {
    bookingid: number;
    booking: Booking;
}

export interface BookingFilters {
    firstname?: string;
    lastname?: string;
    checkin?: string;
    checkout?: string;
}

export interface BookingId {
    bookingid: number;
}

const JSON_HEADERS = { 'Content-Type': 'application/json', Accept: 'application/json' };
const TOKEN_REJECTED = 403;

export class BookingApi {

    private apiHelper: ApiHelper;
    private baseUrl: string;
    private username: string;
    private password: string;
    private cachedToken?: string;


    constructor(
        context: ApiContext,
        baseUrl = 'https://restful-booker.herokuapp.com',
        credentials: { username?: string; password?: string } = {},
    ) {
        this.apiHelper = new ApiHelper(context);
        this.baseUrl = baseUrl;
        this.username = credentials.username ?? '<username>';
        this.password = credentials.password ?? '<password>';
    }


    private authHeaders(token: string): Record<string, string> {
        return { ...JSON_HEADERS, Cookie: `token=${token}` };
    }

    /** Managed token, minted on first use. Pass `true` to force a re-auth. */
    async getToken(forceRefresh = false): Promise<string> {
        if (forceRefresh) this.invalidateToken();
        return (this.cachedToken ??= await this.auth());
    }

     /** Drop the cached token so the next managed call mints a new one. */
    invalidateToken(): void {
        this.cachedToken = undefined;
    }

    /**
     * Send an authenticated request. An explicit token goes out as-is so a negative
     * test can still assert a 403; the managed token re-auths once and retries.
     */
    private async sendAuthed(
        send: (token: string) => Promise<APIResponse>,
        explicitToken?: string,
    ): Promise<APIResponse> {
        if (explicitToken !== undefined) return send(explicitToken);
        const res = await send(await this.getToken());
        return res.status() === TOKEN_REJECTED ? send(await this.getToken(true)) : res;
    }

    async getAllBookings(filters?: BookingFilters): Promise<BookingId[]> {
        const response = await this.apiHelper.get(`${this.baseUrl}/booking`, {
            params: filters as Record<string, string> | undefined,
        });
        if (!this.apiHelper.isSuccess(response)) {
            throw new Error(`[BookingApi] GET /booking failed: ${response.status()}`);
        }
        return this.apiHelper.parseJsonResponse<BookingId[]>(response);
    }


      async getBooking(id: number): Promise<Booking> {
        const response = await this.getBookingResponse(id);
        if (!this.apiHelper.isSuccess(response)) {
            throw new Error(`[BookingApi] GET /booking/${id} failed: ${response.status()}`);
        }
        return this.apiHelper.parseJsonResponse<Booking>(response);
    }


    /** GET /booking/{id} -> raw response, so callers can assert status (e.g. 404). */
    async getBookingResponse(id: number): Promise<APIResponse> {
        return this.apiHelper.get(`${this.baseUrl}/booking/${id}`);
    }

     /**
     * POST /auth -> token. Note restful-booker answers bad credentials with
     * **200** and `{ reason: "Bad credentials" }`, so the status alone is not
     * enough: the body has to be checked for a token.
     */
     async auth(username = this.username, password = this.password): Promise<string> {
        const response = await this.apiHelper.post(`${this.baseUrl}/auth`, { username, password }, {
            headers: JSON_HEADERS,
        });
        if (!this.apiHelper.isSuccess(response)) {
            throw new Error(`[BookingApi] POST /auth failed: ${response.status()}`);
        }
        const body = await this.apiHelper.parseJsonResponse<{ token?: string; reason?: string }>(response);
        if (!body.token) {
            throw new Error(`[BookingApi] /auth returned no token. Reason: ${body.reason ?? 'unknown'}`);
        }
        return body.token;
    }

     /** POST /booking -> raw response, so callers can assert a rejection (e.g. 500). */
    async createBookingResponse(payload: unknown): Promise<APIResponse> {
        return this.apiHelper.post(`${this.baseUrl}/booking`, payload, { headers: JSON_HEADERS });
    }

     /** POST /booking -> { bookingid, booking }. No auth required. */
    async createBooking(payload: Booking): Promise<CreateBookingResponse> {
        const response = await this.createBookingResponse(payload);
        if (!this.apiHelper.isSuccess(response)) {
            throw new Error(`[BookingApi] POST /booking failed: ${response.status()}`);
        }
        return this.apiHelper.parseJsonResponse<CreateBookingResponse>(response);
    }

    /** PUT /booking/{id} -> raw response, so callers can assert a 403. */
    async updateBookingResponse(id: number, payload: unknown, token?: string): Promise<APIResponse> {
        return this.sendAuthed(
            (t) => this.apiHelper.put(`${this.baseUrl}/booking/${id}`, payload, {
                headers: this.authHeaders(t),
            }),
            token,
        );
    }
    /** Omit `token` to use the managed one, which renews itself on a 403. */
    async updateBooking(id: number, payload: Booking, token?: string): Promise<Booking> {
        const response = await this.updateBookingResponse(id, payload, token);
        if (!this.apiHelper.isSuccess(response)) {
            throw new Error(`[BookingApi] PUT /booking/${id} failed: ${response.status()}`);
        }
        return this.apiHelper.parseJsonResponse<Booking>(response);
    }

     async patchBooking(id: number, partial: Partial<Booking>, token?: string): Promise<Booking> {
        const response = await this.sendAuthed(
            (t) => this.apiHelper.patch(`${this.baseUrl}/booking/${id}`, partial, {
                headers: this.authHeaders(t),
            }),
            token,
        );
        if (!this.apiHelper.isSuccess(response)) {
            throw new Error(`[BookingApi] PATCH /booking/${id} failed: ${response.status()}`);
        }
        return this.apiHelper.parseJsonResponse<Booking>(response);
    }

     async deleteBooking(id: number, token?: string): Promise<number> {
        const response = await this.sendAuthed(
            (t) => this.apiHelper.delete(`${this.baseUrl}/booking/${id}`, {
                headers: this.authHeaders(t),
            }),
            token,
        );
        return response.status();
    }

import { test as base, expect } from '@playwright/test';
import { BookingApi } from '../api/BookingApi';

export type BookerFixtures = {
    bookingApi: BookingApi;
    bookerToken: string;
};

export const test = base.extend<BookerFixtures>({
    // Build the service object once and hand it to the test.
    bookingApi: async ({ request }, use) => {
        await use(new BookingApi(request));
    },

    // Generate a token via POST /auth and expose it to the test. This is the
    // "token generation lives in a fixture" requirement.
    //
    // A fixture resolves once, before the test body runs, so it cannot react to a
    // token that expires mid-test. That recovery lives in BookingApi.sendAuthed():
    // omit the token argument on a mutating call and it re-auths on a 403 and
    // retries. Use this fixture when you want the token value itself (to log it,
    // to pass it on, or to assert on it).
    bookerToken: async ({ bookingApi }, use) => {
        await use(await bookingApi.getToken());
    },
});

export { expect };

/**
 * A random booking, built entirely through `@utils/DataGenerator` so every spec
 * draws its randomness from one utility.
 *
 * Check-out is derived from check-in, so the stay is always in the right order,
 * and check-in is relative to today, so a booking never ages into the past.
 *
 * @param overrides fields to pin; anything omitted is generated.
 * @param stayNights nights between check-in and check-out (default 3).
 */
export function buildBookingFromGenerator(
    overrides: Partial<Booking> = {},
    stayNights = 3,
): Booking {
    const checkin = DataGenerator.dateOffset(1);

    return {
        firstname: DataGenerator.firstName(),
        lastname: DataGenerator.lastName(),
        totalprice: DataGenerator.number(100, 1000),
        depositpaid: DataGenerator.bool(),
        bookingdates: {
            checkin,
            checkout: DataGenerator.dateOffset(stayNights, new Date(checkin)),
        },
        additionalneeds: DataGenerator.oneOf(ADDITIONAL_NEEDS),
        ...overrides,
    };
}

import { test, expect } from '@fixtures/booker.fixture';
import { buildBookingFromGenerator } from '@testdata/booking.data';

test.describe.serial('@e2e @P0 Level 3 - Booking lifecycle (token from fixture)', () => {
    let bookingId: number;
     test('create a booking', async ({ bookingApi }) => {
        const { bookingid, booking } = await bookingApi.createBooking(
            buildBookingFromGenerator({ firstname: 'E2E', lastname: 'Journey' }),
        );
        expect(bookingid).toBeGreaterThan(0);
        expect(booking.firstname).toBe('E2E');
        bookingId = bookingid;

    });

    test('update the booking, then read it back', async ({ bookingApi }) => {
        const updated = await bookingApi.updateBooking(
            bookingId,
            buildBookingFromGenerator({ firstname: 'E2E', lastname: 'Updated', totalprice: 950 }),
        );
        expect(updated).toMatchObject({ lastname: 'Updated', totalprice: 950 });
        expect((await bookingApi.getBooking(bookingId)).lastname).toBe('Updated');
    });

    test('delete the booking and confirm it is gone', async ({ bookingApi }) => {
        expect(await bookingApi.deleteBooking(bookingId)).toBe(201); // booker returns 201, not 204
        expect((await bookingApi.getBookingResponse(bookingId)).status()).toBe(404);
    });





});