DEV Community: Aykut Denizci

Configuring Playwright MCP Like a Pro: Custom Headers, Cookies, and Smarter Agents

Aykut Denizci — Wed, 26 Nov 2025 05:40:42 +0000

How can you use Playwright MCP more effectively? How can you handle login scenarios? And how can you run Playwright MCP using your own browser profile? I hope this article helps answer questions like these :) Enjoy reading!

We use Playwright MCP, but are we really using it efficiently? Does it cover all our cases? After finding myself thinking things like “It doesn’t support this” or “I don’t think it can do that,” I realized the real issue was that I wasn’t configuring it correctly. With proper configuration, I discovered that it can actually solve all of my problems. In this article, we’ll look at how to use MCP more effectively through the configurations we can provide. (You can find even more details in the link.)

1. Config

With a config.json file you create, you can provide most of the settings you normally define inside playwright.config.ts.

Browser Args
Extra Http Header
ViewPort Size
Permissions
bypassing CSP, and similar configurations can all be added through this JSON file.

With these settings, MCP can also help you handle cases where the page behaves differently based on specific headers you pass. This allows the agents to analyze the page with those headers applied. An example config file would look like this:

{
  "browser": {
    "launchOptions": {
      "args": [
        "--ignore-certificate-errors"
      ]
    },
    "contextOptions": {
      "extraHTTPHeaders": {
        "test-header": "true"
      },
      "permissions": ["geolocation"],
      "bypassCSP": true
    }
  }
}

You also need to provide the location of this file inside your mcp.json, under the args section of the Playwright MCP configuration.

    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--config=path/to/playwright-mcp.config.json"
      ]
    }

2. Storage State

If you need cookies for a full and accurate page analysis, this part is exactly what you need. Anyone using Playwright is familiar with the concept of storage state, which saves your session’s cookie values and lets your tests run with them. The same applies to MCP by creating a JSON file and providing your cookie values there, you can run MCP with the session you want.

In my opinion, the biggest advantage is eliminating the login step. By supplying token-based cookies, you prevent MCP from wasting time on login flows and let it directly analyze authenticated pages. An example storage state JSON file might look like this:

{
  "cookies": [
    {
      "name": "testCookie",
      "value": "testValue123",
      "domain": ".testDomain.com",
      "path": "/",
      "expires": -1,
      "httpOnly": false,
      "secure": true,
      "sameSite": "Lax"
    },
    {
      "name": "token",
      "value": "testToken123.",
      "domain": ".testDomain.com",
      "path": "/",
      "expires": -1,
      "httpOnly": false,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "origins": []
}

You’ll need to provide this file in the same place inside your mcp.json as well, just like the previous configuration. It should look something like this:

    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--storage-state=path/to/storage-state.json"
      ]
    }

3. Init Script

If you want MCP to run certain actions at the very beginning, or if you want to show specific logs, alerts, or messages on the DOM under certain conditions, the init script will do exactly what you need. You can take the curl of a request and have it executed at the start of the MCP run or whenever the conditions you define are met. You can even customize it to display error messages directly on the UI, as shown in the example 😄

To use this, simply create an init-script.js file and provide its path in your mcp.json as shown below.

    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--init-script=path/to/init-script.js"
      ]
    }

4. Extension

If you want MCP to run with your own browser settings using your personal browser profile this part is exactly what you need. After downloading and installing the extension (as shown in the link), you can run your MCP tests on your own browser profile by adding the following configuration to your mcp.json.

    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--extension"
      ]
    }

After completing the setup, when you run MCP, it will launch a browser using your profile and ask for permission to access it. Once you approve that prompt, it will continue running with your own browser settings.

Debbie O'Brien also has a great video about this extension on YouTube. I definitely recommend watching it.

https://youtu.be/uE0r51pneSA?si=opgO-bCizppC7uxK

5. Other Settings

In addition to the features mentioned above, there are a few more settings that can be useful:

