DEV Community: Oleksandr Solomin

Setup type safe Playwright-Graphql client.

Oleksandr Solomin — Mon, 03 Mar 2025 15:53:14 +0000

Hello my fellows AQA Engineers! This is continuation of my previous article: Revolutionize GraphQL testing with auto generated type safe client.

Today I will guide you through creating a completely type-safe client framework for testing GraphQL APIs with Playwright Test.

Our goal is to set up a project for code generation and create a fixture with a GraphQL API client that will completely eliminate the need to define queries and mutations in your code.
Let's use this "Pokemon" API playground as our system under test: https://graphql-pokeapi.graphcdn.app

The link above will navigate you to the built-in GraphQL explorer that inspects the API, shows you all available queries, and allows you to write and send GraphQL requests.

We are going to automate all this boring and repetitive work!

As prerequisites, you should have a Node/TypeScript project with initialised Playwright Test.

Lets start:

Step 1. Installation:

npm install -D playwright-graphql

Step 2. Generate GraphQL type safe client via CLI:

playwright-graphql --url https://graphql-pokeapi.graphcdn.app

This command will generate the following files:

📁 Project Root
├── 📄 schema.gql (generated schema file)
└── 📁 gql (default directory for generated files)
    ├──📁 schema
    │  └── 📁 autogenerated-operations (GraphQL queries/mutations)
    │      ├── 📄 mutations.gql
    │      └── 📄 queries.gql
    └── 📄 graphql.ts (generated TypeScript types and client)

Step 3. Add path to your tsconfig:

To simplify your imports and improve project readability, configure your tsconfig.json by adding custom path aliases.
This makes it easier to import your generated GraphQL client across your project:

Add "@gql": ["gql/graphql"] for easy import.

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "Node16",
    "baseUrl": "./",
    "paths": {
      "@fixtures/*": ["fixtures/*"],
      "@gql": ["gql/graphql"]
    }
  }
}

This setup allows you to import your client like this:

import { getClient, GqlAPI } from '@gql';

