Shared steps

Configuration

This package contains shared Step definitions which we want to share between test suite repositories.

The cucumber.mjs configures Cucumber to look for step definitions from e2e.support package by including it in the import list:

{
  ...
  import: [
    'src/**/*.ts',
    'features/**/*.steps.ts',
    './node_modules/@fry-it/e2e.support/dist/steps'
  ],
  ...
}

Cucumber expressions & Parameter types

Steps are defined using the Cucumber expressions (see documentation). You can find the Cucumber expression in the first column of the Step definitions table below. An example of the Cucumber expression from the content-assertions.steps.ts could be:

Then Admin sees "Reset exam day" link on the page    // Step as used in the feature file
Then {actor} sees {string} {aria_role} on the page   // Cucumber expression of step definition

The curly brackets {} denote parameter(s) of the step. The parameter can be of several types allowing authors to express what kind of value is expected in the step implementation.

[!IMPORTANT]
The step is matched by the Cucumber expression including the parameter(s) type! If you provide a number as a parameter into a step expecting the string or omit/add quotes the step won’t match and will be marked as not implemented.

Parameter types

Text between curly braces reference a parameter type. Cucumber comes with the built-in parameter types and e2e.support adds additional custom types:

Parameter Type	Description
{int}	Matches integers for example 71 or -19.
{float}	Matches floats, for example 3.6, .8 or -9.2.
{word}	Matches words without whitespace, for example banana (but not banana split).
{string}	Matches single-quoted or double-quoted strings, for example “banana split” or ‘banana split’ (but not banana split). Only the text between the quotes will be extracted. The quotes themselves are discarded. Empty pairs of quotes are valid and will be matched and passed to step code as empty strings.
{}	Matches anything.
{actor}	Actor who is performing the step. This matches a single word, e.g. Admin, EbelJudge, JimJones but not “Jim Jones”.
{aria_role}	Role of the UI element on the page, no quotes. Allowed values: ‘button’, ‘combobox’, ‘heading’, ‘link’, ‘textbox’
{fixture}
{numbers}	Type allows to use a list of numbers separated by commas.
{ordinal}	Type allows to use 1st, 2nd… etc ordinal numbers where position is required.
{path}
{strings}	Type allows to use a list of strings separated by commas.

Step definitions

Step	Arguments	Description	Example
Then 'the {string} page has no accessibility violations'	pageID - is the name of the page, e.g. Home	Used to check the accessibility of the current page using AXE library The step will fail if there are any accessibility violations and attach the report as plain text in the report.	Then the "Home" page has no accessibility violations

annotations (annotations.steps.ts)

Screenshot Annotation steps

These steps are used to add annotations, element highlighting and interaction highlighting to the page under the test.

Users:

Developers:

