Forem: Juan G. Vazquez Jr.

Playwright BrowserContext: What It Is, Why It Matters, and How to Configure It

Juan G. Vazquez Jr. — Fri, 06 Feb 2026 18:02:59 +0000

If you’ve been using Playwright for a while, you’ve definitely used browserContext—even if you didn’t fully realize it. It’s one of those core concepts that quietly shapes test isolation, speed, flakiness, auth state, parallelism, and even how sane your test suite feels over time.

This article is a practical, real-world deep dive into:

What a BrowserContext actually is (and why it exists)
How Playwright creates and manages contexts for you
How to configure contexts globally in playwright.config.ts
How to share setup across tests without sharing state
When and how to use multiple setup files / projects
Common anti-patterns and real-world use cases

This is written for engineers who already know Playwright basics and want to level up their test architecture.

First: What Is a BrowserContext?

A BrowserContext is an isolated browser profile.

Think of it like this:

One Browser → the actual Chrome / Firefox / WebKit instance
Multiple BrowserContexts → separate incognito-like sessions

Each context has its own:

Cookies
LocalStorage / SessionStorage
IndexedDB
Cache
Permissions
Auth state

But they all share the same browser process, which is why contexts are fast and cheap.

If you’ve ever opened two incognito windows side by side — that’s basically two browser contexts.

Why BrowserContexts Exist (And Why You Should Care)

Playwright is opinionated about test isolation.

By default:

test('example', async ({ page }) => {
  // This page lives in a fresh browser context
});

Under the hood:

Playwright launches a browser
Creates a new browser context
Creates a page inside that context
Destroys the context after the test

This gives you:

No state leakage between tests
Safe parallel execution
Predictable failures

If you’ve ever fought flaky Selenium tests caused by leftover cookies — this is why Playwright feels so much better.

The Hidden Relationship: browser → context → page

You almost never create this manually, but it’s worth understanding:

const browser = await chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();

Playwright’s test runner does this for every test, unless you tell it otherwise.

Key takeaway:

Pages never exist without a BrowserContext.

Configuring BrowserContexts in `playwright.config.ts`

Most context configuration happens via the use block.

Basic Example

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

export default defineConfig({
  use: {
    baseURL: 'https://my-app.com',
    headless: true,
    viewport: { width: 1280, height: 720 },
    locale: 'en-US',
    timezoneId: 'America/New_York',
  },
});

Everything inside use becomes default BrowserContext options.

This means every test gets:

The same viewport
Same locale
Same timezone

…but still not the same state.

Auth State: The #1 Real-World BrowserContext Feature

Let’s talk about the killer feature: storageState.

Problem

Logging in before every test is:

Slow
Brittle
Redundant

Solution: Auth Setup + storageState

1️⃣ Create a global setup

// global-setup.ts
import { chromium } from '@playwright/test';

export default async () => {
  const browser = await chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();

  await page.goto('https://my-app.com/login');
  await page.fill('#email', 'user@test.com');
  await page.fill('#password', 'password');
  await page.click('button[type=submit]');

  await context.storageState({ path: 'auth.json' });
  await browser.close();
};

2️⃣ Reference it in config

export default defineConfig({
  globalSetup: './global-setup.ts',
  use: {
    storageState: 'auth.json',
  },
});

Now every test:

Starts logged in
Still runs in a fresh browser context

This is isolation with convenience.

Sharing Setup Without Sharing State

This is where many teams mess up.

❌ Anti-pattern

let sharedPage;

beforeAll(async ({ browser }) => {
  const context = await browser.newContext();
  sharedPage = await context.newPage();
});

This:

Breaks test isolation
Breaks parallelism
Causes order-dependent failures

✅ Correct Pattern: Fixtures

import { test as base } from '@playwright/test';

export const test = base.extend({
  authenticatedPage: async ({ page }, use) => {
    await page.goto('/dashboard');
    await use(page);
  },
});

Each test still gets:

Its own context
Its own page

But setup logic is shared cleanly.

Multiple BrowserContexts in One Test (Yes, You Can)

Sometimes you need multiple users.

Example: chat apps, admin/user flows, invitations.

