Scope Definitions

On this page:

• What are scope definitions?
• How are scope definitions made in the axe DevTools browser extension?
  • Adding a scope definition
  • Editing a scope definition
  • Deleting a scope definition
• How are scope definitions used in axe Monitor?
• How are scope definitions shared to the organization?

What are scope definitions?

Scope definitions (also called templates) allow you to segment portions of pages that are common across multiple pages, such as the header, footer and navigation areas.

When an issue appears in one of these defined areas, regardless of how many pages it appears on, it will be reported as one Common Issue in the Project Dashboard (it will appear once in the Common Issues table and once in the Automated Issues table) and one Issue in the Issues Report - instead of repeatedly for each page on which it appears.

How are scope definitions made in the axe DevTools browser extension?

Defining a scope in axe DevTools is done when you want to only test certain portions of a page instead of the entire page. On many websites, there are elements or "template" areas that are common to many pages of a site. This can be used to specifically test common template components, or to ignore them in order to focus on the content that is not a part of the common components (for example, header, footer, or navigation sections). Version 1.1 and later of the axe DevTools browser extensions were designed and implemented using Cascading Style Sheet (CSS) Selectors for the purpose of defining scope.

XPath Version Support:

Axe Monitor v. 6.0 or later supports both CSS selector and XPath technologies, due to the fact that previously, version 1.0 of XPath was supported by v. 1.0 of the axe DevTools browser Extensions. For more information, see XML Path Language (XPath) Version 1.0 - W3C.

To avoid violation duplication when analyzing multiple pages, the Scope definition feature of axe DevTools provides you with a way to limit what is being analyzed to one or more specific sections of a page, while ignoring the common, repeated content that is not selected as a part of the scope. By having the scope definitions defined during scripted analysis it will have the same effect as static analysis. In other words, only including the defined portions of the page in the script. This process is particularly useful when testing only scope definitions that cover the content areas of the page, which eliminates the repetitious issues found in testing templates.

Enabling Scope functionality without logging into axe Monitor

Employ the following steps to enable Scope functionality display on the Settings panel without logging into axe Monitor:

1. Select Scope on the axe DevTools extension overflow menu to access the Settings tab:

   

2. The extension displays the empty axe DevTools extension Scope tab on first access:

   

   Do NOT login to axe Monitor. Instead, create a new project-less scope using the described Option Descriptions and Column Descriptions:

   

Note:

Scopes created and saved without a connection to axe Monitor do not persist across working sessions in axe DevTools Extensions 2.7. The ability to save a scope allows users to work with multiple scopes in a single working session. Future axe DevTools Extensions may incorporate persistent scope storage without requiring the user to login to axe Monitor.

Enabling Scope Functionality while logged into axe Monitor

Employ the following steps to enable Scope functionality display on the Settings panel while logged into axe Monitor:

1. Sign in to axe Monitor on the Settings tab in axe DevTools. For complete details, see Sign In to axe Monitor.

   After you sign in, the Project selection section appears on the Settings panel.

2. Select a Project by using the Select a project menu and button on the Settings panel. For complete details, see Select an axe Monitor Project.

   The Scope Definitions functionality appears below the project selection and issue download sections on the Settings panel.

   

Option Descriptions

Once enabled, you will see the Scope section on the Settings panel in axe DevTools, which displays an Analyze scope radio button option group with the following three available options from which to select:

• Entire page: Select to refine the defined scope when performing an analysis on the Analysis panel to the entire page that is loaded in the browser.
• Content only: Select to refine the scope when performing an analysis on the Analyze panel to only the content items not a part of any templates defined in the Scope Definitions table below.
• Template only: Select this option to refine the analysis performed on the Analyze panel to everything except the content definitions on the loaded page under test.

Column Descriptions

Below the Analyze scope options section, you will see the scope definitions table section, which displays a table with the following six columns of information:

• Name: A text entry field used to give the scope definition a name that is clear and meaningful (for example, 'Header').
• Category: A drop-down menu field used to specify the type of scope. Options include 'Template 1-4' (whole page) and 'Content 1-4' (body of page). These can be used to group related scope definitions together so that they can be easily sorted.
• URL pattern: A text entry field used to specify a part or parts of a website that uses a different template set than the main portion of the site (for example, a shopping or secure member services area), defined with a string of text that appears immediately after the domain name in the page address for a pattern that uses a wildcard match (for example, '/products' would match '/products' as well as any string of text that comes after it).
• CSS Selector(s): A text entry field used to specify the locator of the content to be targeted (for example, /html/body for the body of the document, or html to specify the whole page). Generally, you must know the id of the element you want to evaluate. For example:
  • **/section[@id='content']** identifies a section tag with an id of "content": <section id="content">
  • **/div[@id='header-panel']** identifies a div with an id of "header-panel": <div id="header-panel">
  • **/div[@id='right-column']** identifies a div with an id of "right-column": <div id="right-column">
  • **/html/body/section/div[2]/div[3]** identifies an item without an id: the third div inside the second div inside the section tag inside the body of the html