Isolated: Ensures that each test session starts in an isolated browser profile. Use --isolated.
Device: If you want your MCP to emulate different devices while running tests and analyzing pages, you can set this option. Example: --device=iPhone 15.
Headless: If you don’t want to see a browser launching while MCP does its work in the background, add this option to your mcp.json --headless.

Finally, you can also configure agents to perform the actions you want. Playwright MCP server allows you to run JavaScript evaluate commands. For example, you can add a step like the following to the Planner agent’s MD file:

When you have finished manually testing, add a thick red border around the specific areas that have been tested

At the end of the analysis, the browser view looks like this:

Debbie O'Brien also has a great video on this topic, where you can learn more details.

https://youtu.be/n0CFmm38o4Y?si=FxV00dNx1SHB_CJQ

Thank you for reading this far. I hope you found it helpful 🙏

Playwright Agents

Aykut Denizci — Fri, 14 Nov 2025 11:09:59 +0000

In this article, I’ll talk about the Playwright agents introduced with Playwright version 1.56 and walk through the concept with examples.

Playwright 1.56 brings three types of agents into our workflow:

Planner
Generator
Healer

To automatically generate these agents, you can run one of the following commands depending on the AI-powered editor you’re using:

# Visual Studio Code -> Works for Cursor as well
npx playwright init-agents --loop=vscode
# Claude Code
npx playwright init-agents --loop=claude
# Opencode
npx playwright init-agents --loop=opencode

For Cursor users, you can convert the generated file into MDC format and move it under .cursor/rules to continue.

The Planner visits the page you need to test, analyzes it, and generates test cases in Markdown format. We will try these cases on Trendyol’s cart page for that, we want it to add an item to the cart and navigate to the cart before starting the analysis.

After analyzing the page, it creates the test plan in .md format, closes the browser, and completes the process.

When reviewing the generated test plan, we can clearly see that it produces scenarios we actually need. It doesn’t just think functionally when I tested it on a login page, it even generated security related cases (such as XSS vulnerabilities and CSRF protection).

Now, let’s take one of the cases created by the Planner and try to generate the test using the Generator agent. For this example, I’m choosing the case that increases the product quantity.

The test was successfully created. It is able to automatically add the necessary commands I normally use in my basket tests (such as login and adding a random product to the cart) inside the beforeEach, following the exact structure I use in my other spec files. It also generates the test in the same style I use for example, by waiting for responses instead of relying on static waits. This means I don’t have to refactor the test to match my existing code standards.

When I ran this test across the six projects defined in my Playwright config, five passed and one failed. To fix this, we’ll use the Healer agent.

After enabling the Healer, it runs the tests across all projects, identifies flaky parts, and if it doesn’t catch the issue on the first attempt, it retries the failing test several times to reproduce the flaky behavior.

Once it identifies the issue, it applies logical fixes.

Then it applies sensible fixes to the issues it finds.

And here is the result.

Conclusion

Playwright Agents are evolving beyond simple tools that execute test code they now actively contribute to test analysis, maintenance, and even scenario generation. Each agent has its own strengths. For example, the Healer re-runs failing steps, analyzes UI changes, proposes fixes, and retries tests multiple times to detect flaky behavior. The Planner can generate user scenarios we might not even think of and provides highly sensible additional checks for existing tests. The Generator analyzes our existing tests, adds necessary preconditions automatically, and produces new tests that match our coding style. This leads to more consistent test suites and significantly reduces the need for manual adjustments.

With all these capabilities combined, I can confidently say that Playwright Agents bring real value to my testing process in terms of both speed and quality.

For more details, you can read Playwright’s official documentation or watch the YouTube video they shared.

https://playwright.dev/docs/test-agents

Sharding in Playwright: Speeding Up Your Test Suites and CI Pipelines

Aykut Denizci — Mon, 03 Nov 2025 10:07:41 +0000

In this article, I’ll talk about why using sharding in Playwright automation projects is so important, how it affects your test durations, and how you can use it effectively based on your project needs.

By default, Playwright runs test files in parallel and strives for optimal utilization of CPU cores on your machine.