test('admin invites user', async ({ browser }) => {
  const adminContext = await browser.newContext({ storageState: 'admin.json' });
  const userContext = await browser.newContext({ storageState: 'user.json' });

  const adminPage = await adminContext.newPage();
  const userPage = await userContext.newPage();

  await adminPage.goto('/admin');
  await userPage.goto('/dashboard');
});

This is powerful — and still fast.

Multiple Setup Files Using Projects

This is where Playwright really shines.

Use Case Examples

Logged-in user vs logged-out user
Admin vs regular user
Mobile vs desktop
Different feature flags

Example: Multiple Projects

export default defineConfig({
  projects: [
    {
      name: 'guest',
      use: {
        storageState: undefined,
      },
    },
    {
      name: 'user',
      use: {
        storageState: 'auth.json',
      },
    },
    {
      name: 'admin',
      use: {
        storageState: 'admin.json',
      },
    },
  ],
});

Each project:

Uses the same tests
Spins up different browser contexts
Runs in parallel if you want

You can even target them:

npx playwright test --project=admin

Can BrowserContexts Be Shared?

No — and that’s the point.

Contexts are designed to be:

Cheap
Disposable
Isolated

What can be shared:

Config (use)
Storage snapshots (storageState)
Fixtures and helpers

What should never be shared:

Live pages
Live contexts
Mutable global state

Mental Model to Remember

If you remember nothing else, remember this:

One test = one browser context

Unless you explicitly create more.

That rule alone explains:

Why Playwright scales
Why parallel runs work
Why tests don’t leak state

Common BrowserContext Mistakes (and How to Avoid Them)

1. Sharing Pages or Contexts Across Tests

This is the fastest way to introduce flaky, order-dependent tests.

If you see patterns like:

beforeAll creating a page
Globals holding page or context
Tests depending on previous navigation

You’re fighting Playwright instead of using it.

Fix: Let Playwright create a fresh context per test. Share setup logic via fixtures or storageState, not live objects.

2. Logging In Inside Every Test

Repeated UI logins:

Slow down your suite
Increase flakiness
Add zero test value

Fix: Use a dedicated auth setup and storageState. Test login flows separately.

3. Overusing `beforeAll`

beforeAll feels convenient, but it breaks:

Parallel execution
Isolation guarantees
Debuggability

Fix: Prefer per-test setup with fixtures. If something must run once, make sure it does not create shared browser state.

4. Confusing Config Sharing with State Sharing

Config options like use, projects, and fixtures are safe to share.

Browser contexts, pages, and mutable globals are not.

If a failure only happens when tests run together, this is usually the reason.

5. Avoiding Multiple Contexts When You Actually Need Them

Some teams try to force complex multi-user flows into a single page.

This leads to:

Unreadable tests
Fake mocks instead of real behavior
Missed bugs

Fix: Use multiple browser contexts intentionally when modeling real users.

Final Thoughts

BrowserContext is one of Playwright’s most important architectural concepts.

Once you understand how contexts work, your test suite naturally becomes:

Faster
More reliable
Easier to scale
Easier to reason about

If your Playwright tests feel fragile or hard to maintain, there’s a strong chance the root cause is how browser contexts are being managed.

Design around them correctly, and the rest of Playwright starts to feel effortless.

Happy testing

Understanding Headless vs. Headed Modes in Playwright: A Guide for QA Automation Engineers / SDETs

Juan G. Vazquez Jr. — Fri, 31 Jan 2025 11:50:51 +0000

As a Software Development Engineer in Test (SDET), understanding how to leverage headless and headed browser modes in Playwright can significantly impact the efficiency of your automated tests. In this article, we’ll explore these two modes, their pros and cons, and why headless mode is often preferred in Continuous Integration/Delivery (CI/CD) pipelines.

What Are Headless and Headed Modes?

Headless Mode: The browser operates without a graphical user interface (GUI). In essence, it runs in the background, rendering the DOM and executing all operations without displaying anything on the screen.
Headed Mode: The browser operates with a GUI, allowing you to visually see the browser as it navigates, interacts with elements, and executes tests.

Configuring Headless and Headed Modes in Playwright

In Playwright, switching between these modes is straightforward. You can control the mode by setting the headless property in the launch method of the browser.

Example:

import { chromium } from 'playwright';

