Native app testing

Learn how to evaluate your app's functionality using Retool's native testing feature.

Native testing Availability
Cloud	Closed beta	Business Enterprise
Self-hosted Edge 3.286 or later	Closed beta	Business Enterprise
Self-hosted Stable 3.284 or later	Closed beta	Business Enterprise

Use native testing to create, edit, and run tests from within the Code tab of the App IDE. Use this guide to learn more about native testing and how to use it to ensure that your app runs as expected in any scenario.

Create tests

In the Tests section of the Code tab, click to create a new test. Name your test, and choose the method that you want to use:

• Manual: Add an empty test and configure each step manually.
• Record: Record interactions with your app and automatically generate a test based on your actions.

Record tests

Retool's test recording mechanism enables you to write tests more quickly than you could from scratch. The recording works by capturing your activity in the editor and translating that into a test.

Use the Record button to begin a recording. Start a recording at any point where you want to validate behavior. Each recording automatically captures the app state at the time the recording starts, so you don't need to include setup steps unless you wish to have tests for those events.

When a recording is running, the Retool editor behaves the same way it would if you were manually testing it. Be sure that any actions you take during the recording are safe for your app and data.

As you record, you’ll see the actions that Retool captures on the left sidebar. This gives you an indication of how long the generated test will be.

Click Stop to conclude the recording. Retool automatically creates a test based on the events that occurred during the recording. You may edit any generated test post-recording so that it is most useful to you.

Each test runs in isolation, and doesn’t make network calls. This means you do not need to worry about any live resources being run or app state being changed when you run tests. This also means you do not need to write any “tear down” logic for your tests.

In order to ensure a good recording output, use the following best practices:

• Do not start a recording while the app has queries in progress.
• Wait for queries to complete before ending a recording.

Test composition

Each test is composed of a series of steps that are run together to represent a series of user actions and resulting changes to the app state.

You can edit any part of a test, including the following:

• Rename a test by double clicking on its name.
• Edit the steps executed in a test by clicking the icon next to a step.
• Delete a step from a test by clicking its icon.
• Delete an entire test by hovering over the name and clicking the icon.

Changes are autosaved.

Global app state

The first step in each test is the Global app state. This step is made up of a set of preconditions, which define the app state before you started the test.

You can edit preconditions in the following ways:

• Add preconditions by clicking the icon at the top of the preconditions list.
• Remove preconditions by hovering over the name and clicking the icon.
• Edit precondition values by clicking the precondition name and opening up the value field. You can type directly in the value field to change it.

Steps

Each step corresponds with an action either directly taken by a user or indirectly triggered by their behavior. Click the icon to add a new step. You can test the following actions:

• Component event trigger: Configure the Component and Event that you want to trigger.
• Resource query run: Configure the Component and Event that you want to trigger.
• JS query run: Configure the Component and Event that you want to trigger.
• Value change: Configure the Component, Field, and Value that you want to change.

Each step is tested using the validation of assertions and mocks.

Assertions

Assertions are statements that evaluate as true once the original action in the step is complete. For example, a Resource query run action might result in updated component or variable values, so an assertion would represent the updated value.

If one or more assertions evaluate as false, the step fails.

You can create the following types of assertions:

• Custom: A custom assertion using the Jest testing framework.
• Model update: An update to the app state.
• Run query: A query was triggered.
• Utils API: A method from the Utils API was called.

You can edit assertions in the following ways:

• Add an assertion by clicking the button at the top of the assertions list.
• Edit an assertion by changing dropdown values or text input values.
• Delete an assertion by hovering over the assertion and clicking the icon on the right side.
• Write an assertion using the JEST framework by creating a Custom assertion from the dropdown options.

Mocks

Query mocks represent any network calls that are run as a result of user action. When you record a test, these calls are executed. During any subsequent test runs, these calls are mocked in order to prevent changes to your data.

You can edit query mocks in the following ways:

• Add query mocks by clicking the icon at the top of the Mocks list.
• Remove query mocks by hovering over the name and clicking the icon.
• Edit mocked responses by clicking the query name and opening up the value field. You can type directly in the value field to change the mocked response.

Run tests

Tests must be run manually. At the top of your list of steps, click Run all to run each step.

Known limitations

This feature is still in development and there are several known limitations, which are listed below. If your app contains one of the known limitations or bugs, the recording will likely generate assertions that fail. Retool recommends deleting these assertions from your tests.

• Tests do not currently support mocking any calls to workflows from apps. Workflows will be called rather than being mocked if they are in a test flow.
• Tests do not currently support mocking for AI Action queries. Unexpected behavior may occur if AI queries are in a test flow.
• Tests may not evaluate correctly on apps that use certain beta features, such as app functions.
• Tests using non-deterministic Javascript (e.g. Math.random) are not currently supported.
• Date mocking is not available for Date calls in user-imported JS libraries. Retool recommends either using custom assertions to rewrite assertions so that they do not use dates, or using the Date library directly so that dates can be mocked.
• JS code that uses fetch() calls are not supported. Retool recommends re-writing fetch() calls to use a Retool query.
• Queries that are set to run periodically, and JS code that includes setInterval usage are not currently supported.
• Tests with deprecated or legacy components may cause unexpected behavior.
• Function calls to window from preloaded Javascript are not currently supported.
• For tests involving repeatable components (such as List Views), certain parts of generated assertions may not be editable post-recording.
• Tests do not support certain objects, such as localStorage.
• AlaSQL NOW() usage is not currently date-mocked.