---
sourceDocument: Australia Build or modify applications
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/application-development

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia Build or modify applications

ft:clusterId :

    - cadev

bundleId :

    - cadev

workflow :

    - Development, Data, and Analytics


---

# List and Related List

# List and Related List {#ariaid-title1}

Release version: Australia  
Updated March 12, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 7 minutes to read  
Validate the functionality and visibility of records and UI actions in lists and related lists.
Test Agent can now generate ATF tests that use List and Related List test steps, extending test coverage beyond form interactions to include list view operations such as validating visibility and applying
filters. See [Test Agent](https://servicenow-prod.fluidtopics.net/KjtigkvrIJ37RW9knHUFKQ "Use Test Agent to streamline the process of authoring, running, and troubleshooting tests autonomously from a single interface. Test Agent generates test coverage for code produced by Build Agent, executes tests, and performs root cause analysis on failures, enabling end‑to‑end build‑to‑test workflows within a single development session.") for more information.  
Consider the following while creating the tests:

* Related lists has three sources: default platform relationships (Attachments, Approvals, Journal Entries), reference fields on the table, and custom relationships defined in `sys_relationship`. Only test related lists that have custom logic (client scripts, UI policies, or custom relationships) affecting their behavior. Default platform related lists without custom logic don't require testing.
* Before deciding a related list has no custom behavior, search the target table for matching client scripts (`sys_script_client`), UI policies (`sys_ui_policy`), and custom relationships (`sys_relationship`) that reference related list operations.
* Related list parameters use the format `<child_table>.<field>` (for example, `task.parent`) or `REL:<sys_id>` for custom relationships. These values must be looked up for each table.
* When a related list is confirmed to have custom logic, test all applicable methods: `relatedListVisibility` for visibility, `applyFilterToList` for filtering, `recordPresentInList` for membership, `openRecordInList` for navigation, and `listUIActionVisibility` for UI Actions. `clickListUIAction` should be used only when the specific action behavior needs verification, not as a default check.
* ATF list steps are part of a 13-category ATF namespace. Select `atf.list` for list/related list interactions; use `atf.form` for form field interactions, and `atf.uiTestScript` for custom UI not reachable through standard form or list steps.
{#test-steps-list-related-list__ul_z42_cjd_jkc}

## Validate Related List Visibility {#ariaid-title2}

Validate the visibility of the selected related lists on a form.
{#atf-validate-related-list-visibility__table_vgk_zs4_nhb__entry__2}

| Field | Description |
|-|-|
| Execution order | Integer specifying the order in which the test executes this step. As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them. You can change this default order by editing the Execution order values. |
| Application | Application scope in which the system runs this step. |
| Active | Option to activate this test step for use. |
| Test | Name of the test that you're adding the step to. |
| Step config | Name of the step. |
| Notes | Notes about the test step. |
| Table | Name of the table of the parent form where related list visibility is validated. |
| Visible | List of related lists to assert as visible. |
| Not visible | List of related lists to assert as not visible. |
[Table 1. Inputs]

{#atf-validate-related-list-visibility__table_vgk_zs4_nhb}

## Apply Filter to List {#ariaid-title3}

Apply a filter to a list to find the required record.
{#atf-apply-filter-list__table_vgk_zs4_nhb__entry__2}

| Field | Description |
|-|-|
| Execution order | Integer specifying the order in which the test executes this step. As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them. You can change this default order by editing the Execution order values. |
| Active | Option to activate this test step for use. |
| Application | Application scope in which the system runs this step. |
| Test | Name of the test that you're adding the step to. |
| Step config | Name of the step. |
| Notes | Notes about the test step. |
| List type | Option to select the type of list. * List * Related list {#atf-apply-filter-list__ul_ajs_kp4_y3b} |
| Assert Type | Specifies the assertion on executing the test step: * At least one matching record found: The step succeeds if there is at least one matching record. * No matching record found: The step fails if there is any matching record. * One matching record found: The step succeeds if there is exactly one matching record. {#atf-apply-filter-list__ul_p4b_fyk_q3b} |
| Table | If the List type is List, this field is the table of the opened list. If the List type is Related list, this field states the name of the table of the parent form where the list belongs. |
| Related List | The related list to apply a filter to. Note: This field is available when Related list is selected from List type. |
| List filter | Filter conditions to apply to the list. |
[Table 2. Inputs]

{#atf-apply-filter-list__table_vgk_zs4_nhb} {#atf-apply-filter-list__d5b_d2p_tw__entry__2}

| Field | Description |
|-|-|
| first_record | The first record found in the list after applying the indicated filter. |
[Table 3. Outputs]

{#atf-apply-filter-list__d5b_d2p_tw}

## Validate Record Present in List {#ariaid-title4}

Validate the presence of a record in a list. A valid form must be open and the list containing the record must be visible to proceed.
{#atf-validate-record-present__table_vgk_zs4_nhb__entry__2}

| Field | Description |
|-|-|
| Execution order | Integer specifying the order in which the test executes this step. As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them. You can change this default order by editing the Execution order values. |
| Application | Application scope in which the system runs this step. |
| Active | Option to activate this test step for use. |
| Test | Name of the test that you're adding the step to. |
| Timeout | Number of seconds allowed before the step fails. If the validation fails, the system repeats the step until it reaches the duration of the timeout. If the validation fails after the timeout duration has passed, the step fails. |
| Step config | Name of the step. |
| Notes | Notes about the test step. |
| List type | Option to select the type of list. * List * Related list {#atf-validate-record-present__ul_f1s_xjy_s3b} |
| Assert type | Specifies the assertion on executing the test step: * Record is present in the list * Record is not present in the list {#atf-validate-record-present__ul_bgv_mxx_s3b} |
| Table | Name of the parent table where the list belongs. |
| Related list | The related list which has the record to validate. Note: This field is available when Related list is selected from List type. |
| Record | The record whose presence is validated. |
[Table 4. Inputs]

{#atf-validate-record-present__table_vgk_zs4_nhb}

## Open a Record in List {#ariaid-title5}

Open a specific record in a list.
{#atf-open-record-list__table_vgk_zs4_nhb__entry__2}

| Field | Description |
|-|-|
| Execution order | Integer specifying the order in which the test executes this step. As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them. You can change this default order by editing the Execution order values. |
| Application | Application scope in which the system runs this step. |
| Active | Option to activate this test step for use. |
| Test | Name of the test that you're adding the step to. |
| Step config | Name of the step. |
| Notes | Notes about the test step. |
| List type | Option to select the type of list. * List * Related list {#atf-open-record-list__ul_b1g_qwd_t3b} |
| Table | Name of the parent table where the list belongs. |
| Related List | The related list which has the record to open. Note: This field is available when Related list is selected from List type. |
| Record | The record to be opened. |
[Table 5. Inputs]

{#atf-open-record-list__table_vgk_zs4_nhb}

## Validate List UI Action Visibility {#ariaid-title6}

Validate that a UI action is visible in a list. If you're impersonating a user, the visibility of a UI action can change depending on the user being impersonated.
{#atf-validate-listUI-action-visibility__table_vgk_zs4_nhb__entry__2}

| Field | Description |
|-|-|
| Execution order | Integer specifying the order in which the test executes this step. As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them. You can change this default order by editing the Execution order values. |
| Application | Application scope in which the system runs this step. |
| Active | Option to activate this test step for use. |
| Test | Name of the test that you're adding the step to. |
| Step config | Name of the step. |
| Notes | Notes about the test step. |
| List type | Option to select the type of list. * List * Related list {#atf-validate-listUI-action-visibility__ul_snm_2v5_y3b} |
| Table | Name of the table of the parent form. |
| Related List | The related list which has the UI actions. Note: This field is available when Related list is selected from List type. |
| Visible | List of UI actions to assert as visible. |
| Not visible | List of UI actions to assert as not visible. |
[Table 6. Inputs]

{#atf-validate-listUI-action-visibility__table_vgk_zs4_nhb}

## Click a List UI Action {#ariaid-title7}

Select a list UI action in a list on a form.
{#atf-click-list-UI-action__table_vgk_zs4_nhb__entry__2}

| Field | Description |
|-|-|
| Execution order | Integer specifying the order in which the test executes this step. As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them. You can change this default order by editing the Execution order values. |
| Application | Application scope in which the system runs this step. |
| Active | Option to activate this test step for use. |
| Test | Name of the test that you're adding the step to. |
| Step config | Name of the step. |
| Notes | Notes about the test step. |
| List type | Option to select the type of list. * List * Related list {#atf-click-list-UI-action__ul_js4_k2p_53b} |
| Table | Name of the table where the UI action belongs. |
| Related list | The related list which has the UI actions. Note: This field is available when Related list is selected from List type. |
| List action | The list UI action to be clicked. |
| Action type | The type of UI action to be clicked. |
| Apply to | The record on which the UI action is applied. |
| Assert type | The assertion made by the step when executed. * None: Click a UI action and continue without making an assertion. * Page reloaded or redirected: Click a UI action, and assert that the page was reloaded or redirected. This assert type doesn't assert form submission. {#atf-click-list-UI-action__ul_fpx_lfp_53b} |
| Record | The record to which the UI action is applied. Note: This field appears when you choose Single record in the Apply to field. |
[Table 7. Inputs]

{#atf-click-list-UI-action__table_vgk_zs4_nhb}