How to Tag Tests in Playwright

Have you ever waited 30 minutes for your full test automation suite to run, just to check one login flow? Or worse, pushed code to production only to realize a critical test was silently skipped?

If you’re managing hundreds (or thousands) of automated tests, you’re probably wrestling with bloated runs, flaky CI jobs, and unclear test coverage. That’s where test tagging comes in. It’s not just a nice-to-have – it’s how modern teams tame chaos and take control.

Test tagging is a strategy used across nearly every major test automation framework, including Selenium, Cypress, JUnit, Playwright, and even tools powered by AI for QA testing. By tagging your tests with meaningful labels like @smoke, @regression, or @critical, you gain the ability to:

• Organize tests by purpose or priority

• Filter specific tests for execution.

• Parallelize or shard tests across CI pipelines

• Troubleshoot specific categories of failures

• Maintain test hygiene and clarity.

In short, tagging gives you precision. It puts you in control of your test suite.

Now, let’s shift gears and focus on Playwright, one of the most powerful and flexible end-to-end testing solutions available today.

Having used many different tech stacks and test automation frameworks, I’ll show you how to apply tagging in Playwright using TypeScript, from the legacy workarounds to the native tagging features introduced in recent releases.

You’ll get real examples, pro tips, and a few hard-earned lessons. Whether you are just starting Playwright or looking to refine your existing test suite, this guide will equip you with the knowledge to leverage test tagging effectively.

Let’s dive in!

All the code examples we discuss are available in the GitHub repository.

Why Tag Tests?

Before diving into code and examples, it’s worth understanding why tagging tests matter. Test tags are labels or markers that you assign to tests to categorise them. They help in:

• Selective test execution: Run a subset of tests based on criteria (for example: run only smoke, regression, or feature-specific tests).
• Organizing tests: Group tests by features, components, or priority..
• CI optimization: Speed up pipelines by running only necessary tests at different stages (for example: trigger different test sets in different stages or environments; smoke tests on every PR, full regression nightly).

• Parallelism and sharding: Distribute test workloads efficiently.

• Maintenance: Quickly locate or refactor related tests.

• Debugging: Re-run failing tags in isolation.

If you’re not tagging yet, you’re likely missing out on a huge maintainability and scalability boost.

Real-World Scenario:

Imagine you have a test suite of 1000 tests. Running all of them on every commit is time-consuming and expensive. Instead, you can:

• Run a set of smoke tests (tagged @smoke) on every pull request to catch critical issues quickly.
• Run regression tests (tagged @regression) nightly.
• Run tests for a specific module (for example: tagged @checkout) when changes are made to that module.

Here’s how you might tag them:

• @smoke: Core workflows, ~5% of tests

• @regression: Full suite for release, ~100%

• @ui, @api, @mobile: Layer-specific tests

• @flaky: Known unstable tests

• @critical, @low: Priority tiers

Getting Started with Playwright

First, ensure your environment is set up for Playwright with TypeScript. Create a new directory “playwright-tests” (or give any name you like for your project), and navigate to the folder in the terminal/command prompt. Run this command to initialize the playwright in your system.

npm init playwright@latest

This command scaffolds a complete Playwright TypeScript project.

Typical folder structure, you would have now is:

/playwright-tests

├── tests

│   ├── login.spec.ts

│   ├── dashboard.spec.ts

├── playwright.config.ts

When it comes to running and scaling your tagged tests across different environments, TestMu AI (Formerly LambdaTest) provides an excellent platform. TestMu AI’s cloud-based Selenium and Playwright grid allows you to run your tagged tests in parallel across a variety of browsers and devices, significantly speeding up your testing cycle. 

By integrating Playwright with TestMu AI, you can execute your tagged tests on a scalable grid of real devices and browsers, ensuring a comprehensive and efficient testing process. 

TestMu AI also supports advanced features like test analytics and video recording, which provide insights into test execution and failures, making it easier to track and troubleshoot issues in your tagged tests. With this integration, you can ensure that your tests are not only properly tagged but also run in the most efficient and scalable manner possible.

Application Under Test & Its Functionality

In order to discuss further the tagging functionality in Playwright, we need an application under test to play around with. The application under test is a sample e-commerce platform, similar to a typical online store. It includes features such as product search, category navigation, a homepage with banners and featured products, a shopping cart, and user account management (login and registration).

URL: https://ecommerce-playground.lambdatest.io/

What Tests Are Written?

We also need an existing set of test cases to leverage for applying tags and understanding their functionality. The test suite covers the following areas:

Homepage:

Tests validate the homepage’s title, URL, banners, featured products, trending categories, wishlist, and navigation to special offers.

Search Functionality:

Tests verify searching for products, handling empty and invalid searches, and checking product details in search results.

Category Navigation:

Tests cover navigating through product categories, verifying category pages, and checking view options (grid/list).

Cart Functionality:

Tests include adding products to the cart, viewing an empty cart, updating product quantities, and removing products.

Account Management:

Tests check login with invalid credentials, registration form fields, and registration with an existing email.

