Tutorials

Learn to write UTAM tests with live-coding tutorials on the UTAM.dev tutorials site.

The tutorials teach you how to write JSON page objects for your application components, as well as test code that calls the page object methods. Tutorial tests are written in JavaScript.

Each tutorial includes instructions and live coding panels.

Introduction: Start here to complete the full tutorial experience in order.
Hello World: Outline the mental model of creating a page object for a component.
Write a Test: Use the same HTML and JSON as the Hello World tutorial to explain the basics of writing a test with UTAM code.
Root Page Objects: Explain the importance of the root page object.
Basic Elements: Break down the JSON page object as a tree of elements that map to the DOM of the corresponding page.
Web Components and Shadow DOM: Learn how to cross a shadow boundary using UTAM.
Simple Selectors: Learn how to select things in a page with UTAM JSON grammar.
Selector String Parameter: Write a CSS selector that accepts a string dynamically.
Selector Number Parameter: Write a CSS selector that accepts a number dynamically.
Basic Actions: Call the basic actions API to get, set, and wait for UI element state without walking the DOM.
Editable Actions: Create an element with "type": "editable" that has access to basic action APIs that can set and clear text.
Clickable Actions: Test an app with clickable buttons.
Lists: Return all the elements from a list.
Get List Item by Index: Get a list item by its index.
Get List Items by Pattern: Use a pattern to select items from a list.
Get List Items by Attribute: Use a selector to target specific elements you need in a test.
Filter a List of Elements Using stringEquals: When you can't use a selector to get the elements you need, use an element filter.
Filter a List of Elements Using stringContains: When you can't use a selector to get the elements you need, use an element filter.
Filter a List of Elements Using findFirst: Return only the first filtered element.
Filter a List of Elements Using isTrue: Use the isTrue matcher to filter a list of Trailhead units to show only visible (incomplete) units.
Custom Elements: Test page objects that are composed of other page objects.
Filter Custom Elements: Use declarative filtering in a JSON page object to allow a test to get a list of contacts filtered by a search string in the contact's title. This use case builds on the Custom Elements and Filter a List of Elements Using stringContains tutorials.
Nullable Elements: Use a nullable element for an element that isn't always present on the page.
Container Elements: Select a component with a slot or a div acting as a container for other components.
Compose Method: Compose several actions into a single method by declaring them in a compose array.
Compose Custom Actions: Combine several actions applied to the basic elements into one composed method.
Compose vs. Expose Root Element: Expose an element's root as a public editable element or declare compose methods to set and get the value.
Compose Argument References: Reuse an argument in multiple statements in a compose method.
Chain Compose Statements: Chain multiple compose statements in a test.
Imperative Extensions: Create reusable utility code to address complex use cases that aren't supported in UTAM's JSON grammar.
Explicit Wait: Simulate a UI test that waits for an element to appear as the result of a user action.
Wait for an Element Before Loading: Intercept the load method and override it by adding an explicit wait for an element to be rendered.
Todo App: Experiment writing UTAM page objects and test code against a real app.