To achieve even greater parallelization, you can further scale Playwright test execution by running tests on multiple machines simultaneously — a process Playwright refers to as “sharding.”

Without sharding, all tests are distributed among the workers within a single pod.

When sharding is enabled, the test suite is divided into multiple shards, and each shard runs its own workers on separate pods.

This allows true multi pod parallelism.

Workers → parallel test executors within the same pod
Shards → distribute the test suite across multiple pods

To enable sharding, simply add the following option to the end of your test command.

Here, x represents the active shard index, and y represents the total number of shards:

--shard=x/y

If you’re using sharding, the fullyParallel parameter becomes even more important.

When this parameter is set to true, all your tests are divided and executed across the shards.

If it’s set to false, the distribution happens on a file basis — meaning entire test files are assigned to shards rather than individual tests.

However, there’s an important nuance here: even when fullyParallel is set to false, the same test file can still run on different shards if it’s executed under multiple projects defined in your Playwright configuration.

For example, a basket1.spec.ts file might run on one shard for the project1 project and on another shard for the project2 project.

You can add sharding to your YAML configuration as shown below:

parallel: 4
  script:
    - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL

Tip: If you’re using npm run or yarn run, you need to add an extra -- before your Playwright arguments.

npm run test -- --shard=1/4

In our automation project, we built a login system that assigns different users to each worker within a spec file to prevent them from interfering with one another.

However, this setup introduced flakiness in our tests when running with Playwright’s fullyParallel parameter — both in true and false modes.

To overcome this issue, we started manually assigning spec files to specific shards , giving us full control over how tests are distributed.

If you’re facing a similar problem, you can configure your YAML file as shown below.

parallel:
    matrix:
      - SPEC_FILE: "basket1.spec.ts basket2.spec.ts"
      - SPEC_FILE: "basket3.spec.ts checkout.spec.ts checkout2.spec.ts"
      - SPEC_FILE: "checkout3.spec.ts basket4.spec.ts"
      - SPEC_FILE: "checkout4.spec.ts"

When doing so, it’s important to keep the completion times of shards as close as possible to optimize the overall pipeline duration.

If one spec file takes significantly longer than others, consider splitting it into multiple smaller specs and assigning them to different shards — this can lead to a noticeable time gain.

For example, in our project, the checkout4.spec.ts file used to take much longer than other specs.

By splitting it into two separate specs and assigning them to different shards, we were able to significantly reduce the total test duration.

Before

After

After completing the sharding setup, the next important step is merging the reports generated by the shards.

To merge the reports, you need to set the reporter type in your Playwright configuration to blob.

The blob reporter is mergeable and can be converted into other reporting formats. It can include screenshots, traces, and other attachments , making it ideal for shard-based parallel test runs.

You can add the following setting to your configuration file:

export default defineConfig({
  testDir: './tests',
  reporter: process.env.CI ? 'blob' : 'html',
});

To merge your reports, you can run the following command:

npx playwright merge-reports --reporter html ./all-blob-reports

Here, the --reporter parameter specifies which format the blob reports will be converted to , and the path at the end points to the folder containing the blob reports to merge.

Additionally, if you have multiple reporting configurations or want to generate multiple report types from blob reports, you can create a separate config file and pass it to the merge-reports command.

For example, in our project, we generate both HTML and Allure reports.

Here’s the merge.config.ts we use:

export default {
    testDir: 'tests',
    reporter: [['html', { open: 'never' }], 
    ['allure-playwright', {
        outputFolder: "allure-results",
      }],
      ['json', { outputFile: 'playwright-report/test-results.json' }]],
  };

You can then use this config file in the merge step as follows:

npx playwright merge-reports --config merge.config.ts ./blob-report

After completing the merging step, let’s look at how sharding improved our test durations in the project.

In our automation project, we divide our tests into different schedules based on tags for example, schedule1, schedule2, and so on. The impact of our sharding structure on these schedules is shown in the table below.

Thanks for the readings 🎭