A guide to human readable reports in Playwright with test.step, expect, and annotations

Ben Fellows

Human readable test reports are critical to the quality assurance (QA) testing process as they allow for clear communication of the results of a test. 

Without clear and detailed information about what has failed and why, it can be difficult for those involved in the testing process to effectively understand and address any issues that may have arisen. 

This can lead to a slower and more inefficient testing process, as well as potentially lower quality products.

Additionally, human readable test reports are especially important when working with a team, as they allow for clear communication between team members and can help to ensure that all parties are on the same page. 

Without clear and detailed reports, it can be difficult for team members to understand the status of a project and what needs to be done next.

Unfortunately, out of the box, playwright reports may not always be as human readable as desired. While they do provide some information about the results of a test, they may not include all of the necessary context and detail to fully understand the issue. 

However, with a little extra effort, it is possible to significantly improve the human readability of playwright reports and make the testing process more efficient and effective. 

By including annotations, steps, and custom error messages, as well as carefully considering the formatting and layout of the report, it is possible to create test reports that are both comprehensive and easy to understand.

The three most important playwright features for human readable reports are:

  1. test.step: This feature allows for the breakdown of individual actions within a test and grouping of relevant steps together, creating a more detailed and comprehensive understanding of the test.

  1. custom expect messages: Custom error messages inserted using expect statements allow for immediate understanding of what has failed and potentially why it may have failed, improving the efficiency of the debugging process.

  1. annotations: Annotations provide additional context for each test case and can be used to describe the purpose or expected outcome of the test, improving the overall understanding of the report.

Download our Automation ROI Formula

Test.Step - Providing Clear Stages to Your Tests

Making Reporting Clearer

Test.step is a useful feature in playwright that helps to improve the human readability of test reports by allowing for the breakdown of individual actions within a test and grouping of relevant steps together. This helps to provide a clearer understanding of what is happening within the test and can aid in debugging if an issue arises. 

One of the key benefits of test.step is that it updates the test steps section of the report to give a much clearer roadmap of what the test is covering and what steps it failed on. This can be especially helpful in identifying the root cause of a failure and can save time and effort in the debugging process.

Example of Playwright report without test steps
Example without steps

Example of Playwright report without test steps
Example with steps

How to Implement Test.Step

Test.step can be used: 

  1. Within Methods
  2. Within Tests

Using test.step within Playwright methods

In playwright, steps can be added to functions in order to provide a more detailed and comprehensive understanding of the actions being performed. Steps allow for the breakdown of individual actions within a function and can be used to describe the specific steps being taken.

For example, instead of simply stating that a function navigates to a certain website, steps can be used to list the specific actions involved, such as opening the browser and entering the URL. This helps to provide a clearer understanding of what is happening within the function and can aid in debugging if an issue arises.

Example Code

Using test.step within Playwright test

When test.step is used at the test level, it often serves to group multiple methods together under a described action or series of actions.

What is fantastic is that this then will automatically nest the method steps in the reports. 

For example, if a test includes three methods, each with its own set of steps, the steps at the test level will nest the steps from each of the individual methods within the report. 

This helps to provide a clearer understanding of the overall flow of the test and can be especially helpful when working with a team, as it allows for clear communication between team members and can help to ensure that all parties are on the same page.

Example Code

Download our Automation ROI Formula

Custom Expect Messages - Human Readable Error Messages

In playwright, when an expect statement within a test fails, the message included within the expect statement is displayed as an error in the report. 

This allows for immediate understanding of what has failed and potentially why it may have failed, improving the efficiency of the debugging process.

For example, if a test includes an expect statement that checks for the presence of a certain element on a webpage and that element is not found, the message included within the expect statement will be displayed as an error in the report. 

This can be especially helpful when working with a team, as it allows for clear communication between team members and can help to ensure that all parties are on the same page.

It is important to note that this "custom error" message does not exist for actions functions. In the case of an action function failing, the error message displayed in the report will be the default message provided by playwright. This default message may not always include as much context and detail as a custom error message, making it potentially more difficult to understand the issue and address it.

This is why we recommend leading your actions with expect statements whenever possible to ensure that you have the most detailed and helpful error messages available to you when debugging.

teps can be added to functions in order to provide a more detailed and comprehensive understanding of the actions being performed. Steps allow for the breakdown of individual actions within a function and can be used to describe the specific steps being taken.

For example, instead of simply stating that a function navigates to a certain website, steps can be used to list the specific actions involved, such as opening the browser and entering the URL. This helps to provide a clearer understanding of what is happening within the function and can aid in debugging if an issue arises.

Example Code

Using Annotations to Provide Context