(async () => {
    const browser = await chromium.launch({ headless: true }); // Headless mode
    const context = await browser.newContext();
    const page = await context.newPage();

    await page.goto('https://example.com');
    console.log(await page.title());

    await browser.close();
})();

Change headless: true to headless: false for headed mode.

Pros and Cons of Headless and Headed Modes

Headless Mode

Pros:

Performance: Faster execution as no GUI needs rendering.
Resource Efficiency: Consumes less CPU and memory, allowing for parallel execution of multiple tests.
Scalability: Ideal for CI/CD pipelines where multiple tests run simultaneously.

Cons:

Debugging Difficulty: Without visual feedback, debugging failures can be challenging. Screenshots and videos become essential for diagnosing issues.
False Positives/Negatives: Minor discrepancies might arise due to differences in rendering behavior compared to a GUI-enabled browser.

Headed Mode

Pros:

Debugging Ease: Provides a clear view of the browser’s actions, making it easier to identify issues during test execution.
Realistic Interactions: Useful for validating animations, transitions, and user interface behaviors that depend on visual elements.
Ideal for Automation and Debugging: Headed mode is especially good for scenarios where visual feedback is necessary to troubleshoot problems.

Cons:

Performance Overhead: Slower execution due to GUI rendering.
Resource Intensive: Requires more CPU and memory, which can limit parallel execution.

Why Headless Mode Works Better

Stealthier Execution: Headless mode often avoids triggering detection mechanisms because it mimics user interactions without rendering a GUI, reducing anomalies in behavior.
Fewer Visual Artifacts: Websites might flag elements like the absence of mouse movements or odd window dimensions in headed mode, whereas headless mode can replicate consistent, browser-like behavior.
Lower Overhead: Headless mode avoids rendering, meaning it can be more consistent and less prone to resource-related delays that could be flagged by a website.

Why Use Headless Mode in CI/CD Pipelines?

CI/CD pipelines prioritize speed, resource efficiency, and reliability. Headless mode aligns perfectly with these requirements:

Faster Execution: Tests run quicker without GUI rendering, reducing the total pipeline runtime.
Resource Optimization: Multiple headless browsers can run simultaneously on the same machine, maximizing resource utilization.
Non-Interactive Environments: CI/CD pipelines typically operate in server environments without display capabilities, making headless mode the default choice.

Best Practices for Using Headless Mode in CI/CD Pipelines

Enable Logging: Capture console logs to debug JavaScript errors and other issues.

page.on('console', msg => console.log(msg.text()));

Use Screenshots and Videos: Configure Playwright to capture screenshots or videos for failed tests.

await page.screenshot({ path: 'screenshot.png' });

Configure Timeouts: Set appropriate timeouts for elements to avoid false negatives caused by slow-loading pages.

await page.waitForSelector('#element', { timeout: 5000 });

Run Tests Locally in Headed Mode: Use headed mode for local debugging and headless mode for pipeline execution. Playwright’s built-in UI mode can help during test creation and debugging by visualizing test runs:

npx playwright test --ui

Use the Same Browser Version: Ensure consistency by using the same browser version locally and in CI/CD to avoid discrepancies.

Debugging Tips for Headless Mode

Even in headless mode, Playwright offers robust debugging capabilities:

Record Traces: Use the trace viewer to capture and replay test actions step by step.

await context.tracing.start({ screenshots: true, snapshots: true });
// Run your test steps
await context.tracing.stop({ path: 'trace.zip' });

Conclusion

Understanding the trade-offs between headless and headed modes is crucial for SDETs working with Playwright. While headed mode is invaluable for debugging and local development, headless mode reigns supreme in CI/CD pipelines due to its speed and resource efficiency. By adopting best practices like logging, screenshots, and trace recording, you can ensure robust and reliable automation in headless environments.

data-testid: Bridging the Gap between QA Engineering and Front End Dev

Juan G. Vazquez Jr. — Fri, 20 Sep 2024 09:47:40 +0000

original article medium.com/@JohnnyV_5G

In the ever-evolving world of software testing, we often find ourselves embarking on new adventures - like trying out the latest frameworks. Recently, we were tasked with implementing a new testing framework and decided to roll with Playwright, because, why not aim for the stars? 🚀

