Playwright is a powerful test automation tool that is gaining popularity in the software development world. The tool allows automating browser tasks and testing web applications. It offers great performance and efficiency in terms of performing automation testing activities. With automation comes the need to ensure seamless execution of the scripts. And for that to happen, Playwright debugging is of utmost importance.
In this article, we will cover the tips and techniques to debug that will help you troubleshoot the issues and improve the automation scripts.
What Is Playwright Debugging?
Playwright debugging is the process of identifying and fixing failures in automated browser tests created with the Playwright framework. It involves analysing test execution, browser interactions, selectors, network activity, and timing issues to determine why a test fails.
Playwright debugging uses tools like the Playwright Inspector, Trace Viewer, debug logs, and browser developer tools to inspect test steps, reproduce errors, and diagnose issues such as element not found errors, flaky tests, navigation timeouts, and authentication failures. This process improves test reliability, failure analysis, and automation stability.
Why Debugging Playwright Tests Is Critical for Test Stability
Debugging is an important aspect of the software development lifecycle. It helps in identifying and resolving the issues in the code. Key pointers highlighting the importance of debugging are as-
- Ensure-your-app-works-perfectly-under-real-world-scenarios-on-real-devices.webp
- It helps in finding out the errors in the code and easy resolution. Debugging acts as the first line of defence, using which we can ensure that our code is not vulnerable to crashes, data corruption, or security issues.
- Debugging helps in maintaining Quality Assurance within a project by helping identify issues that can lead to inconsistency in the functionality, performance issues, or other glitches in user interactions. If these are identified at the right time, the overall success of the project can be assured.
- Although debugging might take some time initially, in the long run, it reduces the overhead of time and resources. It reduces the need for rework at later stages of the project, hence proving to be a budget and resource-friendly activity.
- Debugging makes sure that the software is robust, secure and compatible with the changing technology. Now that we understand the importance of debugging in the software development lifecycle, let us look at the challenges that you may face while you use Playwright Debug.
Common Playwright Test Failures and How to Diagnose Them
When you start automating, you will come across various scenarios where your scripts will fail. These failures might look confusing, as you may notice that the scripts are logically correct, but due to some minor issue, like delays in page loading, session authentication, etc. Let us look at some common challenges that you might encounter, and then in the next section, we will discuss elaborately on handling them using Playwright Debug.
Element Not Found: Errors in Playwright
While working with web applications, you will have to perform browser interactions. For these browser interactions, the element should be displayed so that the action corresponding to it can be taken. Element not found error is one of the most common and repeated challenges that you may face. It becomes very important to tackle such a case to handle the abrupt failure of the automation script.
Page Load and Navigation Timeout Issues
When working with complex applications, you will come across scenarios where you will have to interact with multiple pages or even work with single-page applications. Playwright execution may fail as it might not be able to detect page loading or proper navigation.
Authentication Failures
A lot of automation scenarios might include the authentication of users. If proper flow is not used for the automation scripts, the chances of failures increase, leading to inconsistency in the behaviour. Debugging helps in identifying gaps in such scenarios.
The above stated challenges are just some of the examples of how you may face failures in your automation script. In order to eliminate script failures due to such basic mistakes, playwright debugging can come to the rescue. In the next section, we will discuss the different ways through which you can use Playwright Debug.
Methods to Debug Playwright Tests
We have been talking about debugging since the start of this article.
Let us first see how we actually debug the code. Steps involved in debugging are:
Capture the error in the code and analyse the area of the code causing the error.
- Set breakpoints for the debugger.
- Execute the code step by step to analyse the code while it runs.
- Find the exact code due to which the error is coming.
- Once the exact location of the issue is identified, the code is fixed and retested to ensure that the error is no longer present. These steps can be performed in order to rectify the faulty code using debug. Playwright comes with different ways to debug the code, which makes debugging an important feature for Playwright. Let us walk through the different ways offered by Playwright to debug the code.
Debugging Playwright Tests in VS Code
If you have worked with tools like Eclipse IDE for programming, you might be familiar with using breakpoints to debug the code in events of failures. Playwright also provides a similar way of debugging using Visual Studio Code. You need to follow the steps below to do so:
Go to the run menu of VS Code and click on Add Configuration.
Playwright Debugging using Visual Studio
Select Node.js from the available options.
You will see that the launch.json file is created automatically in the project directory.
Ensure-your-app-works-perfectly-under-real-world-scenarios-on-real-devices.webp
image8 1
- Next, we need to edit the launch.json file by adding code as shown below:
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"skipFiles": [
"/**"
],
"program": "${file}",
"runtimeExecutable": "npm",
"runtimeArgs": [
"run-script",
"test"
],
}
]
}
- Now, we need to add the package.json file, which should be present in your project root directory. We will add the test command to the scripts property. Once you do that, as shown below, you need to save the configurations. Note that if the package.json file is not available at the root, you will have to create one and then do the edits.
"scripts": {
"test" : "npx playwright test --headed"
},
6 . Now, to execute the set configurations, you will first set the breakpoint in your tests in VS Code as shown below:
image2 1
- Now execute the test by clicking on Start Debugging from the Run menu.
- You will see that the test starts executing with the debugger opened, and it will halt executing when it reaches the breakpoint.
Debugging with Playwright Inspector
Playwright Inspector is a GUI tool that can be used to debug and record your Playwright scripts. To use the playwright inspector tool, you need to use the following command:
Windows(using cmd):
set PWDEBUG=1
npm run test
MAC OS/Linux:
PWDEBUG=1 npm run test
Once you execute the command, you will see that the chromium is launched along with Playwright Inspector, with the script pausing at the first statement. There are two points that you need to note:
The Playwright Inspector opens in headed mode by default.
The default timeout is set to 0, which means that there is no timeout.
The playwright inspector will look like as shown below-
Playwright Inspector
The playwright inspector shows you the code as well as the logs of the execution. It also allows you to either resume the script execution or step over a step. If you intend to pause at a specific step in your script, you can use the await page.pause() command. If you use this command, the playwright inspector would automatically open irrespective of whether you use the PWDEBUG=1 flag. Additionally, if you do not wish to open the playwright inspector, you may set the flag to 0, i.e. PWDEBUG=0.
Recording and Inspecting Selectors with Inspector
You can also use the Playwright Inspector to record scripts in scenarios where you are facing issues while performing certain actions or capturing locators. Playwright inspector helps in recording the scripts using another command, i.e., the playwright codegen. You need to execute the below command from the terminal, and the playwright inspector will be launched, where you can record the scripts.
You can also use the Playwright Inspector to record scripts in scenarios where you are facing issues while performing certain actions or capturing locators. Playwright inspector helps in recording the scripts using another command, i.e., the playwright codegen. You need to execute the below command from the terminal, and the playwright inspector will be launched, where you can record the scripts.
npx playwright codegen
The record button on the inspector allows you to record the actions you are performing. Once you have recorded the actions, you can save the script for use when desired. This feature allows for an easy entry point for developers and testers to start automating their scripts using Playwright.
Using Browser DevTools to Debug Playwright Tests
Browser Developer Tools, or the Dev Tools, are provided by the browsers, which allow you to perform certain actions like inspecting the web elements, executing commands on the browser console, checking network requests and the console logs. The Dev Tools are very helpful in understanding the actions performed on the web pages and seeing how the response is in real-time.
Playwright helps in debugging locators by highlighting the selectors in the browser console using the Playwright object. To make use of the feature, you need to launch Playwright in debug mode just like we did for Playwright Inspector. Once you launch Playwright in debug mode(PWDEBUG=1), you will see that the Playwright object is available in the console. Note that you will have to open up the dev tools, and then you will notice that the locator is highlighted(the one where the breakpoint was applied) on the browser with the details as shown below-
Using Browser DevTools to Debug Playwright Tests
Once the playwright object is available, you can also use one of the many ways to highlight the locators-
playwright.$(selector) – Highlight the selector(first occurrence).
playwright.$$(selector) – Similar to playwright.$(selector), but it returns all matching elements.
playwright.inspect(selector) – Inspects the selector in the elements panel.
playwright.locator(selector) – Highlight the locator(first occurrence).
playwright.selector(element) – Generates a selector for the element provided.
playwright.clear() – Clears the highlight.
Debugging Failures with Playwright Trace Viewer
Trace Viewer is a GUI tool that helps in exploring the playwright traces of the recorded tests. You can use the trace viewer using the browser or the command line interface. First, you need to configure the global config file to enable recording of traces.
Create a global config file- playwright.config.ts, and place it in the project root directory.
Debugging Failures with Playwright Trace Viewer
- Next, add the code below to the file
// playwright.config.ts
import { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
use:{
trace:'on'
},
};
export default config;
In the code, we have kept the value of trace as “on”, which will help record the trace for each test. Other than this, you can also select from other options for trace-
off, does not record traces.
retain-on-failure, records traces for each test, but removes them from the tests that are successful.
on-first-retry, records traces only when retrying for the first time.
These traces are stored in the test-results directory. These traces are recorded action-wise. Each of these actions has the snapshots, logs, source code location and its corresponding network log.
Once you have executed the tests and the traces are recorded, you can view them in the test-results directory in the trace.zip file.
Playwright Demo
Now there are two ways to open this trace file- using the terminal & through the browser. Let us see how we view the file using both ways-
Using Terminal
You can view the trace file by using the command below in the terminal-
npx playwright show-trace
Once you run this command, the Playwright Trace Viewer UI will open up to display all the actions and the metadata of the run. You will be able to see the snapshots along with the logs, errors(if any) and other relevant details.
Using Browser
To open the zip file from the browser, you need to navigate to https://trace.playwright.dev/ and drop the zip file. Once that is done, you will be able to see the traces of all the details of the actions in the test.
Playwright Using Browser
Using Playwright Debug Logs and Verbose Mode
Another way to debug using Playwright is by using Verbose Logging. This feature helps the testers to analyse the scripts through the logs. You can enable verbose logging using the command in the terminal.
Bash:
DEBUG=pw:api npx playwright test
Powershell:
$env:DEBUG=”pw:api”
npx playwright test
Batch:
Set DEBUG=pw:api
npx playwright test
Once you use the command for execution, you will notice that the logs are continuously fed into the terminal, displaying the execution steps.
Conclusion
Debugging is an important aspect in developing test scripts as it helps to eliminate issues in the code. It ensures that the code works seamlessly in the dynamic work environment where different issues like the element not found, page navigation issues or authentication issues may pop up. The playwright provides multiple ways in which we can perform the debugging. Right from using Visual Studio Code debugging to Trace Viewer, each of these ways offers a different view of the debugging option. Playwright Inspector can be used in conjunction with the browser developer tools to yield maximum output. Verbose logging, on the other hand, provides comprehensive logging for each action using the playwright test script. If you intend to get a comprehensive debugging report of the test execution, Trace Viewer will yield maximum benefits. Now that you know the different ways to use Playwright Debugging, you can select whichever way suits you best for your requirements.
This blog is originally published at TestGrid
Top comments (0)