• + Frame: Click to add a new line below that provides a text entry field you can use to enter a selected CSS selector locator (the DOM node region data) if the region is within a frame. The plus symbol becomes a minus to indicate it is possible to remove the line after it has been added.
• Actions: Within a blank row, the Save button appears in the Actions column, which allows you to add your selection/entries as a new scope definition row. After a row has been added, the Edit and Delete buttons appear.

Adding a Scope Definition

Follow this procedure any time you want to limit or restrict the portion of the page you are analyzing to a CSS selector or URL pattern categorized by content, template, or the entire page. Adding a scope definition is a matter of populating five columns of information in the Scope section table on the Settings panel in axe DevTools, then selecting the Save button.

Scope Definitions and Auto-Association with Comply Projects

The Scope section of the Settings panel only appears after a connection with axe Monitor has been established and a project selected. Defining and saving a scope by following this procedure adds the Scope Definition to the selected project in axe Monitor so that when you subsequently select the project again in the axe DevTools Extension, the existing scope definitions automatically load on the Settings tab. Any time you select the project, this scope definition will automatically download into axe DevTools Extension from axe Monitor. For complete details about how to work with saved scope definitions in axe Monitor, refer to Scope Definitions in the Managing Organization Projects section of the Comply User Guide.

Added scope definitions refine the analysis performed on the Analyze panel in axe DevTools Extension to the areas of the loaded page that match the scope.

Before you begin, it is important that you understand how to enable the scope definitions functionality and understand the purpose of each option and table column field. For complete details, see the parent Scope Definitions topic of this guide.

To add a scope definition:

1. In the Scope section of the Settings panel, enter meaningful text in the Name column (for example, 'Header').

2. In the Category column, access the drop-down menu options, and then select an item in the list (for example, 'Template 1').

   The Category drop-down list closes and your selection is populated in the field display.

3. In the URL pattern field, enter the text string after the domain name, if desired (for example, '/html/head').

4. Optionally, select + Frame to cause a new, blank CSS Selector field to display on a new line below, then enter the selector for the component, if it is contained in a frame.

   

5. In the CSS Selector(s) field, enter the selector you have selected using your tool of choice (for example, via right-click > Copy > Copy selector in Chrome DevTools after highlighting the source code in the Elements tool).

6. In the Actions column, select Save.

   

The scope you added appears as a new row in the table, and the Actions column displays buttons that allow you to either Edit or Delete it. Additionally, a new, blank line appears below your saved scope line, which allows you to specify and save another, etc.

You may now select the desired option in the Analyze scope section above the table, then perform an analysis on the loaded page that is defined by the scope you specified. For more information, see Analyze a Page for Accessibility Rule Violations.

Editing a Scope Definition

Editing a scope definition is done when you want to modify an existing scope definition by editing one or more of its five fields of information. Selecting the Edit button in the Actions column of the Scope section table on the Settings panel in axe DevTools causes the fields to become editable and a Save button to appear, which allow you to change the scope of what will be targeted when performing an analysis of the loaded page on the Analyze panel. This also changes what is stored in axe Monitor accordingly.

To edit a scope definition:

1. In the Actions column of the Scope section table, select Edit.

   

   The fields become editable in each column, and the Actions column displays a Save and Cancel button.

2. Make changes to one or more column fields as desired, then select Save in the Actions column.

   

The changes you saved are displayed as a read-only line in the table and are automatically synchronized with axe Monitor.

Deleting a Scope Definition

Deleting a scope definition removes the row from the Scope section table on the Settings panel, and also removes the scope definition from axe Monitor.

Delete a scope definition:

1. In the Actions column, in the row of the existing scope definition you want to delete, select Delete.

   

   The row is removed from the Scope Definitions section table.

How are scope definitions used in axe Monitor?

Scope definitions are applied to a scan on the Create or Edit a Project Scan page. Scope Definitions can also be combined with Use Case Scripts on the Create or Edit a Scan page.

How are scope definitions shared to the organization?

To share scope definitions to the Organization so they can be used by other Organization Projects:

1. Select the scope definition(s) via the checkboxes.
2. Select Share with organization from the Action dropdown.
3. Select the Apply button.