App & Browser Testing Made Easy

Give your users a seamless experience by testing on 3000+ real devices and browsers. Don't compromise with emulators and simulators

Home Guide How to start with Playwright Debugging

How to start with Playwright Debugging

By Ganesh Hegde, Community Contributor -

Table of Contents

Test Automation is gaining prominence with each passing day, as companies prefer to have a Test Automation Suite for faster software development. There are many frameworks like Selenium, Cypress, Puppeteer, etc. that support test automation. Playwright by Microsoft is another Test Automation framework for web application testing. It is the newest addition to the Headless Browser Testing frameworks in popular use. 

What is a Playwright?

Playwright is a new open-source test automation tool, that is shipped with an Apache license. While Playwright launches browsers in the headless mode by default, it can also be used to run the browsers in headful mode. By passing a flag, when the browser is launched, Playwright can be used to run browsers in headful mode for tests. 

It is gaining traction these days due to its various benefits such as support for multiple languages such as Java, C#, NodeJS, and Python. Playwright tests can be run on browsers like Firefox, Webkit, and Chromium-based browsers. It is compatible with Windows, Linux, and macOS, and can be integrated with major CI/CD servers such as Jenkins, CircleCI, Azure Pipeline, TravisCI, etc.

What is Debugging and why is it important? 

Debugging is the process of finding the root cause of the issue and resolving them. It is vital to the testing process because it:

  • Helps resolve the issues quickly
  • Identify the exact root cause
  • Eliminates complexities
  • Serves as proof to analyze the software quality
  • Provides a way to validate functionality by applying dynamic values

What is Debugging Process?

A debugging process consists of the following steps:

  • Note down the error
  • Assume the error location based on expertize
  • Set the debugger breakpoints
  • Analyze the code during run time step by step.
  • Find the exact location that is causing the issue
  • Fix the line of code which is causing the issue
  • Validate the code, for a successful fix of the error.

How to Debug Playwright Tests?

One of the important features of Playwright is debugging. It allows debugging tests in the following multiple ways:

  1. Playwright Inspector
  2. Playwright Trace Viewer​
  3. Browser Developer Tools​
  4. Visual Studio Code debugger
  5. Verbose API logs​

Debugging using Playwright Inspector

What is a Playwright Inspector?

Playwright Inspector is a GUI tool, which comes with the framework by default and no additional configuration is required to use this tool.

To launch your test with Playwright Inspector mode you need to prefix the test command with PWDEBUG=1 depending on the command-line tool you are using the syntax might differ.

Powershell

$env:PWDEBUG=1

npx run test

Bash

PWDEBUG=1 npx run test

Batch

set PWDEBUG=1

npx run test

Once you enter the command, the UI window also known as Inspector windows opens and shows the line is being executed. You can debug the test line by line using this window.

Debugging using Playwright InspectorPoints to Remember when using PWDEBUG=1 flag:

  1. The browser launches in headed mode by default.
  2. There will be no default time-out.
  3. Playwright Inspector window is split into two parts: the upper part shows your code and the lower part code shows the execution log.
  4. The Playwright provides two options either you can resume the script or you can step over.
  5. If you want to pause the test at the desired line use await page.pause(); in your script.
  6. If you add the await page.pause() playwright automatically opens the Inspector Window even though you have not set the PWDEBUG=1 flag.

Any time, if you don’t want to attach the Playwright inspector, change the PWDEBUG flag to 0 i.e PWDEBUG=0

Recording Scripts using Playwright Inspector Tool

Sometimes you might find it difficult to understand how the locators simulate flows using scripts. Playwright Inspector Tool also provides a command called codegen, Popularly known as Playwright codegen that allows us to record the scripts automatically. 

The codegen is like a recording tool, however, you can use this to generate the complex scripts, and later you can paste it inside our test case.

From the terminal, you can enter the below command to record the tests using Playwright Codegen Tool

npx playwright codegen <webpage_url>

Example:

npx playwright codegen browserstack.com

Once the above command is entered in the terminal, the Playwright inspector window launches. The record button in the inspector window helps to start or stop the recording at any desired point. As the browser opens baseURL you can navigate through the set of actions or workflows. 

Upon completing the recording stop the recording, Save/Copy the recorded script and close the Playwright inspector window.

Debugging using Playwright Inspector

Test Playwright on Real Devices

Debugging Playwright Tests using Browser Developer Tools

DevTools are part of the browser, which enables easy debugging. While most browsers have this functionality, however, the shortcut key might differ from browser to browser. On your browser window right click and choose inspect element. If you are using chromium-based browser you can also choose CTRL +SHIFT + I or F12 to open DevTools windows.

Browser Developer tools are popularly known as DevTools. The browser developer tools are still accessible when running playwright tests.

Some of the actions that can be performed using Browser Developer Tools are:

  1. Inspect DOM Element
  2. Run commands in the browser console.
  3. Check console logs during execution
  4. Verify Network calls/requests in the Network tab

Apart from the actions listed above, any action that can be performed on a normal browser while working with webpages can be done using browser developer tools with Playwright.

Working with Playwright Object in Browser Developer Tools console (Chrome DevTools Console).

The Playwright provides an option to highlight selectors in your browser console with the Playwright object. This is the most useful option, helps debug locators and view the locators rendered during run time.

To utilize this option, Playwright needs to be launched in debug mode as explained above (using PWDEBUG=1 flag). Once you launch the Playwright test with debug mode, the Playwright Object is available in the browser console.