One of the next key features of playwright that can greatly improve the human readability of test reports is the use of annotations. Annotations provide additional context for each test case and can be used to describe the purpose or expected outcome of the test, helping to improve the overall understanding of the report.

Example of Playwright annotations

To add annotations to a test case in playwright, you can use the test.info().annotations.push method. This method allows you to add custom annotations to a test case, providing additional context and detail to the report.

For example, let's say that you have a test case that checks for the presence of a certain element on a webpage. You can use test.info().annotations.push to add an annotation that describes the purpose of the test and what you expect to see. This annotation could be something like "Verify that the login button is displayed on the homepage" or "Expect to see the search bar on the page".

Example Code

Download our Automation ROI Formula

Hidden Gem - Use Arguments in Test Steps & Expect Messages

One of the lesser known but highly effective features of playwright is the ability to use arguments to pass test data directly into test steps and custom expect messages. This feature can have a major impact on the human readability of test reports, as it allows for more specific and detailed messaging that is not generic.

For example, rather than simply stating that a test "couldn't find a book", the use of arguments can enable the test step to literally include the name of the book that could not be found. Instead of a generic message, the test step could be written as "couldn't find the book: Harry Potter". This level of specificity can provide much more context and detail to the report, improving the overall understanding and organization of the testing process.

The use of arguments can also be helpful in the event of a test failure. By including specific data within the expect message, it is possible to more accurately and effectively communicate what has failed and potentially why it may have failed. This can be especially useful when working with a team, as it allows for clear communication between team members and can help to ensure that all parties are on the same page.

In addition to improving the messaging in the event of a test failure, the use of arguments can also help to improve the overall organization and structure of the report. By allowing for the inclusion of specific data within the test steps, it is possible to create a more comprehensive and understandable report that can be easily accessed and understood by all.

Example Code

Other Helpful Info for Human Readable Reports

test.describe - limited use

In playwright, test.describe can be used to provide context around a group of tests. This can be especially helpful when working with a team, as it allows for clear communication between team members and can help to ensure that all parties are on the same page.

However, it is important to note that test.describe is severely limited in where it displays in the report. It is only displayed at the beginning of the test case name in the report, which can make it difficult to reference and understand in the context of the overall report. This limitation can make test.describe much more useful in the code than in the final report.

Test names

It is worth pointing out that naming your tests is also an important factor in achieving human readability in test reports. While it may seem like a little obvious, the names of your tests can greatly impact the overall understanding and organization of the report.

When naming your tests, it is important to choose names that are clear and concise, and that accurately describe the purpose or expected outcome of the test. This will make it easier for all parties involved in the testing process to understand what each test is covering and what steps it may have failed on.

In addition to choosing clear and concise names, it is also a good idea to use a consistent naming convention throughout your tests. This can help to further improve the organization and structure of the report and make it easier to navigate and understand.

Consistent Code Formatting - camelCase

As we have discussed, there are a number of different techniques and features that can be used to improve the human readability of test reports in playwright. However, it is also important to consider the importance of using a consistent formatting convention when working with a large number of tests.

One common formatting convention that can be especially useful in this context is the use of camelCase. CamelCase involves the use of capital letters to denote the beginning of each new word in a compound word or phrase, and is often used to improve the readability and clarity of text.

For example, rather than writing "find element by id", you could use camelCase to write "findElementById". This simple formatting convention can greatly improve the overall readability and organization of the code, making it easier to navigate and understand.

Using a consistent formatting convention such as camelCase can be especially helpful when working with a large number of tests, as it can help to create a more structured and organized codebase. This, in turn, can greatly improve the human readability of the report and make the testing process more efficient and effective.

Download our Automation ROI Formula

Conclusion

In conclusion, human readable test reports are an essential component of the QA testing process, as they allow for clear communication of the results of a test and facilitate effective debugging and problem solving. Without clear and detailed reports, it can be difficult for those involved in the testing process to understand and address any issues that may have arisen, leading to a slower and less efficient testing process.

Fortunately, playwright offers a number of features that can help to improve the human readability of test reports, including test.step, custom expect messages, and annotations. By utilizing these features and carefully considering the formatting and layout of the report, it is possible to create test reports that are both comprehensive and easy to understand.

In addition to the features provided by playwright, it is also important to consider the naming of tests and the use of a consistent formatting convention, such as camelCase. These small details can make a big difference in the overall readability and understandability of the report, helping to reduce confusion and improve the efficiency of the testing process.

Overall, by prioritizing human readable test reports, it is possible to create a more efficient and effective QA testing process that leads to higher quality products.

More from Loop

Get updates on Loop's best content

Stay in touch as we publish more great Quality Assurance content!