However, as we dove into this exciting new realm, we quickly realized that having a robust testing strategy isn't just about the latest tools. It's also about having a reliable way to identify elements on the page. Enter data-testid - our unsung hero.

In this piece, we'll explore why data-testid attributes are like the secret sauce that can turn a good test into a great one. We'll show you how this little attribute can make your Playwright tests as smooth as a victory in the Squid Game - minus the drama, of course. So, buckle up and let's dive into how data-testid can make your testing journey more manageable and less like a game of chance!

Why Using data-testid is Important

Separation of Concerns: The data-testid attribute helps keep test selectors separate from other attributes that are meant for UI or functionality, like id or class. These attributes might change as part of UI updates, but the data-testid is meant to be stable, ensuring your tests don't break with UI changes.
Avoids Targeting Visual Elements: Often, developers are tempted to use classes or styles for testing, but these are subject to frequent changes when CSS is modified. Using data-testid ensures that the tests remain stable regardless of visual or structural changes.
Readability in Tests: When using data-testid, the test code becomes more readable. Testers and developers can immediately understand what element is being tested without guessing based on ambiguous or changing attributes like id or class.
Performance Optimization: Selecting elements using data-testid can be faster and more reliable in tests compared to selecting elements by class names, which are generally used for styling and might not be unique or optimized for querying.

Best Practices for Adding data-testid

For Key Interactive Elements: Use data-testid on elements that your tests frequently interact with, such as buttons, input fields, and links. This ensures that the most critical user actions can be reliably tested.

<button data-testid="submit-button">Submit</button>

Stable, Descriptive Naming: The data-testid values should be stable and descriptive of the element's role or action, e.g., submit-button, login-form, or profile-picture. Avoid using temporary or context-specific names that could change frequently.
For Dynamic Content: Use data-testid on elements where content changes dynamically, like modals, dropdowns, or dynamically loaded lists. This allows your tests to reliably locate and verify dynamic content.
Avoid Overuse: Not every element needs a data-testid. Apply it only to elements you interact with in tests, to avoid cluttering the HTML.
Multiple Child Elements: If a parent container has multiple child elements, assign data-testid to specific children rather than the container. This allows precise interaction with the correct elements in tests.
Unique Identifiers: Ensure each data-testid value is unique within the scope of your page, so there is no ambiguity when selecting elements in tests.

How to Explain to your Front-end Developers the Importance of Using data-testid Attributes

Hey there, front-end wizards! Let's chat about data-testid attributes - those little heroes of testing that don't get nearly enough credit.

Why Use data-testid?

Because I told you so! …. no no jk jk…. we are alllll in the "same team" 🙄

A Secret Code for Testers: Think of data-testid as your personal secret code that only testers and automated scripts know. It's like a VIP pass for your elements. When your testers want to find that elusive button or input field in your complex layout, data-testid is their golden ticket.
The Non-Disruptive Sidekick: Unlike those flamboyant class names or IDs, data-testid quietly sits in the background, never stealing the spotlight from your shiny new CSS or causing layout dramas. It's there to help, not to show off.
A Refuge from Randomness: If you've ever tried to test something using a dynamically generated class name or ID, you know the struggle is real. data-testid is a steadfast anchor in the turbulent sea of changing styles and structure. It's like having a GPS in a maze.
The Invisible Friend: It's like having a friend who's always there to lend a hand but never makes a fuss. data-testid doesn't mess with your design or functionality; it just does its job silently, helping your tests find what they need without a fuss.
A Clean Slate for Future Upgrades: Imagine your app gets a makeover. If you've used data-testid, your tests will still be able to find what they're looking for, even if the UI gets a whole new look. No more worrying about breaking tests when you jazz up the design.

So, in Summary…
Use data-testid attributes as your secret agent for testing. They keep things clean, simple, and less prone to the dreaded "why is this test failing now?" headaches. They're the unsung heroes of the testing world, helping us all live happily ever after in code harmony.
Now, go forth and data-testid your way to automation success!

await page.evaluate(() => 
{ try { SquidGame.run(); } 
catch { 
console.log('Looks like we're all playing Red Light, Green Light here!'!'); 
} 
});