There are many ways to highlight the locators using playwright objects such as:

  1. playwright.$(selector): Highlights the first occurrence of the selector. This is equivalent to a page.$ usage in the script.
  2. playwright.$$(selector): Highlights all occurrences of the selector. This is equivalent to a page.$$ usage in the script.
  3. playwright.inspect(selector): Inspects the selector in the Elements panel.
  4. playwright.locator(selector): Highlights the first occurrence of the locator.
  5. playwright.clear(): Clears existing highlights.
  6. playwright.selector(element): Generates a selector that points to the element.

Example:

playwright.$("a[href='/docs/intro']")

The above command in the browser console highlights the web element containing with locator a[href=’/docs/intro’]

Playwright Debugging using Browser Developer Tools

Debugging Playwright Tests using Visual Studio Code

Playwright works well with Visual Studio Code. If you are familiar with Java or C# and are seeking to debug using IDE breakpoints or the traditional style of debugging by setting and unsetting breakpoints, then Playwright provides the same way of debugging options.

To debug Playwright scripts using VS Code, follow the below steps.

Step 1: Navigate to Visual Studio Code Run Menu > Click on Add Configuration

Configuring Visual Studio for Debugging Playwright

Step 2: Choose NodJS as an Environment

Setting NodeJS as Environment for Playwright Debugging

Step 3: The launch.json will be created inside our project folder automatically. You can check the file under

<Project_Folder>/.vscode/launch.json

JSON File for Playwright Debugging

Step 4: Edit launch.json file and enter the below code to it.

{

    "version": "0.2.0",

    "configurations": [

        {

            "type": "pwa-node",

            "request": "launch",

            "name": "Launch Program",

            "skipFiles": [

                "<node_internals>/**"

            ],

            "program": "${file}",

            "runtimeExecutable": "npm",

            "runtimeArgs": [

                "run-script",

                "test"

            ],

        }

    ]

}

Step 5: Add test command/value to script property in package.json. The package.json should be located in the project root directory (Note: If package.json is not available in your Project root directory, then you can create one using npm init command). Enter the below code to the package.json and save the configuration.

  "scripts": {

    "test": "npx playwright test --headed" 

  }

Step 6: Run with Configuration in Visual Studio Code by following the below steps

  • Set the breakpoint in your code with VSCode IDE
  • Launch the test with Run (Menu)  > Start Debugging or F5
  • The test starts with the debugger attached, the test execution should halt when it hits your breakpoint.

Running Visual Studio for Playwright Debugging

Debugging Playwright Tests with Trace Viewer

Trace Viewer is another useful functionality of playwright debugging. Trace Viewer is a GUI tool that shows the traces recorded during test execution. Trace viewers can be opened using CLI or on the browser.

Recording Trace in Playwright

To record Trace, you need to configure it in the Global config file, and then follow these steps:

Step 1: Create a Global Playwright Config File i.e playwright.config.ts

Step 2: Place the playwright.config.ts under the Project root directory

Step 3: Add the below code in it

// playwright.config.ts

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

const config: PlaywrightTestConfig = {

  use:{

    trace:'on'

  },

};

export default config;

In the above code, the trace option has on value, likewise, you can provide different values from the list of available options for trace

  • ‘off’ – Do not record a trace.
  • ‘on’ – Record a trace for each test.
  • ‘retain-on-failure’ – Record a trace for each test, but remove it from successful test runs.
  • ‘on-first-retry’ – Record a trace only when retrying a test for the first time.

Once you run the test after configuring the trace option to the global config file. Trace will be recorded and stored in the test-results directory.

Traces of your tests will be recorded action-wise. Each action contains

  • action snapshots,
  • action log,
  • source code location,
  • network log for this action

Viewing Traces in Playwright

You can view the recorded Traces by following the below steps:

Step 1: Run/Execute your test

Step 2: Look for traces.zip inside your test-results folder

Step 3: From CLI you can enter the path to trace file in the following format 

npx playwright show-trace <path_to_trace.zip_directory>/trace.zip

For Example:

npx playwright show-trace test-results\tests-example-basic-test\trace.zip

Step 4: Open trace.zip from the browser (Optional). Navigate to https://trace.playwright.dev/ and then drag and drop the trace.zip folder as seen below

Debugging Playwright Tests using Trace Viewer

Debug tests with Playwright Verbose Logging

Amidts the several debugging options provided by Playwright, Verbose logging is another way to debug Playwright tests where the QA can see the verbose logs and analyze the scripts.

Enabling Verbose Logging in Playwright
The enabling of verbose logging depends on which type of CLI/Terminal you are using.

Enable Verbose Logging with Bash

DEBUG=pw:api npx playwright test

Enable Verbose Loggging with Powershell

$env:DEBUG="pw:api"
npx playwright test

Enable Verbose Logging with Batch

set DEBUG=pw:api
npx playwright test

Once you enable the Verbose Log, Playwright continuously feeds the logs to the command line so you can see what’s happening during the script execution.

Debugging Playwright using Verbose Logging

 

Conclusion

While Playwright offers different debugging options for tests, it is upto you to choose the most suitable way to debug your tests for delivering a high-quality web application. No matter which debugging option you opt for, it is always crucial to take the real user conditions into account for a seamless user experience. This is only possible by testing on real devices.

BrowserStack offers 3000+ browser-device combinations that you can use to run your Playwright tests with a simple integration with BrowserStack Automate. Their real device cloud is secure and apt for test automation as it can be integrated with most of the CI/CD pipelines like Jenkins, Travis CI, CircleCI, Gitlab, Azure, Bamboo, etc. and help Agile teams run Parallel tests for a faster and more accurate testing experience.

Run Playwright Tests on Real Device Cloud

Tags
Automation Testing Website Testing

Featured Articles

Playwright Framework Tutorial: Learn Basics and Setup

How to Perform Visual Regression Testing Using Playwright

Playwright vs Cypress: A Comparison