Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsUse Playwright tags to classify tests across your suite, then select them with --grep or exclude them with --grep-invert. Tags must start with @. Use projects instead when you need to run tests under different shared configurations, such as separate browsers or environments.
How Playwright tags work
A tag is a label attached to a test. It can be added in a test’s details object or written as an @-prefixed token in the title. Tags appear in reports and can be used to filter tests. See Playwright’s tag documentation.
Tags are not limited to a single test: a test.describe group can apply a tag to its tests, and an individual test can carry multiple tags. Each tag must begin with @.
Add tags to tests
Tag an individual test with a details object
import { test, expect } from '@playwright/test';
test('checkout accepts a valid card', {
tag: '@smoke',
}, async ({ page }) => {
// test steps
});This keeps the classification separate from the human-readable test title. The Playwright Test API documents the test options at Test API.
#1 Best Overall
Put a tag in the title
test('checkout accepts a valid card @smoke', async ({ page }) => {
// test steps
});This is a supported alternative, though a details-object tag can make titles easier to read when a suite has several classifications.
Tag a group and add test-specific tags
test.describe('checkout', { tag: '@checkout' }, () => {
test('accepts a valid card', { tag: ['@smoke', '@critical'] }, async ({ page }) => {
// test steps
});
});Choose a group-level tag when all tests in that describe block share the classification. Add individual tags for distinctions within the group. Names such as @smoke, @checkout, and @critical are examples, not a vocabulary prescribed by Playwright.
Choose a tag scheme your team can apply consistently
Playwright defines how tags work, but does not prescribe a naming scheme or maximum number of tags. Agree on what each label means before using it in scripts or CI. A practical scheme can classify tests by the decision the team needs to make:
- Execution purpose:
@smokefor a small confidence check or@regressionfor broader coverage. - Execution cost or cadence:
@slowfor tests that take longer or are run less often. - Product area:
@checkoutfor tests concerning checkout, including when they sit in different files or groups.
Keep spellings distinctive and apply them consistently. This matters because grep is not a tag-only filter: it searches a combined identity string containing the project name, file name, describe title, test title, and tags.
Run tests by tag from the command line
Use --grep to include tests whose combined identity string matches a regular expression, and --grep-invert to exclude matching tests. The CLI accepts the short -g alias for --grep. These examples follow Playwright’s command-line documentation.
Include one tag
npx playwright test --grep @smokeExclude a tag
npx playwright test --grep-invert @slowInclude tests with either tag
npx playwright test --grep "@smoke|@critical"The pipe is a regular-expression OR: a test matches if the combined string contains either expression.
Require both tags
npx playwright test --grep "(?=.*@smoke)(?=.*@critical)"The lookaheads require both expressions to occur in the string. OR and AND here are patterns you write as regular expressions, not separate Playwright filter operators. Quote expressions containing shell-significant characters; quoting rules can differ between shells.
Set a default filter in configuration
Use testConfig.grep to define a regular expression or an array of regular expressions in the Playwright configuration. Use grepInvert for the inverse. The TestConfig API documents these options.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →import { defineConfig } from '@playwright/test';
export default defineConfig({
grep: /@smoke/,
// Or use an array of regular expressions when needed.
// grep: [/@smoke/, /@critical/],
grepInvert: /@slow/,
});Choose a config-level filter only when it should affect ordinary runs that use that configuration. Otherwise, a routine command may silently run a narrower or different selection than a teammate expects; pass the filter on the command line when it should be temporary.
Choose between tags and projects
Tags classify tests and let you select cross-cutting subsets. Projects group tests that share execution settings, commonly a browser/device setup or environment. Use --project to select a configured project; combine it with grep when you need a tagged subset inside that project. See Playwright’s Projects documentation.
| Need | Use | Example |
|---|---|---|
| Run smoke tests across the suite | Tag plus grep | npx playwright test --grep @smoke |
| Run tests using a particular browser configuration | Project selection | npx playwright test --project=chromium |
| Run smoke tests in a particular project | Combine project and tag filter | npx playwright test --project=chromium --grep @smoke |
A tag does not create a browser or environment configuration, and a project is not a substitute for a cross-suite classification.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Distinguish test tags from run-level tags
The configuration tag option can prepend one or more tags to each test in a run so the run context is visible in reporting. Each configured tag must start with @. This is separate from test-level tags: it labels tests for the run and does not select which tests execute. See the TestConfig API.
Troubleshoot tag filtering
- A tagged test is missing: Check that the tag starts with
@, that the filter spelling matches, and that no config-levelgreporgrepInvertis changing the selection. - A filter matches unexpected tests: Remember that grep checks project, file, describe title, test title, and tags together. A word in a filename or title can match even if the test has no explicit matching tag. Use a more distinctive tag expression.
- An AND filter returns no tests: Confirm that the same test’s combined string contains both tag expressions. The lookahead pattern requires both; two separate grep flags are not needed.
- A command behaves differently across shells: Quote regex expressions that contain characters such as the pipe or parentheses, and use the quoting syntax for the shell running the command.
- A normal run selects fewer tests than expected: Inspect configuration for a default
greporgrepInvert; remove it or run with the intended selection. - The wrong environment or browser runs: Select the appropriate configured project with
--project; tags do not change project settings.
Or skip the browser setup
If your task is capturing a website screenshot rather than running Playwright tests, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. It accepts cookie banners before capture and removes 60+ known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status. MCP tools include take_screenshot, get_page_info, and capture_pdf.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo provides 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000. Sign up for a free ScreenshotNeo account.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