https://www.reddit.com/r/ProgrammerHumor/comments/qjpy74/squidgamerun/

QA Tester, QA Engineer, QA Automation Engineer, and SDET. What’s the difference?

Juan G. Vazquez Jr. — Sat, 31 Aug 2024 21:29:38 +0000

original article medium.com/@JohnnyV_5G

When it comes to software quality assurance (QA), the titles can get pretty confusing. Let’s break it down.

QA Tester

Think of QA Testers as the chess pawns or frontline soldiers of the QA world. They primarily focus on manual testing. Their job? To execute test cases, hunt down bugs, and make sure the software does what it’s supposed to do. They dive into exploratory testing, regression testing, and usability testing. No coding skills required — just a sharp eye for detail and a knack for understanding how users might interact with the application.

Responsibilities:

Executing Test Cases: QA Testers meticulously follow predefined test cases to validate that the software functions as expected.
Bug Hunting: They identify, document, and track software bugs, often using bug tracking tools.
Exploratory Testing: Beyond predefined tests, they explore the application to discover unexpected issues.
Regression Testing: They re-test functionalities to ensure new changes haven’t broken existing features.
Usability Testing: QA Testers evaluate the software from a user’s perspective to ensure a seamless user experience.

Tools They Use:

Bug Tracking Tools: JIRA, Bugzilla, Mantis
Test Management Tools: TestRail, Zephyr, Quality Center
Collaboration Tools: Slack, Trello, Confluence

Example Task:

Imagine a new e-commerce website feature where users can apply discount codes. A QA Tester would manually test different discount codes to ensure they apply correctly, checking various scenarios like expired codes, minimum purchase requirements, and stacking multiple discounts. They would document each test case in TestRail and log any issues in JIRA, providing detailed steps to reproduce the bugs.

QA Engineer

QA Engineers take a broader approach. They design and develop test plans, create test cases, and can dabble in both manual and automated testing. These folks are all about improving the QA process. They work closely with developers and stakeholders to ensure everything runs smoothly. They’ve got a solid understanding of QA methodologies and maybe some basic scripting skills to help out with automation.

Responsibilities:

Test Planning: Creating detailed test plans to ensure comprehensive coverage of all software features.
Test Case Development: Designing both manual and automated test cases.
Process Improvement: Continuously refining the QA process to enhance efficiency and effectiveness.
Stakeholder Collaboration: Working with developers, product managers, and other stakeholders to understand requirements and deliver quality software.
Basic Automation: Implementing simple automated tests to complement manual testing efforts.

Tools They Use:

Test Case Management Tools: TestRail, Zephyr
Bug Tracking Tools: JIRA
Automation Tools: Basic frameworks like Selenium WebDriver, Postman for API testing
Continuous Integration Tools: Jenkins, GitLab CI

Example Task:

For a mobile banking app, a QA Engineer might create a comprehensive test plan that includes both manual and automated tests. They would test features like login, balance checks, fund transfers, and bill payments. The QA Engineer would use Selenium to automate the web interface tests and Postman to automate API tests. They ensure these tests run automatically on every code change using Jenkins, providing quick feedback to developers about any issues.

QA Automation Engineer

Now, QA Automation Engineers are the automation gurus. They write and maintain scripts that automate the testing process. This means they need strong programming skills and experience with tools like Selenium or Appium. They’re the ones integrating these automated tests into the CI/CD pipeline, ensuring the tests run seamlessly every time the code changes. They’re all about efficiency and making sure that tests provide thorough coverage of the software requirements.

Responsibilities:

Script Development: Writing and maintaining automated test scripts to validate software functionality.
Framework Implementation: Building and maintaining the automation framework.
CI/CD Integration: Ensuring automated tests are integrated into the continuous integration/continuous deployment (CI/CD) pipeline.
Test Coverage: Expanding automated test coverage to include new features and regression tests.
Efficiency Optimization: Continuously improving the automation process for faster and more reliable test execution.

Tools They Use:

Automation Frameworks: Selenium for web applications, Appium for mobile apps, Cypress for JavaScript applications
Test Frameworks: TestNG, JUnit, Mocha
CI/CD Tools: Jenkins, GitLab CI, CircleCI
Version Control Systems: Git

