Organization-Level Use Case Scripts
The Organization-level Scripts page simply lists the use case scripts that have been shared from a Project to an Organization. Only Organization Administrators are able to access this page.
Axe Monitor comes with the axe DevTools browser extension, which includes several features that allow for interaction between the two tools, one of which is scripting functionality. Together, they can be used to apply scripts recorded and validated in the axe DevTools extension to spider scans in axe Monitor that can be configured to run before a scan begins. Typically, this powerful combination is used to access and then scan sites and pages for accessibility that require sign-in authentication first.
On this page:
In their simplest form, recorded scripts can activate (click) a link and navigate from one page to another on a website. When a more complex script of recorded event actions such as populating Username and Password fields, then performing a mouse click event on a Submit action button is recorded with the axe DevTools browser extension, it can be combined with axe Monitor by applying it to a scan, which offers the ability to establish a user session from inside of axe Monitor as a scan starts. As such, bypassing authentication automatically to access content to be scanned is the most popular use of the scripting-related functionality you get with the combination of the axe DevTools browser extension and axe Monitor.
A qualified web developer with a firm grasp of web events and CSS selectors is by far the best person to create robust and reliable scripts. Script authors should also have a good understanding of what conditions might cause a given page to load with slightly different content, such as viewport size, user agent, or routine content updates. Crucially, script authors should also be familiar with which event hooks the page uses to process user input. A common pitfall is to capture too many different event types without understanding which events are actually necessary to produce the intended behavior. Recording too many events can cause unexpected and undesirable results during playback, depending on how event handlers are implemented.
Although you are certainly free to take advantage of any possible use of scripts in either the axe DevTools Extension and/or axe Monitor that you discover is beneficial, we can offer some good and bad use case scenarios for your consideration:
The following uses of scripts with axe Monitor are known to have potential to cause frustration due to limitation of the technologies involved on the pages being tested:
- Q&A Chat Support Bots: Attempts to bypass/ignore comment/question form bots and similar interactive chat popup plugins used for customer service.
- Dynamic Sites: Sites and pages with content that is not static are subject to changes upon subsequent scans that can prevent scripts from working.
The following uses of scripts with axe Monitor are known to be commonly used with success to accomplish important tasks on the pages being tested:
Username/PW Entry & Submission: Secure session establishment that involves automating the sign-in authentication necessary for access to password-protected pages and sites.
Analysis of User Input Interactions, such as:
Search: Conducting a search in a website.
Basic Web Application Interactions: Closing a notification dialog, adding items to a shopping cart (when non-dynamic).
Scripts are created in the axe DevTools browser extension for Chrome or Firefox and then uploaded to a axe Monitor Project from the extension. Use case scripts can be used to analyze content in both axe Monitor and within the extension itself.
- Overview: For general information about the Scripting panel in the axe DevTools Browser Extension, see Using the Scripting Functionality in the axe DevTools Extension on this page, or the Scripts topic in the axe DevTools Browser Extension User Guide. This will also lead you to subtopics that explain all of the tool's action options.
- Recording: For detailed instructions about how to record a new script in the axe DevTools Extension, see Recording a Script on this page, or the Recording a Script topic of the axe DevTools Extension User Guide.
- Uploading: For specific instructions about how to upload a script recorded in the axe DevTools Browser Extension (for Chrome or Firefox) to axe Monitor, see Uploading a Script on this page, or the Uploading a Script subtopic in the axe DevTools Browser Extension User Guide.
The use of the FireEyes II extension for the Firefox browser for scripting is only possible with older versions of the Firefox browser. Version 2.0 of the axe DevTools extension for Firefox has replaced FireEyes II for use with axe Monitor v.6.2. For complete information about how to use the new axe DevTools extension with axe Monitor for either the Chrome or Firefox browsers, see axe DevTools Browser Extension - User Guide v.2.0.
- As of Firefox version #55 or later: Scripting functionality in FireEyes II is no longer supported.
- As of Firefox version #56 or later: FireEyes II is discontinued and no longer supported.
The Scripts page lists all of the use case scripts that have been created for the Project by any Project Member.
Each script is listed with:
- The scan(s) using the use case script. The scan name is a link to the scan's Edit Scan page.
- The number of steps in the script.
- The number of still-open issues found in the analysis of the script. This number is a link. Select the link to see the Issues Report filtered to include only the issues linked to that script.
- The number of pages with open issues found in the analysis of the script. This number is a link. Select the link to see the Pages Report filtered to include only the pages linked to that script.
- The number of clean pages found in the analysis of the script.
Use case scripts are applied to an axe Monitor scan on the Create or Edit a Project Scan page. Use Case Scripts can also be combined with Scope Definitions on the Create or Edit a Scan page. See the Session Establishment Tasks and Specify a Scripted Event sections for complete details.
Avoid using scripts with dynamic sites (page differences between visits can break scripts).
Scripting is a trial and error process to discover what works for each site. For example, if recording click and change events doesn't work, try recording only keypress or submit events.
Use Incognito Mode in Chrome when recording and testing.
Check Allow in incognito for the axe DevTools DevTools Extension in the browser extension settings.
Disable ad blocking software.
Keep in mind the following script refinement tips:
Navigate to a different site, then play your script.
Remove unnecessary or redundant events.
Adjust timing as necessary.
You may need to upload your script to axe Monitor, then restart your incognito session and retrieve your script if cookies were saved locally during recording.
To test in axe Monitor, add your script to a scan (select Scans > Edit, then Session Establishment Task), which completes the script, then scans the first Task.
Scripts can be shared to the Organization so they can be used by other Organization Projects.
To share script(s) with your organization:
- Select the use case script(s) via the checkboxes.
- Select Share with organization from the Action dropdown.
- Select the Apply button.
To export use case script information:
- Select the script or scripts via the checkboxes.
- Select Export (to CSV) or Export to Excel from the Action dropdown.
- Select the Apply button.
- Follow the prompts from your browser to open or download the file.
To delete one or more use case scripts:
- Select the script or scripts via the checkboxes.
- Select Delete from the Action dropdown.
- Select the Apply button.
Note: Deleted use case scripts are not actually deleted from the axe Monitor server - they are stored, but not used.
To restore a deleted script:
- Check Show Deleted Use Case Scripts.
- Select the Go button. A list of deleted scripts will appear.
- Select the Undelete button to restore the script.
- To return to the active use case scripts view: uncheck Show Deleted Use Case Scripts and select the Go button.
Script tasks are used to drive the page into a particular state prior to analyzing the content for accessibility. A recorded script may load multiple different URLs before it finally gets to the page which is to be analyzed, but it is this final URL that will be used to determine whether the page is unique and should therefore be analyzed. Axe Monitor ignores all but the first instance of a given page — future encounters with the same page will cause axe Monitor to recognize the page as a duplicate of a page that has already been scanned, and it will therefore be ignored.
When axe Monitor replays a user-recorded script in the context of a script task, and any of the events in that script fail to play back successfully, the entire script task will be failed and the reason for the failure recorded for user to review. The intent is to alert user that scripts are broken as quickly as possible so they have an opportunity to repair the script, or find another method of analyzing the desired content for accessibility. This also prevents the unfortunate situation wherein a script fails silently, causing users to assume that their content has no accessibility issues, when in fact the content was not successfully analyzed.
When you use an input device (such as a keyboard or mouse) to interact with a web site (such as scrolling, making a selection, entering text, clicking a link or button), the series of interactions can be recorded and then played back at a later time in the order in which you performed them. These recordings, referred to as scripts, play like videos in which you see the cursor moving, options being selected, text entered, links clicked, etc., just as you performed them when recording.
Scripts in the axe DevTools extension capture the URL, Target, Timing, and Details for each Event. Each event can be deleted from a script, and the timing of each event can be modified. Aside from recording and playing back, scripts can be stopped at any point in time, and they can also be resumed from the point at which they were paused. Scripts can be downloaded from or uploaded to axe Monitor, provided you are signed in to your axe Monitor server, which is done on the Settings panel.
- Start/Stop Recording buttons: Initiates the recording of a script. For detailed information, see Recording a Script.
- Play/Pause/Stop/Resume/Step Forward buttons: Plays a previously-recorded script, pauses a script that is playing or being recorded, resumes play of a paused script, stops play of a playing script, advances the stopped (paused) script to the next sequential action step. For detailed information, see Playing a Script, Stopping a Script, Resuming a Script, Stepping Forward.
- Clear button: Clears the script from the Scripting tab event table. For detailed information, see Clearing a Script.
- Export to axe Monitor: Exports a previously-recorded script to a file for uploading to axe Monitor. For detailed information, see Exporting a Script.
- Export to AGet: Exports the currently-displayed script as an AGet JSON script file. For detailed information, see AGet actions recording and export.
- Login: Displays the axe Monitor login panel. For detailed information, see Sign In to axe Monitor.
- Options: Displays the Script Recording Options panel to select options for event types to be recorded or ignored. For detailed information, see Selecting Event Recording Options.
- Event column: The type of event recorded, such as the click event.
- URL column: The page on which the event took place.
- Target column: The Xpath for the element that was acted upon.
- Timing column: How long each individual action lasted.
- Details column: The coordinates of the element on the page.
- Actions column: Buttons display action option link menu buttons that allow you to display drop-down menu lists of possible actions to be taken for the selected event row.
- Actions column menus: The expanded menu displays items that are action option links which allow you to Edit and save changes made to an event's timing, or Delete an event.
Detailed Instructions for using the axe DevTools Browser Extension (for Chrome and Firefox) v. 2.0 Scripts functionality
Recording a script whenever you want to record yourself taking actions on the page under test in a sequential order so that they can be repeated automatically at a later time. Scripts can be particularly useful when applied to axe Monitor scans (for example, login scripts to establish secure sessions for page access, dynamic content scripts to expose hidden form menus and widgets, or for activating hidden steps in multi-step processes).
Note: You can control which types of events are recorded by selecting options on the Script Recording Options panel, which is accessed via the Options link on the Scripts panel. For more information, see Selecting Event Recording Options.
Before you begin: Ensure you first have the desired start page loaded in the browser.
To record a script:
On the Scripts panel, select Start Recording.
Start performing actions on the page under test as desired, in the desired order (for example, by clicking the Desktops page link on the main horizontal menu).
You will notice that as you interact with the site, a table appears in the main content pane of the Scripts panel and rows begin to appear with each column populated with values for each event (for example, in the Event column a 'loadURL' event with the URL column as 'http://abcdcomputech.dequecloud.com/desktops.php').
When you have finished performing all desired actions, select Stop Recording (which has replaced the Start Recording button).
You must stop the recording at some point in order to have a recorded script. This enables the previously greyed-out Upload link above the event table. Additionally, this causes Stop Recording to change back to Start Recording again, and displays a Play button beneath.
Recording stops immediately, and every action you recorded now displays as an event row in the Scripts panel table in the right content pane, with each column populated with values. Note: Not every event will record content values in every column cell, so some (for example, the Details column for the focus event type) may be blank. Additionally, stopping a recording enables the Edit and Delete options in the Actions column menus.
Playing a script is done whenever you want to command the browser to automatically perform previously-recorded sequential, timed user actions on the page under test. This may also be referred to as "running" a script.
To play a script:
- Enter the URL of the web page the script starts on in the browser Address field, then press the [Enter] key on your keyboard to load the page under test in the browser.
- Open axe DevTools and navigate to the Scripts panel using the main menu to the right of the axe DevTools logo. For more information about opening the axe DevTools tool, see Open the axe DevTools Extension.
- Do one of the following to load an existing script into the Scripts content pane table:
- Click Play on the Scripting toolbar.
As you view the page under test, you can observe the automated script performing each recorded event (for example, selecting the Desktops page link from the main horizontal menu bar, and the selected page loading so that its content is displayed).
The Resume button becomes a Pause button after the Play button has been clicked and before the script has finished playing.
Optionally, you may do either of the following before the script is finished playing:
- Stop the script. For complete details, see Stopping a Script.
- Pause the script. For complete details, see Pausing a Script.
If you do not choose to Stop or Pause the script, you can continue to observe the events until all have been completed, at which time the script control buttons return to their original state.
Stopping a script is done whenever you want to either end the playback of a script, or halt the progress of a script that is currently paused before it has been completed. Note: To stop a script that is currently being recorded, refer to the instructions in the Recording a Script topic.
Stop a script:
With a script either being played back or paused, click Stop in the script controls pane at left.
Note the following resulting implications:
- While playing: Stops the script at a point in time and enables the Resume button to continue playing until finished.
- While paused: Stops the script and returns it to its first event so that it can be played back again from the beginning.
When a script has been paused at an event step prior to completion of being played to its end, the Stop button appears between the Resume and Step forward buttons:
Pausing a script is done whenever you want to stop a currently-playing script before it has finished playing, and still be able to continue playing it at a later time.
At any time after clicking the Play button and before the last event has been performed, the Resume button becomes a Pause button that, when clicked, will stop the script from running at that point in time, after which it will change the Pause button back to a Resume button again.
Pause a script:
While a script is currently playing, click Pause on the Scripting toolbar.
The script stops playing, and the Pause button changes to display a Resume button.
For instructions about how to resume a paused script, see Resuming a Script.
Resuming a script is done whenever you want to "pick up where you left off" on a page under test in which a script has been previously played, then paused prior to finishing.
To resume a script:
With either a script that has been played, then paused, or played, then stopped, click Resume on the left controls pane of the Scripts panel.
The following results occur based on the state of the script prior to resuming:
- When previously paused: The script continues to play from the point where it had been paused until its last event is completed.
- When previously stopped: The script starts playing from the first recorded event.
As noted above, depending on the state of the script, the location of the Resume button (and the other buttons in proximity to it) differs (as in the paused state example shown below):
You can step forward in a script whenever you want to advance a stopped (or paused) script to the next event step. Click Step forward in the left controls pane of the Scripts panel.
To step forward in a script:
Click Step forward in the left pane of the Scripts panel when a previously-recorded script is loaded and either paused or stopped at a particular event step (as noted by the row with the shaded background in the event table at right).
The script advances forward to the next event, and the event row is shaded with a blue background indicating the current step in play. Note that if the script is paused, the Resume button is replaced with a Pause button instead of a Stop button after clicking Step Forward. Additionally, note that the change to the rendered page above the DevTools displays the next event. For example, navigating from the Index page to the Cart page of the Gefalscht CompuTech site.
Click Resume (or Play), and the script will begin to play from the advance to shaded event.
Clear a script when you want to clear the event table in the right content pane of the Scripts panel to remove all of the event data rows. Presumably, you might do this when the currently-displayed script is no longer necessary, or when you want to either record or download a different script.
Caution: If you have not previously uploaded the script to axe Monitor, the script cannot be used again after clearing. You need to record the script again. For instructions about how to upload a script, see Uploading a Script.
To clear a script:
With a script currently loaded and displayed in the main content pane event table, click Clear on the left controls pane.
The Scripts content pane table is refreshed to display only the column headings, but no content rows, effectively clearing the script.
At this point you can either start recording a new script, or download a script from axe Monitor.
Download a script whenever you want to select an existing script from a project in axe Monitor to make it available for playing in the Scripting tab of the axe DevTools browser extension.
Before you begin, it is important to remember to clear any currently loaded and displayed scripts from the Scripting tab prior to downloading one. For more information, see Clearing a Script. Additionally, you must be logged in to axe Monitor. For more information, see Settings. It is also important to note that the Chrome browser must not be using "incognito" mode, otherwise script downloading from axe Monitor is not possible.
To download a script:
At the top, right of the Scripts panel content pane, click Download link.
If you have not already signed in to axe Monitor and selected a project, you will be prompted to do so. The list of available projects corresponds to those marked as Favorite in axe Monitor. For more information, see The Concept of "Favorite" Projects in the axe Monitor User Guide.
In the Select a script drop-down menu, click down arrow, then click to select a script in the list.
The Select a script menu closes and your selection displays.
Click DOWNLOAD SCRIPT.
The event table in the Scripts panel content pane at right displays populated rows for each event in the downloaded script.
You can now play the script, or edit it as desired. For more information, see Playing a Script.
Uploading a script whenever you want to store and share a recorded script with other axe Monitor users for a particular project for reuse; for example, to automate completing a tedious sign-in form to access a portion of a site to be spider scanned for accessibility rule violations.
Before you begin, you must have a previously-recorded script currently displayed in the content pane table on the Scripts panel. For more information, see Recording a Script. Additionally, you must be signed in to axe Monitor. For more information, see Settings.
Testing (Playing Back) Your Script Before Upload: You should play a previously-recorded script in axe DevTools before you upload it to axe Monitor to verify desired functionality. As web pages are subject to change, the relevant selectors and paths are also subject to change, which can break a previously-recorded script. Axe Monitor scans may not work when attempting to reuse older scripts. It is recommended best practice to validate (particularly when the script has first been downloaded from axe Monitor into axe DevTools) against the latest code of the page on which you intend to run the script.
To upload a script for axe Monitor:
At the top, right of the event table content pane on the Scripts panel, select the Upload to axe Monitor link.
If you have not already signed in to axe Monitor and selected a Project, you will be prompted to do so. The list of available projects corresponds to those marked as Favorite in axe Monitor. For more information, see The Concept of "Favorite" Projects in the axe Monitor User Guide. Follow the prompts to select a project to populate the list of available scripts from which to select, then select a script name as desired.
If desired, modify the default date text in the Script Name field on the Upload to axe Monitor pane at the right of the Scripts panel.
If desired, check Save as a new script (when a script of the same name already exists and you do not want to replace its content).
Click Upload to axe Monitor.
The Scripts panel refreshes to display the event table of the uploaded script in place of the Upload to axe Monitor Script to axe Monitor pane.
Validation Note: The name you gave the uploaded script is now displayed in the Script field at the top, left of the right pane. Although no upload success response message displays to confirm a completed upload within axe DevTools, selecting Settings>Scripts in axe Monitor's menu will display the script name you uploaded in the selected project list.
You are now able to download the script from axe Monitor into axe DevTools in the future to play it. For more information, see Downloading a Script.
Record and export AGet scripts using the Scripts panel. See AGet: Codeless Testing for specific information about AGet actions in axe DevTools. See Record a Script in this guide for more information about recording scripts in general.
Current supported AGet actions available for script recording and export include:
- change — change the value of
- click — click an element in the DOM
- navigate — navigate to a new page
In time, we plan to add more AGet actions. The current functionality does allow users to get started with AGet without writing a single line of code!
Navigate to the web page you wish to analyze through scripting. For the purposes of this example, we've opened https://dequelabs.github.io/aget-demo-site/.
Note the Satisfaction Survey dialog that displays in the middle of the browser page. We'll record a small script to dismiss the dialog.
Open your browser's developer tools (Chrome for macOS is used in the examples here) and navigate to the axe DevTools tab. Select Scripts.
Select Start Recording.
When active, the Start Recording button turns red to indicate active recording and the text below the button changes to Stop Recording.
With script recording active, move the DevTools window out of the way to display the https://dequelabs.github.io/aget-demo-site/. Select X to dismiss the dialog window.
Switch your focus to the DevTools window again and select Stop Recording. Notice that the Script panel is now populated with at least one action - where the modal dialog was dismissed.
Select Stop Recording button in the axe DevTools left panel and review the content of the Script panel. The Start Recording button is now enabled. Note that the script contains a click event. Also note the location of the Export to AGet link as the second of four buttons on the upper right quadrant of the Script panel.
Select Export to AGet to start the AGet export process. Axe DevTools displays the system file browser. Navigate to the folder where you wish to save the AGet script.
Provide a meaningful file name, carefully preserving the
.jsonextension and select Save.
The system file browser window is dismissed and a successful save message and the name of the saved file is displayed in the lower left corner of the DevTools window.
Open the saved JSON file in your favorite text editor to review the AGet script contents:
The use IDs for Selectors checkbox in axe DevTools Extension 2.7 Scripting options is deprecated in favor of using axe-core’s more reliable axe-selector feature. A message with more information displays when the user hovers over the deprecated text following the disabled use IDs for Selectors checkbox:
The Scripts selection in the main drop-down menu displays the Start Recording button in axe DevTools. Select Options on the Scripts panel to display script recording options.
The intent of the vast majority of recorded scripts is to bypass authentication. Verify that focus and keydown events are not checked in the Events to Capture portion of the Options in the Scripts tab. Focus is useful for replay purposes when an element is visible upon focus and hidden when focus is removed. Keydown is required to exercise custom keyboard event handlers, which are otherwise picked up by click or change events.
To select an event recording option:
Verify that the aXe tab is active in the Developer Tools window and select Scripts from the axe DevTools main drop-down menu. The Scripts panel displays.
Select Options at the far, upper right side of the Scripts panel. The General and Events to Capture scripting options display.
Depending on the size of your browser window and the docking orientation of your developer tools, you may need to scroll down vertically to see all of the available options.
In the Events to Capture section of the right pane, click checkboxes to the left of desired options to enable or disable the option in the subsequent recorded script (for example, Submit).
A checkbox displaying a checkmark indicates option selection and any scripts recorded will record events of this type.
The Load URL, Change, Click, and Scroll options are active by default.
To prevent recording an event type in a script, clear the relevant checkbox to disable the specific event type.
The next script recorded reflects your saved Events to Capture changes.
Editing a script event when you want to modify any of the fields of information associated with the recorded script events (for example, Timing, which would be the number of milliseconds required for a particular event to complete so that it takes more or less time than the original recording when subsequently played again). Additionally, the target (XPath) of an event is editable.
XPath Reference: For more information about XPath expressions, refer to W3 XML Path Language (XPath) 3.1.
To edit a script event:
With a script currently displayed in the content pane event table of the Scripts panel, click the context menu button in the Actions column within the desired event row and select Edit from that menu.
The Edit Script Step pane replaces the event table in the right content pane of the Scripts panel, displaying editable fields of information associated with the event script step. Depending on the type of event you selected, the editable fields will differ.
In the desired field(s), change the existing content value(s) as desired (for example, for a LoadURL type of event, in the Event Timing field, modify the existing amount of milliseconds by either increasing the numeric value to add time to complete or decrease the value to reduce the amount of time required to complete the event).
Scroll to the bottom of the editable fields and click SAVE.
The Edit Script Step pane is replaced by the event table, and if the value you changed is one of the events displayed as a column within the table, it will reflect the new value (for example, the Timing column value changed to the number you specified).
You are now able to re-run (play) the script and the change you made will be reflected accordingly for the event step.
The fields of information that are editable on the Edit Script Step pane of the Scripts panel will differ depending on the type of script event selected, as will the number of editable fields.
A logical next step after you've edited an event step in a script would be to upload it to replace the old script in axe Monitor. For complete details, see Exporting a Script.
Delete a script event whenever you want to eliminate an event from a script. Deleting a script event removes the event from the Scripts panel event table.
Events cannot be restored to a script after deletion.
To delete a script event:
Within the table row of the event you want to remove, click context menu (ellipses) in the Actions column.
In the Actions column context menu, click Delete.
The event row is removed from the table in the content pane of the Scripting tab, and will no longer be included when you play the script again.
Related Topic: You can control which types of events are recorded by selecting options on the Settings panel. For more information, see Selecting Event Recording Options.