Tagging Tests in Playwright: The Old Approach (before v1.42)

Before version 1.42, Playwright did not have built-in support for test tags. Instead, we used to use workarounds like leveraging the test.describe function and custom attributes. The common practice was to use @ symbol in the test title and then use the – -grep and – -grep-invert CLI options to filter tests.

How it worked?

You would include tags in the test title as plain text. For example:

Then, to run only smoke tests, you would use:

npx playwright test –grep “@smoke”

Similarly, to exclude smoke tests:

npx playwright test –-grep-invert “@smoke”

Limitations

This approach had several limitations:

1. Fragile: If you change the tag format, you break the filtering.
2. No Type Safety: Tags were just strings, prone to typo errors.
3. Limited Expressiveness: Complex filtering was not straightforward.

Code Example

Here’s a more detailed example:

//tests/homepage.spec.ts

import { test, expect } from ‘@playwright/test’;

test.describe(‘Homepage Navigation’, () => {

    test.beforeEach(async ({ page }) => {

        await page.goto(“/”);

    });

    test(‘should navigate to Specials page @homepage @navigation @smoke @p1’, async ({ page }) => {

        await page.getByRole(‘link’, { name: ‘Special Hot’, exact: true }).click();

        await expect(page.getByRole(‘heading’, { name: /Special Offers/i })).toBeVisible();

    });

    test(‘should navigate to Contact Us page @homepage @navigation @p2’, async ({ page }) => {

        await page.getByRole(‘link’, { name: ‘Contact Us’ }).click();

        await expect(page.getByRole(‘heading’, { name: /Contact Us/i })).toBeVisible();

    });

});

Reporting

If you run this code and take a look at the report generated by Playwright, it looks like this. We can see the tags are displayed in the title as well as with markup values in the report – that means it’s duplicated and not readable.

Tagging Tests in Playwright: The New Approach (v1.42+)

Playwright 1.42 introduced built-in support for test tags. This is a game-changer because it provides a first-class, type-safe way to tag tests and filter them with more powerful expressions.

How it works?

Now, you can use the test or test.describe functions with a tag option. To use the new syntax, create a tag object with an array of tags or a single tag:

Or, if we wanted to use multiple tags:

As earlier, to run only smoke tests, you would still use:

npx playwright test –grep “@smoke”

Similarly, to exclude smoke tests:

npx playwright test –-grep-invert “@smoke”

Key Features

Type Safety: If you are using TypeScript, you can define a union type for your tags to prevent typos.

Dedicated Field: Tags are stored separately from the title, making them easier to manage.

Powerful Filtering: Use logical operators (and, or, not) to combine tags.

Code Example

//tests/homepage.spec.ts

import { test, expect } from ‘@playwright/test’;

test.describe(‘Homepage Navigation’,  { tag: [‘@e2e’, ‘@smoke’] }, () => {

    test.beforeEach(async ({ page }) => {

        await page.goto(“/”);

    });

    test(‘should navigate to Specials page’, { tag: [‘@homepage’, ‘@navigation’, ‘@smoke’, ‘@p1’] }, async ({ page }) => {

        await page.getByRole(‘link’, { name: ‘Special Hot’, exact: true }).click();

        await expect(page.getByRole(‘heading’, { name: /Special Offers/i })).toBeVisible();

    });

    test(‘should navigate to Contact Us page’, { tag: [‘@homepage’, ‘@navigation’, ‘@p2’]} ,async ({ page }) => {

        await page.getByRole(‘link’, { name: ‘Contact Us’ }).click();

        await expect(page.getByRole(‘heading’, { name: /Contact Us/i })).toBeVisible();

    });

});

Reporting

Look at the cleaner reporting format with this new tagging approach. No tagging details in the test title!

Comparing the Old and New Approaches

Let us take a look at the differences between the old and new approaches:

Recommendation: If you’re using Playwright v1.42 or newer, adopt the new approach. It’s more robust and flexible. You can still use the old approach, but not recommended to use – as it will be deprecated soon.

Conclusion

In conclusion, if you’re managing a large suite of automated tests, you know how important it is to stay on top of your testing process. Test tagging isn’t just about organization; it’s about control, precision, and efficiency. It helps you filter tests, parallelize execution, troubleshoot failures, and maintain clarity across your entire test suite. Whether you’re working with Selenium, Cypress, JUnit, Playwright, or even tools powered by AI for QA testing, this strategy is essential for keeping your tests manageable and your pipeline smooth.

And let’s not forget about automated accessibility testing. As teams continue to scale, accessibility shouldn’t be an afterthought. Integrating accessibility checks directly into your test automation suite ensures that you’re not only shipping code quickly but also delivering inclusive, accessible products. With the right tools and tagging strategies, accessibility tests can run alongside functional tests, saving time and reducing the risk of missing critical accessibility issues.

By implementing test tagging in Playwright, especially with the latest features and insights shared here, you’ll have the power to refine your test processes and boost the quality of both your functional and accessibility tests. The result? A leaner, faster, and more reliable test suite that helps you ship better code, faster, and more inclusively.