--- sourceDocument: Zurich Build or modify applications sourceDocumentLink: https://www.servicenow.com/docs/r/zurich/application-development Release : - zurich ft:locale : - en-US ft:publication_title : - Zurich Build or modify applications ft:clusterId : - cadev bundleId : - cadev workflow : - Development, Data, and Analytics --- # Custom UI test steps # Custom UI test steps {#ariaid-title1} * Release version: Zurich * * Updated July 31, 2025 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 8 minutes to read Test customized user interfaces such as UI pages and UI macros by retrieving their HTML and JavaScript page components and identifying the test actions they support. Custom UI test steps require the Automated Test Framework to retrieve and identify the testable components from a target web page. Note: Next UI Experience pages are not supported by the Custom UI test steps, including but not limited to Configurable Workspaces (except for Form steps) and UI Builder. ## Testable components {#custom-ui-test-steps__section_sd1_rfv_bgb} Testable page components consist of standard HTML and JavaScript with these characteristics. Are set or clicked by user interaction : Testable page components allow users to set a value or click them. Are accessible from the Document Object Model (DOM) : Testable page components are accessible from the DOM and support JavaScript manipulation of the DOM. Custom UI test steps cannot access page components in the shadow DOM. Are accessible to JavaScript : Testable page components are accessible to JavaScript. Custom UI test steps cannot access page components that interact directly with the operating system such as file fields or display non-HTML content such as Excel or PDF files. : New browser tabs or windows are not supported by Custom UI test steps. Are not excluded from custom UI testing : Testable page components are not excluded from custom UI testing. Automated Test Framework excludes page components that are already testable by other test step categories and also excludes page components associated with ServiceNow AI Platform features. Are accessible to the Page Inspector : Testable page components must return results when viewed from the [Page Inspector](https://www.servicenow.com/docs/fd5e7dAIccYcvMsnmx4_CQ "Identify the HTML and JavaScript page components in your user interfaces that are available for custom UI testing. Enable automated testing by ensuring that your user interfaces only contain testable page components."). Test designers can use the Page Inspector to identify the testable components of a page. Examples of testable page components include these UI elements. * Buttons * Links * Page text * UI controls * UI macros * ui_date * ui_date_time * ui_reference {#custom-ui-test-steps__ul_izq_p31_bgb} * UI pages * Wizards {#custom-ui-test-steps__ul_yl4_nty_4fb} Examples of untestable page components include these UI elements. {#custom-ui-test-steps__table_j5s_pyy_1gb__entry__2} | Reason untestable | Untestable page components | |-|-| | Are not settable or clickable | Hidden controls | | Are not settable or clickable | HTML comments | | Are not settable or clickable | HTML layout elements such as div, section, and span. | | Are not settable or clickable | HTML script elements | | Are inaccessible from DOM | Dashboards | | Are inaccessible from DOM | Images | | Are inaccessible from DOM | Lists | | Are inaccessible from DOM | Reports | | Are inaccessible from DOM | Shadow DOM | | Are inaccessible to JavaScript | Excel files | | Are inaccessible to JavaScript | File fields | | Are inaccessible to JavaScript | PDF files | | Are ServiceNow AI Platform features | Flow Designer | | Are ServiceNow AI Platform features | Studio | | Are ServiceNow AI Platform features | Upgrade Monitor | | Are testable by other test step categories | Form field labels | | Are testable by other test step categories | Form field values | | Are testable by other test step categories | Service Catalog | | Are testable by other test step categories | Workspaces | [Table 1. Example untestable page components] {#custom-ui-test-steps__table_j5s_pyy_1gb} ## Settable page components {#custom-ui-test-steps__section_kmt_kwt_1gb} A settable component is a UI element that has a dynamic value such as a text input field. Settable components support these test actions and test steps. {#custom-ui-test-steps__table_qt2_mqy_1gb__entry__2} | Page Inspector actions | Custom UI test steps | |-|-| | Set Component Value | Set Component Values (Custom UI) | | Get Component Value | Assert Text on Page (Custom UI) | | Get Component Value | Component Value Validation (Custom UI) | | Is Component Disabled | Component State Validation (Custom UI) | [Table 2. Test options for settable components] {#custom-ui-test-steps__table_qt2_mqy_1gb} Settable components have a data type that determines what values a Custom UI test step can set. For example, a page component intended to display a reference to a particular record can have a reference data type to only display Sys ID values. Automated Test Framework allows UI developers to specify a data type to use during custom UI testing. UI developers can assign page components a data type to ensure that a test step sets a valid value. These data types are supported. * Date * Date Time * Reference {#custom-ui-test-steps__ul_vzp_ygv_bgb} See [Override component data type](https://www.servicenow.com/docs/BiCHM6vVtcVZPJrDZoGKnw "Use the sn-atf-data-type and sn-atf-data-type-params attributes to override the type of field displayed in a Set Component Value test step.") for more information. ## Clickable page components {#custom-ui-test-steps__section_rhc_mwt_1gb} A clickable component is a UI element that users can interact with by clicking, such as inputs of type check box or radio. Clickable components support these test actions. {#custom-ui-test-steps__table_fcv_cry_1gb__entry__2} | Page Inspector actions | Custom UI test steps | |-|-| | Click On Component | Click Component (Custom UI) | | Get Component Value | Assert Text on Page (Custom UI) | | Get Component Value | Component Value Validation (Custom UI) | | Is Component Disabled | Component State Validation (Custom UI) | [Table 3. Test options for clickable components] {#custom-ui-test-steps__table_fcv_cry_1gb} Clickable components do not have a data type since they do not have dynamic values. ## Retrieved page components {#custom-ui-test-steps__section_otr_v1k_cgb} Automated Test Framework stores a list of the retrieved page components for each custom UI page you test. Custom UI test steps display the list of retrieved components from the Component and Component values fields. By default, the list of page components is static and is only updated when Test designers manually click Retrieve Components. Administrators can enable the system property sn_atf.page_data_capture.enabled to refresh the list of page components every time a Custom UI test step is run. Enabling this property during test design ensures that your test designers always have access to the most current list of page components. Disabling this property after test design is complete allows your tests to run faster because test steps can use the previously retrieved list of page components. The ServiceNow AI Platform treats the list of retrieved page components as data and does not include them in update sets or applications files. When transferring tests from one instance to another, test designers must manually retrieve page components again. ## Design considerations {#custom-ui-test-steps__section_kzp_5qb_qfb} Follow these design considerations when testing custom UI pages and page components. Use the page inspector to identify testable page components : The page inspector determines which page components are available for custom UI testing. Page components that are unavailable to the page inspector are unavailable to custom UI testing. Navigate to the custom UI you want to test : Use existing test steps to navigate to the target custom UI. For example, to test a Knowledge Base article, use the existing test steps to navigate to a module or to open an existing record. Most custom UI testing requires using existing test step categories as part of the test. Use the component area to identify page components : The component area describes the HTML layout element containing the component such as a `
` or `
` element. The area helps test designers distinguish between components by providing the location in the page layout. Test your custom UI rather than ServiceNow AI Platform UI : The Automated Test Framework prevents custom UI testing of ServiceNow AI Platform features. For example, you cannot test dashboards or graphical designers. Instead, build tests to validate your custom UI pages and elements since you have direct control over these user interfaces. Use HTML attributes to override page component testing properties : Change the testing properties of a particular page component using HTML attributes that are specific to Automated Test Framework. See [Override component test actions](https://www.servicenow.com/docs/5pzGhDoZ5pCcDS7_2SquDg#develop-testable-components "Change the testing properties of a particular page component using HTML attributes that are specific to Automated Test Framework."). Retrieve page components again when you move tests to another instance : Custom UI test steps do not store UI components as metadata. Testers must manually retrieve page components again when moving tests between instances. ## Example custom UI testing {#custom-ui-test-steps__section_oph_4ts_4fb} You can use the list of retrieved components to design custom UI test steps. For example, suppose that you want to test reviewing and commenting on a Knowledge Base article. A Knowledge Base article contains several page components that require custom UI steps to test. Figure 1. Example Knowledge article page For example, these page components require custom UI test steps. 1. The number of article views. 2. The buttons to mark the article as Helpful. 3. The text area to Leave a comment. {#custom-ui-test-steps__ol_nkz_p5f_pfb} These steps demonstrate custom UI testing on a Knowledge Base article. The example test consists of these existing and custom UI test steps. 1. Navigate to Module. Navigate to the 'Published' module in the 'Knowledge' application. 2. Open an Existing Record. Open the 'Knowledge' form with id 'Knowledge: KB0011110'. 3. Click a UI Action. Click UI Action 'View Article' on 'Knowledge' form. 4. Assert Text on Page (Custom UI). Assert that the text 'developers' is on the page. 5. Set Component Values (Custom UI). Set the components on the page as follows: 'Textarea \ \[article_comments\]' = Update with actual article rather than URL to article elsewhere. 6. Click Component (Custom UI). Click the component: 'Button \: Comment'. 7. Assert Text on Page (Custom UI). Assert that the text 'Update with actual article rather than URL to article elsewhere.' is on the page. {#custom-ui-test-steps__ol_h5s_brs_4fb} Figure 2. Example test steps for a knowledge base article test ## Custom UI component version and order {#custom-ui-test-steps__section_ptz_sxc_jlb} When you select a component in any of the custom UI test steps, the Custom UI version might show up. If there are multiple duplicate components, the order of the components show up. Note: * The Custom UI version shows up only if there are at least two different components with different Custom UI versions. * The Order shows up only if there are duplicate components in the component drop-down menu. You can disambiguate them according to the displayed order. * Both Custom UI version and Order show up if there are multiple duplicate components from different versions. {#custom-ui-test-steps__ul_fwz_m5k_hcc} ## Identifying components {#custom-ui-test-steps__section_x4b_nhb_5mb} Implement an alternative way to identify your component by using the sn-atf-id attribute. This is useful if the name or id attribute of your component is dynamic and changes every time a test runs. Add the sn-atf-id attribute with a consistent value to allow ATF identify your component when running a test. It also allows you to identify your component when building a test. For example, in a button component Note: Starting with the Rome release, if you have exactly one component on the page that has sn-atf-id attribute, ATF finds that component irrespective of any other attributes on that component. ## Improve ATF component identification {#custom-ui-test-steps__section_acq_qxg_hpb} Identify your component using the label path included in the Page area column. Starting with the Rome release, the `sn_atf.element.use_label_path` property has been set to true by default. If a component has the `sn-atf-area` attribute, the Page area column displays the `sn-atf-area` value. If the `sn-atf-area` attribute is not present, the label path for that component is shown in the Page area column. Note: If you have multiple, identically named Label values, the label path helps you identify the correct component. If a component doesn't have an `sn-atf-area` attribute or a label path, the value is displayed as default. When you select the required component from the list and click Submit, the description of the test step also gets updated with more details. * **[Page Inspector](https://www.servicenow.com/docs/fd5e7dAIccYcvMsnmx4_CQ)** Identify the HTML and JavaScript page components in your user interfaces that are available for custom UI testing. Enable automated testing by ensuring that your user interfaces only contain testable page components. * **[Enable and use the page inspector](https://www.servicenow.com/docs/5r5uFayl4CgMQshHik4Gjg)** Enable a developer setting to inspect UI pages that open within the platform. Use the Manual Page Inspector to inspect pages that open in a new tab, such as Service Portal pages. * **[Create a custom UI test](https://www.servicenow.com/docs/j0a0MkJYhmL2P48kS93gMA)** Test components in custom UI pages. * **[Override component test actions](https://www.servicenow.com/docs/5pzGhDoZ5pCcDS7_2SquDg#develop-testable-components)** Change the testing properties of a particular page component using HTML attributes that are specific to Automated Test Framework. * **[Override component data type](https://www.servicenow.com/docs/BiCHM6vVtcVZPJrDZoGKnw)** Use the `sn-atf-data-type` and `sn-atf-data-type-params` attributes to override the type of field displayed in a Set Component Value test step. * **[Select2 functionalities in ATF](https://www.servicenow.com/docs/089wQMvlpf9M8QlaiJ2bug)** Use the Select2 component to search and select your option from a drop-down menu easily.