Pay attention that the path @fixtures/* allows you to resolve each file in the directory as a module:

import { test, expect } from '@fixtures/gql';

Step 4. Create gql fixture file:

fixtures/gql.ts

import { test as baseTest, expect, request, APIRequestContext } from '@playwright/test';
// getClient function is factory for GraphQL client.
// GqlAPI represents type with all queries and mutations
import { getClient, GqlAPI } from '@gql'; 

export { expect };

type WorkerFixtures = {
    apiContext: APIRequestContext;
    gql: GqlAPI;
};

export const test = baseTest.extend<{}, WorkerFixtures>({
    apiContext: [
      async ({}, use) => {
        const apiContext = await request.newContext({
          baseURL: 'https://graphql-pokeapi.graphcdn.app'
        });
        await use(apiContext);
      }, { scope: 'worker' } 
    ],
    gql: [
        async ({ apiContext }, use) => {
            // gql endpoint is empty just because our pokemon SUT
            // does not use any graphql endpoint like 'api/graphql' 
            await use(getClient(apiContext, { gqlEndpoint: '' }));
        }, { auto: false, scope: 'worker' }
    ]
});

This fixture ensures that your tests have a consistent and type-safe GraphQL client available, and it leverages
Playwright’s API request context for efficient testing.

Step 5. You are ready jump into writing tests!

tests/pokemon.test:

import { test, expect } from "@fixtures/gql";

test('playwright-graphql test', async ({ gql }) => {
    const res = await gql.pokemons({
        limit: 2,
        offset: 1,
    });

    expect(res.pokemons?.results).toEqual(
        expect.arrayContaining([
            expect.objectContaining({ name: 'venusaur' })
        ])
    );
})

Now dear reader you do not have excuse to build strings in GrapgQL tests with Playwright.

Negative test:

By design GraphQL protocol always returns 200 code and in case error occurs it will be send in payload. By default Playwright-Graphql client throws an error if property data in payload is undefined or null because when error received instead of expected data from DB client will not be able to map this on any type, you can turn off this behaviour:

test('playwright-graphql negative test', async ({ gql }) => {
    const res = await gql.region({
        // @ts-ignore 
        region: undefined
    }, { failOnEmptyData: false });

    expect(res).toHaveProperty('errors[0].message', 'Variable "$region" of required type "String!" was not provided.');
})

Comment // @te-ignore turns off TS protection and allows you to not send required field, used just for demonstration.

Option failOnEmptyData: false just turn off response verification.

Coverage reporter

Since our focus is on input parameters (variables) that can be pass to queries and mutations we need a tool that will help us track what we've already covered in our tests and what still needs to be tested.

You already generated the GraphQL Schema for the Pokemon API playground, you can regenerate the existing autogenerated TypeScript file with coverage logging:

playwright-graphql --coverage

Now the CLI interface will not call the remote server a second time, instead it will regenerate only the graphql.ts file. This version of autogenerated code will include coverage logging.

Add the coverage reporter to your playwright.config.ts file:

import { defineConfig } from '@playwright/test';

export default defineConfig({
    testDir: 'tests',
    reporter: [
        ['list'],
        ['html', { open: 'never' }],
        ['playwright-graphql/coverage-reporter', {
            graphqlFilePath: './gql/graphql.ts',
            minCoveragePerOperation: 20, // percentage, default 100
            logUncoveredOperations: true,
            saveGqlCoverageLog: false,
            coverageFilePath: './gql-coverage.log',
            saveHtmlSummary: true
        }]
    ],
});

Pay attention that graphqlFilePath should point on autogenerated file graphql.ts from step 2

Run your tests:
npm test

This will produce the following console log output:

npx playwright test


Running 1 test using 1 worker

  ✓  1 tests/pokemon.test.ts:3:5 › playwright-graphql test (333ms)

  1 passed (1.1s)

To open last HTML report run:

  npx playwright show-report


============================================================
GQL Operations coverage in executed tests: 3.57%
Total operations: 28
Covered operations: 1
Total arguments coverage: 3.57%
================= Uncovered operations =====================
abilities 0%
ability 0%
berries 0%
berry 0%
eggGroup 0%
eggGroups 0%
encounterMethod 0%
encounterMethods 0%
evolutionChain 0%
evolutionChains 0%
evolutionTrigger 0%
evolutionTriggers 0%
gender 0%
genders 0%
growthRate 0%
growthRates 0%
location 0%
locations 0%
move 0%
moves 0%
nature 0%
natures 0%
pokemon 0%
region 0%
regions 0%
species 0%
types 0%
============================================================

This shows you a high level summary of coverage on queries and mutations level.

But that's not all.

Check your root directory and you will find a gql-coverage.html file there. Open it in your browser.
This HTML report page provides detailed information about covered input parameters for each query and mutation. It's capable of calculating enum parameter types and nested levels of parameters.

By implementing this type-safe GraphQL testing framework with Playwright, you've eliminated the error-prone process of manually writing GraphQL queries and gained valuable insights into your test coverage. The combination of auto-generated clients and comprehensive coverage reporting not only makes your tests more robust and maintainable but also helps you identify untested operations and parameters at a glance. As you expand your test suite, you'll appreciate how this approach scales effortlessly while providing immediate feedback on your testing progress. This framework transforms GraphQL API testing from a tedious task into a streamlined, efficient process that both new team members and experienced engineers will find intuitive and powerful.

Playwright-graphql: Revolutionize GraphQL Testing with Auto-Generated Type-Safe Client

Oleksandr Solomin — Sat, 22 Feb 2025 12:18:48 +0000

Playwright-graphql changes how we test GraphQL APIs. It creates client SDKs from your GraphQL schema, removing the need to write queries by hand. This tool combines Playwright's testing power with GraphQL's flexibility, making tests easier to write and maintain.

Before diving into GraphQL client-based automated tests, let me share a brief story about why I decided to build this integration.

When I first encountered a GraphQL API at work, I did what any engineer would do when faced with something unfamiliar, I googled it. I searched for "How to automate GraphQL with Playwright." The results, were disappointing. Every solution from seemingly relevant sources relied on using queries and mutations as raw strings in the codebase or, at best, employed rudimentary string builders.

This approach felt wrong. It was clunky, error-prone, and missed a critical point about how GraphQL APIs work under the hood. Let’s explore why this is a common mistake and how Playwright-GraphQL solves it.

The Problem with String-Based GraphQL Operations

To understand why using raw strings for GraphQL operations is problematic, we first need to understand how GraphQL APIs work behind the scenes.

How GraphQL Works:

GraphQL servers convert your queries into SQL queries, and mutations into CREATE, UPDATE, or DELETE operations in the database. For example:

{
        location(locationId:1428){
          id
          name
          created
        }
 }

Will be transformed into:

SELECT id, name, created FROM locations WHERE id = 1428;

The power of GraphQL lies in its flexibility. It allows developers to request only the data they need. However, this flexibility comes with a responsibility: ensuring that input parameters (like locationId) are tested thoroughly. Why? Because input parameters drive the backend logic (e.g., SQL WHERE conditions), while query fields (like id, name, created) just define which properties are selected in the response.

The Real Goal of GraphQL Testing

The primary goal of GraphQL testing should be to validate how input parameters affect backend behaviour. For example:

Are filters applied correctly?
Are limits (take) and offsets (skip) handled properly?
Does data in response sorted as expected?
Does the API return the expected results for edge cases?

Focusing on query fields instead of input parameters is a mistake because query fields don’t affect backend logic they only control what’s added in the response. To effectively test a GraphQL API:

Maximize SQL Query Coverage: Ensure your tests trigger as many variations of SQL WHERE conditions as possible.
Avoid Overloading Queries: Keep parameters like take (used for limiting results) reasonable to avoid extracting excessive data.

How Playwright-GraphQL Solves This Problem

Playwright-GraphQL eliminates the need for raw strings in your codebase by generating type-safe operations directly from your GraphQL schema. This approach ensures:

Focus on Input Parameters: Tests validate how input parameters affect backend logic.
Readable Tests: Tests focus on what is being tested, not how it is being tested.
Type Safety: Auto-generated types prevent invalid queries or mutations.

Here’s an example without: playwright-graphql:

Here's how the same test looks with playwright-graphql:

Why Playwright-GraphQL is Better:

No Raw Strings: You no longer need to write raw GraphQL queries or manually manage variables.
Type Safety: The generated client ensures that only valid operations and parameters can be used.
Cleaner Assertions: The response is already parsed and structured, so you can directly assert on the returned data.

By using Playwright-GraphQL, you avoid common pitfalls like forgetting to parse the JSON payload or misnaming fields in your queries. It simplifies your tests and allows you to focus on validating business logic instead of worrying about GraphQL protocol details.

🔑 Main Feature: Schema-Driven Automation

Unlike other GraphQL testing methods, this tool makes complete client SDKs directly from your GraphQL schema:

How It Works

Get Schema get-graphql-schema pulls your GraphQL endpoint definition
Make Operations gql-generator creates all possible queries/mutations
Add TypeScript GraphQL Codegen makes fully-typed client methods with autocomplete

NPM Package: https://www.npmjs.com/package/playwright-graphql

Template repo: https://github.com/DanteUkraine/playwright-graphql-example

Playwright-graphql makes GraphQL testing easier. It creates your API client automatically, so you can focus on writing good tests instead of managing API details. This saves time and helps catch errors early.

Continuation: Setup type safe Playwright-GraphQL client