These steps use support for annotations in the annotations/* folder and code in the FryWorld to inject the necessary JavaScript into the page.

Step	Arguments	Description	Example
When '{actor} adds annotation {string} at {string}'	actor - Actor used to identify the browser context eg. Admin, Alice, ... markdown - Markdown content to be added as annotation location - Location where the annotation should be added	Used to add short annotation to the page at a specific location	When Admin adds annotation "Click Save button" at "top-left"
When '{actor} highlights {aria_role} with label {string}'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to	Then Admin pauses test
When '{actor} highlights element using locator {string}'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to	Then Admin pauses test
When '{actor} removes all annotations'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to	Then Admin pauses test

api (api.steps.ts)

API support steps

These steps are used to manage authentication for the product APIs allowing writing feature files interacting with the API.

Step Arguments Description Example

Step	Arguments	Description	Example
Given '{actor} created API credentials for {string} application'	actor - is the name of the actor, e.g. Admin.	Used to create oAuth application on the Product and extract the credentials This step assumes that the user is already logged in and has the necessary permissions to manage the oAuth applications. It creates the oAuth application or credentials and streams them to a file for later use. This step is only necessary to be run once per Feature file as we usually delete database at the beginning of the Feature file.	Given Admin created API credentials for 'e2e' application
Given '{actor} exchanged API credentials for {string} application for token'	actor - is the name of the actor, e.g. Admin.	Used to exchange the oAuth credentials for the token This step assumes that the user has already created the oAuth application using step above. It exchanges the credentials for the token and initializes the `FryWorld.apiContext` which is used to make the API requests. This step can should be run in each Scenario where the API requests are needed.	Given Tests exchanged API credentials for 'e2e' application for token
When '{actor} sends a API request {string} with payload'	actor - is the name of the actor, e.g. Admin.	Used to perform a generic API call with some kind of payload This step uses the `FryWorld.apiContext` to send a API request to specified endpoint. The format for endpoint URL is `METHOD URL`. The payload is provided as a DocString in JSON format which is passed directly to the backend without any processing.	When E2E sends a API request 'POST /rest/manage/users' with payload

Given '{actor} created API credentials for {string} application'

actor - is the name of the actor, e.g. Admin.

Used to create oAuth application on the Product and extract the credentials

This step assumes that the user is already logged in and has the necessary permissions to manage the oAuth applications. It creates the oAuth application or credentials and streams them to a file for later use.

This step is only necessary to be run once per Feature file as we usually delete database at the beginning of the Feature file.

Given Admin created API credentials for 'e2e' application

Given '{actor} exchanged API credentials for {string} application for token'

actor - is the name of the actor, e.g. Admin.

Used to exchange the oAuth credentials for the token

This step assumes that the user has already created the oAuth application using step above. It exchanges the credentials for the token and initializes the FryWorld.apiContext which is used to make the API requests.

This step can should be run in each Scenario where the API requests are needed.

Given Tests exchanged API credentials for 'e2e' application for token

When '{actor} sends a API request {string} with payload'

actor - is the name of the actor, e.g. Admin.

Used to perform a generic API call with some kind of payload

This step uses the FryWorld.apiContext to send a API request to specified endpoint. The format for endpoint URL is METHOD URL.

The payload is provided as a DocString in JSON format which is passed directly to the backend without any processing.

When E2E sends a API request 'POST /rest/manage/users' with payload

auth (auth.steps.ts)

Authentication and logout

These steps provide means for logging in and out from each of our products as well as re-using the authentication state to improve execution speeds of the test suite.

Users: In order to login each test suite contains a Fixture setting up the users for testing purposes. Authors are therefore aware of the username/password combinations required to login.

The test suite also supports the pre-defined users (actors) which are defined in the src/cucumber-hooks.ts file.

Step	Arguments	Description	Example
Given '{actor} logged into Booking/Apply'	actor - is the name of the actor, e.g. Admin.	Used to login a pre-defined user (actor) into risr/apply Short, convenient version of the login step which uses pre-defined users in each test suite. The actors are defined in the `src/cucumber-hooks.ts` file.	Given Admin logged into Booking
Given '{actor} logged into Booking/Apply as {string} using {string} password'	actor - is the name of the actor, e.g. Admin.	Used to login into risr/apply using username and password This step allows login using username/password combination for cases where pre-defined users are not available or it would be impractical to use them (eg. temporary users). For majority of testing the short hand step using pre-defined role is preferred.	Given Admin logged into Apply as "james" using "passw0rd!"
Given '{actor} logged into Kaizen/Advance'	actor - is the name of the actor, e.g. Admin.	Used to login a pre-defined user (actor) into risr/advance Short, convenient version of the login step which uses pre-defined users in each test suite. The actors are defined in the `src/cucumber-hooks.ts` file.	Given Admin logged into Kaizen
Given '{actor} logged into Kaizen/Advance as {string} using {string} password'	actor - is the name of the actor, e.g. Admin.	Used to login into risr/advance using username and password This step allows login using username/password combination for cases where pre-defined users are not available or it would be impractical to use them (eg. temporary users). For majority of testing the short hand step using pre-defined role is preferred.	Given Admin logged into Advance as "james" using "passw0rd!"
Given '{actor} logged into Practique/Assess'	actor - is the name of the actor, e.g. Admin.	Used to login a pre-defined user (actor) into risr/asses Short, convenient version of the login step which uses pre-defined users in each test suite. The actors are defined in the `src/cucumber-hooks.ts` file.	Given Admin logged into Practique
Given '{actor} logged into Practique/Assess as {string} using {string} password'	actor - is the name of the actor, e.g. Admin.	Used to login into risr/asses using username and password This step allows login using username/password combination for cases where pre-defined users are not available or it would be impractical to use them (eg. temporary users). For majority of testing the short hand step using pre-defined role is preferred.	Given Admin logged into Assess as "james" using "passw0rd!"
Given '{actor} authentication credentials are stored for reuse'	actor - is the name of the actor, e.g. Admin.	Used to store authentication credentials of the logged in user for re-use This step saves authentication information for the `actor` which allows to skip login screen and redirects in following scenarios. The login steps check for an existence of the authentication state for the `actor` and if such state is found authentication is re-used bypassing the login process.	Given Admin authentication credentials are stored for reuse
When '{actor} logs out from Advance/Apply/Assess'	actor - is the name of the actor, e.g. Admin.	Used to log out user from Advance/Apply/Asses	When Admin logs our from Advance

clipboard (clipboard.steps.ts)

Step	Arguments	Description	Example
When '{actor} copies content of {string} to clipboard'		Used to store the content of a locator in the clipboard	undefined

content-assertions (content-assertions.steps.ts)

Step	Arguments	Description	Example
Then '{actor} sees {string} text on the page'	actor - is the name of the actor, e.g. Admin. string - is the text to verify visibility for	Used to verify existence of a text on the page Matches the 1st partial text, case insensitive anywhere on the page.	Then Admin sees "Lorem ipsum" text on the page
Then '{actor} sees exactly {string} text on the page'	actor - is the name of the actor, e.g. Admin. string - is the text to verify visibility for	Used to verify existence of an exact text on the page Matches exact text, case sensitive, anywhere on the page. The text must be present on the page only once.	Then Admin sees exactly "Lorem ipsum" text on the page
Then '{actor} does not see {string} text on the page'	actor - is the name of the actor, e.g. Admin. string - is the text to verify visibility for	Used to verify that a text is not visible on the page. Ensures that the text, case insensitive, is not visible anywhere on the page.	Then Admin does not see "Lorem ipsum" text on the page
Then '{actor} does not see exactly {string} text on the page'	actor - is the name of the actor, e.g. Admin. string - is the text to verify visibility for	Used to verify that an exact text is not visible on the page. Ensures that the exact text, case sensitive, is not visible anywhere on the page.	Then Admin does not see exactly "Lorem ipsum" text on the page
Then '{actor} sees {string} {aria_role} on the page'	actor - is the name of the actor, e.g. Admin. string - is the label of the element to verify visibility for aria_role - is the element type specified by ARIA role	Used to verify existence of an element with specific ARIA role Matches the 1st exact label (2nd parameter), case insensitive anywhere on the page.	Then Admin sees "Reset exam day" link on the page
Then '{actor} does not see {string} {aria_role} on the page'	actor - is the name of the actor, e.g. Admin. string - is the label of the element to verify visibility for aria_role - is the element type specified by ARIA role	Used to verify that an element with specific ARIA role is not visible on the page. Matches the 1st exact label (2nd parameter), case insensitive anywhere on the page.	Then Admin does not see "Reset exam day" link on the page
Then '{actor} sees disabled {string} {aria_role} on the page'	actor - is the name of the actor, e.g. Admin. string - is the label of the element to verify visibility for aria_role - is the element type specified by ARIA role	Used to verify existence of an disabled element with specific ARIA role	Then Admin sees disabled "Reset exam day" button on the page

debugging (debugging.steps.ts)

Step Arguments Description Example

Step	Arguments	Description	Example
Then '{actor} pauses test'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to pause the test execution This is useful when you want to debug the test execution using `npm run test:debug` and want to stop test at certain point and open the Playwright inspector.	Then Admin pauses test
Then '{actor} waits for {int} second(s)', *{ timeout: 250 1000 }**	actor - Actor used to identify the browser context eg. Admin, Alice, ... seconds - Number of seconds to wait	Used to wait for certain amount of time This step should be used as a last resort when you want to wait for some between two steps. Usually this means a bad UI or test design. If you need to wait for certain operation to finish, you should be using the actual UI which expresses the state of the operation and wait for that UI element to appear/disappear/change.	Then Admin waits for 1 second

Then '{actor} pauses test'

actor - Actor used to identify the browser context eg. Admin, Alice, ...

Used to pause the test execution

This is useful when you want to debug the test execution using npm run test:debug and want to stop test at certain point and open the Playwright inspector.

Then Admin pauses test

Then '{actor} waits for {int} second(s)', { timeout: 250 * 1000 }

actor - Actor used to identify the browser context eg. Admin, Alice, ...
seconds - Number of seconds to wait

Used to wait for certain amount of time

This step should be used as a last resort when you want to wait for some between two steps. Usually this means a bad UI or test design.

If you need to wait for certain operation to finish, you should be using the actual UI which expresses the state of the operation and wait for that UI element to appear/disappear/change.

Then Admin waits for 1 second

dialog (dialog.steps.ts)

Step	Description	Example
Then '{actor} sees {string} dialog'	Used to verify dialog with a specific title is visible Examples: Then User sees “Confirm payment” dialog	undefined
Then '{actor} sees dialog with {string} message'	Used to verify dialog with Message/Content Examples: Then User sees dialog with “Do you want to confirm payment?” message	undefined
Then '{actor} sees dialog {string} with {string} message'	Used to verify dialog with both Title and Message/Content Examples: Then User sees dialog “Confirm payment” with “Do you want to confirm payment?” message	undefined
When '{actor} clicks {string} button in the {string} dialog'	Used to click on the Button within a Dialog with specific title This step will wait for the dialog to appear on the screen and also wait for the dialog to disappear after the click. Examples: Then User clicks “Confirm” button in the “Confirm payment” dialog	undefined

filesystem-compression (filesystem-compression.steps.ts)

Steps for filesystem dealing wit compression and decompression

At the moment we only support unzipping the ZIP files. The files are extracted into the same folder as the source file, without an extension or to the specified folder.

For developers:

The state of handling the ZIP files in the Node.js is a bit tricky. Most of the libraries are old and unmaintained. We are using the extract-zip which is a wrapper around the yauzl library. It is semi-maintained unfortunately. The yauzl is a bit old but reasonably stable and well tested so at least the foundation is good.

https://github.com/max-mapper/extract-zip https://github.com/thejoshwolfe/yauzl

This seems to be reasonably robust solution for the E2E use case. It currently does not have security issues (as of 04/04/2024) but of course given it’s low maintenance efforts, it might get a bit tricky in the future.

Step	Arguments	Description	Example
When '{actor} extracts file {string}'	path - The path of the file to extract	Extracts a ZIP file to the folder in the same location	When Admin extracts file "path/to/the/file.zip"
When '{actor} extracts file {string} to {string}'	source - The path of the source file to extract target - The path of the target directory to extract the file	Extracts a ZIP file to the folder to the specified location	When Admin extracts file "path/to/the/file.zip" to "path/to/the/target/dir"

filesystem (filesystem.steps.ts)

Steps for filesystem assertions and operations

Most of the steps here are quite low level and their use most likely require a special use case.

Step	Arguments	Description	Example
Given 'folder {string} has been created'	path - The path to the folder to create	Creates a folder on the filesystem	Given folder "path/to/folder" is created
When '{actor} copies file/folder {string} to {string}'	source - The path to the file/folder to copy target - The path to the destination folder	Copies file/folder to a new location If we’re copying a folder, the operation is recursive and will copy all files and subfolders of the source folder.	When Admin copies file "fixtures/pdfs/pdfs.zip" to "artifacts/temporary/pdfs.zip"
When '{actor} deletes folder {string}'	path - The path to the folder to delete	Deletes folder from the file system	When Admin deletes folder "path/to/directory"
Then 'file/folder {string} exists'	path - The path to the folder or file to test	Tests if a file or folder exists on the filesystem	Then file "path/to/myfile.jpg" exists

fixture (fixture.steps.ts)

Step	Arguments	Description	Example

form-content-assertions (form-content-assertions.steps.ts)

Step	Arguments	Description	Example
Then '{actor} sees checked {string} checkbox form field'	actor - Actor used to identify the browser context eg. Admin, Alice, ... label - is the label of the checkbox	Used to verify checkbox with specific label is checked	Then Admin sees checked "I agree to the terms and conditions" checkbox form field
Then '{actor} sees {ordinal} checked {string} checkbox form field'	actor - Actor used to identify the browser context eg. Admin, Alice, ... order - Ordinal number of the checkbox to look for, 2nd, 3rd, 4th... label - Label of the checkbox we are looking for	Used to verify checkbox with specific label is checked - multiple checkboxes This variant of the step is used when there are multiple checkboxes with the same label on the page.	Then Admin sees checked 2nd "I agree to the terms and conditions" checkbox form field
Then '{actor} sees checked {string} checkbox form field in/under {string}'	actor - Actor used to identify the browser context eg. Admin, Alice, ... label - Label of the checkbox we are looking for fieldset - Label of the grouping fieldset or other element	Used to verify checkbox with specific label in a specific field set is checked This variant of the step is used when there are multiple checkboxes with the same label on the page so we can specify the fieldset to look in.	Then Admin sees checked "I agree to the terms and conditions" checkbox form field under "Terms and Conditions"

form-input (form-input.steps.ts)

Step	Arguments	Description	Example
When '{actor} fills {string} into {string} {aria_role} form field'		Used to fill in a form field with an ARIA role that has specified label	When Candidate fills "Carol" into "First name" textbox form field
When '{actor} fills {string} into {ordinal} {aria_role} form field'	actor - Actor used to identify the browser context eg. Admin, Alice, ... value - Value which needs to be filled in ordinal - Ordinal position of the form field role - ARIA role of the form field to look for	Used to fill in a form field with an ARIA role that has specified ordinal position	When Candidate fills "Carol" into 1st textbox form field
When '{actor} fills {string} into {string} {aria_role} form field in/under {string}'	actor - Name of the actor, e.g. Admin, User value - Value which needs to be filled in label - Label of the form element to look for role - ARIA role of the form field to look for fieldset - Heading or legend of the fieldset to look for the form field in	Used to fill in a form field with an ARIA role & label inside a fieldset	When Candidate fills "Carol" into "First name" textbox form field in "Personal Information"
When '{actor} selects option {string} in {string} {aria_role} form field'			When Candidate selects option "Male" in "Gender" combobox form field
When '{actor} selects the {ordinal} option in {string} {aria_role} form field'			When Candidate selects the 2nd option in "Gender" combobox form field
When '{actor} clicks on {string} option in hierarchy form field'			When Candidate clicks on "Summative" option in hierarchy form field
When '{actor} fills {string} into {string} form field'			When Candidate fills "Carol" into "First name" form field
When '{actor} fills {string} into {ordinal} {string} form field'			When Candidate fills "Carol" into 1st "First name" form field
When '{actor} fills {string} into {string} form field in/under {string}'	actor - Name of the actor, e.g. Admin, User value - Value which needs to be filled in label - Label of the form element to look for fieldset - Heading or legend of the fieldset to look for the form field in	Used to fill in a form field with label inside a fieldset	When Candidate fills "Carol" into "First name" form field in "Personal Information"

Step	Arguments	Description	Example

form-wysiwyg (form-wysiwyg.steps.ts)

(Quill, TinyMCE) Text editor form steps

Interaction with text editors (Quill, TinyMCE) in the form fields across our products. These steps allow input of the long, rich text and HTML content in our forms.

Step	Arguments	Description	Example
When '{actor} fills following text into {string} text editor form field'	actor - Actor used to identify the browser context eg. Admin, Alice, ... label - Label identifying the text editor form field value - Value which needs to be filled in	Used to fill in content into Text editor form field (using label)	When Admin fills following text into "Message" text editor form field
When '{actor} fills following text into {ordinal} text editor form field'	actor - Actor used to identify the browser context eg. Admin, Alice, ... ordinal - Ordinal position of the text editor form field value - Value which needs to be filled in	Used to fill in content into Text editor form field (using ordinal position)	When Admin fills following text into 2nd text editor form field
Then '{actor} sees following text in the {string} text editor form field'	actor - Actor used to identify the browser context eg. Admin, Alice, ... label - Label identifying the text editor form field value - Value which needs to be filled in	Used to verify content in Text editor form field (using label)	Then Admin sees following text in the "Message" text editor form field

interaction (interaction.steps.ts)

Step	Description	Example
When '{actor} clicks the {string} link'	Used to click on the link with the given text or ARIA label (accessible label, icons for example). Examples: When Admin clicks the “Next” link Parameters: actor - is the name of the actor, e.g. Admin string - is the label of the link to click, can be text or ARIA label.	undefined
When '{actor} clicks the {ordinal} {string} link'	Use to click on the link by it's position (ordinal) with the given text or ARIA label (accessible name) when there are multiple links with the same label. Examples: When Admin clicks the 5th “Next” link Parameters: actor - is the name of the actor, e.g. Admin. ordinal - is the position of the link as ordinal number, e.g. 1st, 2nd string - is the label of the link to click.	undefined
When '{actor} clicks the {string} button'	Use to click on the button with the given text or ARIA label (accessible name). Examples: When Admin clicks the “Next” button Parameters: actor - is the name of the actor, e.g. Admin. string - is the label of the link to click.	undefined
When '{actor} clicks the {ordinal} {string} button'	Use to click on the button by it's position (ordinal) with the given text or ARIA label (accessible name) when there are multiple links with the same label. Examples: When Candidate clicks the 1st “Save” button Parameters: actor - is the name of the actor, e.g. Admin. ordinal - is the position of the link as ordinal number, e.g. 1st, 2nd string - is the label of the link to click.	undefined
When '{actor} clicks the {string} text'	Used to click on an arbitrary text on the page	undefined

material-dialog (material-dialog.steps.ts)

Step	Arguments	Description	Example

material-notifications (material-notifications.steps.ts)

Angular Material: Notifications (Snack bar, etc…)

Shared steps to interact with Angular Material notification components.

These steps use the Angular Material Testing Harnesses to interact with the components and are therefore Product independent.

Step	Arguments	Description	Example
Then '{actor} sees a Snack bar with {string} message'	actor - Actor used to identify the browser context eg. Admin, Alice, ... message - Message to look for in the Snack bar	Used to verify that a Snack bar with certain message is on the page	Then Alice sees a Snack bar with "Hello World" message
Then '{actor} sees a Snack bar with {string} message and {string} action'	actor - Actor used to identify the browser context eg. Admin, Alice, ... message - Message to look for in the Snack bar	Used to verify that a Snack bar with certain Message and Action is on the page	Then Alice sees a Snack bar with "Successfully saved the World" message and "Undo" action

Step	Arguments	Description	Example
When '{actor} navigates to {string} using the main menu'	actor - Actor used to identify the browser context eg. Admin, Alice, ... path - Path to the menu item, separated by '\>' (greater	Used to interact with the application's main navigation bar. The step takes a *path() to a menu item which needs to be clicked. The path starts at the top-level menu item and follows the hierarchy of sub-menus.	When Admin navigates to 'User management \> Users' using the main menu
When '{actor} opens new page for {word} clicking {string} link'	initiatingActor - Actor that is opening the new page targetActor - Actor whose page is being opened link - Link to extract the URL from	Used to open new Browser window for a particular Actor by navigating to the URL a specific link.	When Admin opens new page for EbelJudge clicking "Ebel Judgex" link

notifications-and-errors (notifications-and-errors.steps.ts)

Step	Arguments	Description	Example

pdf-comparison (pdf-comparison.steps.ts)

Step	Arguments	Description	Example
Then 'PDF {string} is same as PDF {string}'	reference - Path to the reference PDF actual - Path to the actual PDF	Used to verify that 2 PDFs are identical	Then PDF "resources/x.pdf" is same as PDF "resources/y.pdf"
Then 'PDF {string} is not same as PDF {string}'	reference - Path to the reference PDF actual - Path to the actual PDF	Used to verify that 2 PDFs are different	Then PDF "resources/x.pdf" is not same as PDF "resources/y.pdf"
Then 'page {int} is the same in PDF {string} and {string}'	page - Number of the page to compare reference - Path to the reference PDF actual - Path to the actual PDF	Used to verify that a page is identical in both given PDFs	Then page 3 is the same in PDF "resources/x.pdf" and "resources/y.pdf"
Then 'page {int} is not the same in PDF {string} and {string}'	page - Number of the page to compare reference - Path to the reference PDF actual - Path to the actual PDF	Used to verify that a page is different in both given PDFs.	Then Page 3 is not the same in PDF "resources/x.pdf" and "resources/y.pdf"
Then 'pages {numbers} are the same in PDF {string} and {string}'	pages - List of page numbers to compare reference - Path to the reference PDF actual - Path to the actual PDF	Used to verify that specified pages are identical in both given PDFs	Then pages 1,3,5 are the same in PDF "resources/x.pdf" and "resources/y.pdf"
Then 'pages {numbers} are not the same in PDF {string} and {string}'	pages - List of page numbers to compare reference - Path to the reference PDF actual - Path to the actual PDF	Used to verify that specified pages are different in both given PDFs	Then pages 1,3,5 are not the same in PDF "resources/x.pdf" and "resources/y.pdf"

screenshots (screenshots.steps.ts)

These steps are used to capture screenshots of the current page

For steps which compare the page screenshot to a reference one, see the visual-regression.steps.ts file.

Screenshot steps store captured files stored in the artifacts/screenshot folder, unless configured differently using FryWorld.locations.SCREENSHOTS configuration option.

Step	Arguments	Description	Example
Then '{actor} saves screenshot to {string} file'	actor - Actor used to identify the browser context eg. Admin, Alice, ... name - Name of the file to save the screenshot, without the '.png' extension	Used to save a full page screenshot of the current page to the file system The step saves the screenshot to the {	Then Alice saves screenshot to "screenshot" file
Then '{actor} saves screenshot of {aria_role} with label {string} to {string} file'	actor - Actor used to identify the browser context eg. Admin, Alice, ... role - ARIA role of the element to take the screenshot of label - String to match the element by, eg. name, label, etc. file - Name of the file to save the screenshot, without the '.png' extension	Used to save screenshot of the specific element on the page by ARIA role and name/label The step saves the screenshot to the {	Then Alice saves screenshot of 'button' with label 'Save' to "screenshot" file
Then '{actor} saves screenshot of {string} element to {string} file'	actor - Actor used to identify the browser context eg. Admin, Alice, ... locatorString - Locator to the element to take the screenshot of obtained from Playwright UI file - Name of the file to save the screenshot, without the '.png' extension	Used to save screenshot of the specific element on the page by passing a locator string The step saves the screenshot to the {	Then Alice saves screenshot of "getByRole('button', {name: 'Save'})" element to "screenshot" file
Then '{actor} attaches screenshot to the report'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to attach a full page screenshot of the current page to the report	Then Alice attaches screenshot to the report

table-by-label (table-by-label.steps.ts)

Table steps used for interaction & verification of tables

Table steps are available in 3 different forms based on how the table is located on the page:

By label: This should be the preferred way to locate a table on the page, however the product needs to correctly label the tables using aria-label or aria-labelledby attributes or caption and so on.
By position: This is used when the table can’t be located by label. We use ordinal numbers to locate the table on the page, eg. 1st, 2nd, …
By using first table: When there is only one table on the page, we can use this form to interact with the table.

Examples: Then Admin sees following data in “Results” table Then Admin sees following data in 2nd table Then Admin sees following data in table

Step	Arguments	Description	Example
When '{actor} clicks the {string} header column in {string} table'	actor - Actor used to identify the browser context eg. Admin, Alice, ... header - The name of header column to click on	Used to click on a table header	When Admin clicks the "Name" header column for "Candidate scores" table
When '{actor} clicks the {string} {aria_role} for {string} row in {string} table'	actor - Actor used to identify the browser context eg. Admin, Alice, ... label - Label to click role - Role of the label title - Title of the row	Used to click on a button, label, etc in a specific table row	When Admin clicks the "View" link for "Shoulder X-Ray" row in the "Results" table
When '{actor} clicks the {string} {aria_role} for {ordinal} row in {string} table'	actor - Actor used to identify the browser context eg. Admin, Alice, ... label - Label to click role - Role of the label position - The position of the row	Used to click on a button, label, etc in the nth row of a table	When Admin clicks the "View" link in table for 2nd row in the "Results" table
When '{actor} drags row {int} to row {int} in {string} table'	actor - Actor used to identify the browser context eg. Admin, Alice, ... from - Number of the row to drag to - Number of the row to drop	Used to Drag & Drop a row in a table from position A to position B	When Admin drags and drops row 7 to row 3 in the "Results" table
Then '{actor} sees following data in {string} table'	actor - Actor used to identify the browser context eg. Admin, Alice, ... table - The table which is to be verified	Used to verify that the content of a specific table determined by the `table name` is correct This step should be used as much as possible as it works with single/multiple tables per page and allows matching table per column. It is therefore up to the test author to match the table partially or completely by providing the correct data. This step requires that the tables have correct markup (THEAD, TBODY, TH, TR, TD) and are correctly labelled, using `aria-label` or `aria-labelledby` attributes or `caption` and so on.	Then Admin sees "Candidate scores" table with the following data:

table-by-ordinal (table-by-ordinal.steps.ts)

Step	Arguments	Description	Example

table-first (table-first.steps.ts)

Step	Arguments	Description	Example

table (table.steps.ts)

Step	Arguments	Description	Example
Then 'DEPRECATED: {actor} sees table column/columns with the following data'	actor - Actor used to identify the browser context eg. Admin, Alice, ... table - A table of the columns to verify	Used to verify that the content of individual table columns are correct	Then Admin sees table column with the following data

upload-download (upload-download.steps.ts)

Download & Upload

Steps below implement cross product support for downloading and uploading files.

Downloading files always downloads into the FryWorld.locations.TEMPORARY location. Keep in mind that this temporary location is cleared after each test run.

Step Arguments Description Example

Step	Arguments	Description	Example
When '{actor} downloads document using {string} {aria_role} to {string}'	actor - Actor used to identify the browser context eg. Admin, Alice, ... label - Label of the button to click role - ARIA Role must 'button' or 'link' other elements are not supported filePath - Path (incl. file name) where document should be saved	Used to download a file into a specified location The `filePath` parameter is relative to the `FryWorld.locations.TEMPORARY` folder. Therefore the file from the example can be found in `artifacts/temporary/rrq/rrq-itemset-preview.pdf` location. The `filePath` can be just a file name or a path with file name (like in the example). If the path (folders) does not exist, it will be created.	When Admin downloads document using "Download" button to "rrq/rrq-itemset-preview.pdf"
When '{actor} downloads document using {ordinal} {string} {aria_role} to {string}'	actor - Actor used to identify the browser context eg. Admin, Alice, ... position - Position of the button/link to click as ordinal number, e.g. 1st, 2nd label - Label of the button to click role - ARIA Role must 'button' or 'link' other elements are not supported filePath - Path (incl. file name) where document should be saved	Used to download a file into a specified location Same as `When {actor} downloads document using {string} {aria_role} to {string}` except addition of the {ordinal} parameter to specify the position of the button/link to click. Used in cases where there are multiple buttons/links with the same label.	When Admin downloads document using 3rd "Download" button to "rrq/rrq-itemset-preview.pdf"

When '{actor} downloads document using {string} {aria_role} to {string}'

actor - Actor used to identify the browser context eg. Admin, Alice, ...
label - Label of the button to click
role - ARIA Role must 'button' or 'link' other elements are not supported
filePath - Path (incl. file name) where document should be saved

Used to download a file into a specified location

The filePath parameter is relative to the FryWorld.locations.TEMPORARY folder. Therefore the file from the example can be found in artifacts/temporary/rrq/rrq-itemset-preview.pdf location.

The filePath can be just a file name or a path with file name (like in the example). If the path (folders) does not exist, it will be created.

When Admin downloads document using "Download" button to "rrq/rrq-itemset-preview.pdf"

When '{actor} downloads document using {ordinal} {string} {aria_role} to {string}'

actor - Actor used to identify the browser context eg. Admin, Alice, ...
position - Position of the button/link to click as ordinal number, e.g. 1st, 2nd
label - Label of the button to click
role - ARIA Role must 'button' or 'link' other elements are not supported
filePath - Path (incl. file name) where document should be saved

Used to download a file into a specified location

Same as When {actor} downloads document using {string} {aria_role} to {string} except addition of the {ordinal} parameter to specify the position of the button/link to click.

Used in cases where there are multiple buttons/links with the same label.

When Admin downloads document using 3rd "Download" button to "rrq/rrq-itemset-preview.pdf"

visual-comparison (visual-comparison.steps.ts)

These steps are used to compare the current page screenshot to a reference files stored in Fixtures folder. There are also supporting steps to save or attach the screenshots to the test report, which you can find in the screenshot.steps.ts file.

There may be situations when the elements on the page contain dynamic data changing between the visits of the page (timestamps, counters, etc…). In such cases we must use the Then {actor} screen matches the reference image {string} with element masks: which allows to specify the elements to mask out (overlay) on the screenshot. That way we can ignore the dynamic data and focus on the static parts of the page.

Reference images

Reference images can be provided manually (see below) or generated automatically by running the test suite with PW_REGENERATE_REFERENCE_SCREENSHOTS=1 flag. This will run the test suite and save all the required screenshots into the fixtures folder.

PW_REGENERATE_REFERENCE_SCREENSHOTS=1 npm run test

Reference images are stored in the fixtures/screenshots/features folder. For each feature file, there is a subfolder and within the subfolder there are screenshot files in following format: {name passed in}-{browser}-{platform}-{context key}.png

For example for the step:

Then Admin screen matches the reference image "sba_item_preview_all_options"

The reference file would be (given the reference was created on the Chromium browser and macOS):

fixtures/screenshots/features/item_preview/item_preview_saq.feature/saq_item_preview_all_options-chromium-darwin-Admin.png

Visual comparison

Step 1

Actual and Reference images are compared using Pixelmatch library which is set to ignore transparent/anti-aliased pixels by default and uses 0.5 threshold allowing for small amount of difference between the images.

Step 2

Additionally we allow for 0.5% of the total pixels to be different between two images. This makes images which are almost the same (in terms of content) to be considered same despite the small differences in the rendering (usually blur).

Step	Arguments	Description	Example
Then '{actor} screen does not match the reference image {string}'	actor - Actor used to identify the browser context eg. Admin, Alice, ... name - Name of the reference screenshot, without the '.png' extension	Used to verify the current page screenshot is different to a reference image The step takes a screenshot and compares it to the reference image stored in the {	Then Alice screen does not match the reference image "login-page"

xlsx-comparison (xlsx-comparison.steps.ts)

XLSX spreadsheet comparison steps

These steps allows to assert on the content of XLSX files. It is possible to compare two XLSX files, check if a cell/column contains a specific value or compare a table against the content of an XLSX file.

Please keep in mind that the values which are compared are the textual values of the cells without any formatting. For example ‘10000’ number value instead of formatted ‘10,000’. Same is valid for the dates, which are compared towards the raw value in the XLSX file, eg. 01/01/2023 instead of 01 January 2023.

Step	Arguments	Description	Example

zendesk (zendesk.steps.ts)

Zendesk support chat

Basic interaction and content assertion steps to allow interaction with the Zendesk chat widget.

The Zendesk support chat is available in risr/assess since version 8.11. These steps are however product agnostic and should work everywhere where the Zendesk chat is configured.

Step	Arguments	Description	Example
When '{actor} opens the Zendesk chat'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to open the Zendesk chat message window The steps attempts to open the chat window by clicking the open chat button. Should the button not be visible, the step will fail.	When Alice opens the Zendesk chat
When '{actor} close the Zendesk chat'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to close the Zendesk chat message window Steps closes the chat window by clicking the close button. At the moment the Zendesk can’t be closed, just minimized.	When Alice closes the Zendesk chat
When '{actor} clicks the {string} button in the Zendesk chat'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to click on the buttons within the Zendesk chat message window	When Alice clicks the "Report an issue" button in the Zendesk chat
When '{actor} fills {string} into {string} form field in the Zendesk chat'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to type text into form fields in the Zendesk chat message window The step types provided text and presses the Enter key to send the message to the Zendesk bot.	When Alice fills "How can I add new user?" into "Type a message" form field in the Zendesk chat
Then '{actor} sees {string} text in the Zendesk chat'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to verify presence of a text in the Zendesk chat message window	Then Alice sees "Is this related to a live exam?" text in the Zendesk chat
Then '{actor} does not see {string} text in the Zendesk chat'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to verify absence of a text in the Zendesk chat message window	Then Alice does not see "Is this related to a live exam?" text in the Zendesk chat
Then '{actor} sees the Open Zendesk chat button'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to verify the Zendesk chat button is visible on the page	Then Alice sees Zendesk chat button
Then '{actor} does not see the Open Zendesk chat button'	actor - Actor used to identify the browser context eg. Admin, Alice, ...	Used to verify the Zendesk chat button is not visible on the page	Then Alice does not see Zendesk chat button

Shared steps

Configuration

Cucumber expressions & Parameter types

Parameter types

Step definitions

a11y (a11y.steps.ts)

annotations (annotations.steps.ts)

api (api.steps.ts)

auth (auth.steps.ts)

clipboard (clipboard.steps.ts)

content-assertions (content-assertions.steps.ts)

debugging (debugging.steps.ts)

dialog (dialog.steps.ts)

filesystem-compression (filesystem-compression.steps.ts)

filesystem (filesystem.steps.ts)

fixture (fixture.steps.ts)

form-content-assertions (form-content-assertions.steps.ts)

form-input (form-input.steps.ts)

form-search (form-search.steps.ts)

form-wysiwyg (form-wysiwyg.steps.ts)

interaction (interaction.steps.ts)

material-dialog (material-dialog.steps.ts)

material-notifications (material-notifications.steps.ts)

navigation (navigation.steps.ts)

notifications-and-errors (notifications-and-errors.steps.ts)

pdf-comparison (pdf-comparison.steps.ts)

screenshots (screenshots.steps.ts)

table-by-label (table-by-label.steps.ts)

table-by-ordinal (table-by-ordinal.steps.ts)

table-first (table-first.steps.ts)

table (table.steps.ts)

upload-download (upload-download.steps.ts)

visual-comparison (visual-comparison.steps.ts)

Reference images

Visual comparison

xlsx-comparison (xlsx-comparison.steps.ts)

zendesk (zendesk.steps.ts)