Example Task:

Automating the login functionality for a web application. The QA Automation Engineer would write a Selenium script that inputs various user credentials, checks the login outcome, and reports any failures automatically. They would integrate these scripts with Jenkins so that the tests run every time a developer pushes new code. This automation ensures that any changes to the login feature are instantly validated, reducing the risk of bugs making it to production.

SDET (Software Development Engineer in Test)

SDETs are like QA superheroes with a developer’s mindset. They write code to test code, often building complex test frameworks and tools from scratch. They have strong software engineering skills and work closely with development teams to improve the overall quality of the codebase. Their expertise spans deep testing methodologies, test automation, and test-driven development (TDD). Think of them as the bridge between development and QA.

Responsibilities:

Framework Development: Building sophisticated test frameworks that can handle complex testing scenarios.
Code Quality Improvement: Collaborating with developers to write testable code and improve overall code quality.
Advanced Testing: Implementing advanced testing methodologies, including TDD and behavior-driven development (BDD).
Scalability Testing: Ensuring the application can scale and perform under high load conditions.
Infrastructure Management: Using tools like Docker and Kubernetes to create and manage test environments.

Tools They Use:

Development Tools: IntelliJ IDEA, Visual Studio Code
Testing Frameworks: JUnit, TestNG, NUnit
Automation Tools: Selenium, Appium, Postman for API testing
Infrastructure Tools: Docker, Kubernetes, AWS for cloud environments

Example Task:

Building a custom testing framework for a cloud-based application. An SDET might create a suite of integration tests that simulate thousands of users interacting with the system, ensuring scalability and performance under load. They would use Docker to create consistent testing environments and Kubernetes to manage these environments at scale. The SDET would also write complex API tests using Postman or a similar tool, ensuring the application’s backend can handle high traffic and large data volumes.

So, what’s the bottom line?

QA Tester: Manual testing expert focused on executing test cases and finding bugs.
QA Engineer: A blend of manual and automation testing, with a focus on improving QA processes.
QA Automation Engineer: Specializes in automating the testing process with strong programming skills.
SDET: Combines the skills of a developer and tester, creating robust testing frameworks and ensuring high-quality code.

Each role plays a vital part in delivering reliable, high-quality software. Whether manually running tests, automating them, or developing sophisticated testing tools, they are each a key piece of the development puzzle.

Forem: Juan G. Vazquez Jr.

Playwright BrowserContext: What It Is, Why It Matters, and How to Configure It

First: What Is a BrowserContext?

Why BrowserContexts Exist (And Why You Should Care)

The Hidden Relationship: browser → context → page

Configuring BrowserContexts in playwright.config.ts

Basic Example

Auth State: The #1 Real-World BrowserContext Feature

Problem

Solution: Auth Setup + storageState

1️⃣ Create a global setup

2️⃣ Reference it in config

Sharing Setup Without Sharing State

❌ Anti-pattern

✅ Correct Pattern: Fixtures

Multiple BrowserContexts in One Test (Yes, You Can)

Multiple Setup Files Using Projects

Use Case Examples

Example: Multiple Projects

Can BrowserContexts Be Shared?

Mental Model to Remember

Common BrowserContext Mistakes (and How to Avoid Them)

1. Sharing Pages or Contexts Across Tests

2. Logging In Inside Every Test

3. Overusing beforeAll

4. Confusing Config Sharing with State Sharing

5. Avoiding Multiple Contexts When You Actually Need Them

Final Thoughts

Understanding Headless vs. Headed Modes in Playwright: A Guide for QA Automation Engineers / SDETs

What Are Headless and Headed Modes?

Configuring Headless and Headed Modes in Playwright

Example:

Pros and Cons of Headless and Headed Modes

Headless Mode

Headed Mode

Why Headless Mode Works Better

Why Use Headless Mode in CI/CD Pipelines?

Best Practices for Using Headless Mode in CI/CD Pipelines

Debugging Tips for Headless Mode

Conclusion

data-testid: Bridging the Gap between QA Engineering and Front End Dev

QA Tester, QA Engineer, QA Automation Engineer, and SDET. What’s the difference?

Configuring BrowserContexts in `playwright.config.ts`

3. Overusing `beforeAll`