Creating a Test

​

Prerequisites

​

Creating a Test

1. Navigate to the tests tab on the left
2. Click “Create New Test”
3. Enter a title, select a test suite, and provide an entrypoint URL (the starting point for your test)
4. Click “Launch Browser”

Learn more: For detailed information about the persistent browser/device instance and its controls, see the Remote Screen documentation.

Testing a native mobile app? Instead of an entrypoint URL, mobile tests target a mobile app on a simulator or emulator. See the Mobile Apps guide for supported devices and build requirements.

​

Building Your Test

1. Recorded Steps - Precise coordinate-based actions that replay exactly as recorded and self-heal when the UI changes
2. AI Steps - Natural language instructions that adapt to your UI dynamically
3. API Steps - Network requests to endpoints for seeding, setup, and teardown of test resources
4. Code Steps - Run sandboxed Python to transform data, manage files, call APIs, or drive the browser
5. Modules - Reusable collections of steps that can be shared across multiple tests
6. Trigger Run - Trigger another Docket test and pass variables between them

​

API Steps

• Test Setup: Creating test data, user accounts, or resources before the main test flow
• Test Seeding: Populating databases or systems with necessary data
• Dynamic CRUD Operations: Create resources, store their IDs, then update or delete them later in the test
• Test Teardown: Cleaning up resources after test completion

Extracting Response Data

{
  "response": {
    "data": [
      {"resource_id": 123, "other_data": "..."},
      {"resource_id": 456, "other_data": "..."}
    ]
  }
}

Dynamic CRUD Example

1. Create a product via POST and extract its ID to @product_id
2. Update the product via PUT to https://api.example.com/products/@product_id
3. Use the product in your UI test flow
4. Delete the product via DELETE to https://api.example.com/products/@product_id for cleanup

​

Code Steps

• Generate or transform test data (e.g. a unique payload or a signed token)
• Read an uploaded file or browser download and extract a value
• Call an external API and save part of the response
• Drive the browser directly with Playwright

How It Works

import requests

resp = requests.get("https://api.ipify.org?format=json")
variables["my_ip"] = resp.json()["ip"]

Storing variables: Values must be strings; wrap others with str(...) or json.dumps(...). Use plain literal keys (variables["token"]), not dynamically computed ones, so Docket can detect the variable names.

Browser Access

page = context.pages[0]
variables["page_title"] = page.title()

Files

• The working directory holds your uploaded files. Open them by name: open("data.csv").
• Files your code creates persist for later steps in the same run.
• Browser-downloaded files live under /tmp/docket-downloads/; open them with the full path.

Runtime & Limits

• Synchronous Python only (no async/await).
• Default timeout of 120 s, configurable per step.
• Importable: the full standard library plus requests, PyPDF2, numpy, PIL (Pillow), openpyxl, docx, and faker. Nothing is pre-imported, so import what you use.
• Outbound HTTP(S) to public endpoints works; localhost and private/LAN addresses are blocked unless the run uses a tunnel.
• No process spawning (subprocess, os.system, multiprocessing).

Generate Code with AI

Results

• STDOUT / STDERR: captured output (STDERR turns red when the step fails)
• Created Variables: values written to variables, shown as @name = "value"
• Created Files: files the step wrote

​

Modules

• Create and manage modules in the “Modules” section of Docket
• Compose with any step type: Modules can contain AI steps, recorded steps, and API steps
• Can nest: A step_module step inside a module references another module (up to 5 levels deep)
• Universal: One module works across every browser viewport, iOS device, and Android device — modules inherit the running screen’s config rather than carrying their own
• CRUD interface: The module creation interface is similar to test creation, with a remote screen for recording interactions

Variables in Modules

• Can reference variables: Modules can use variables (like @user_email or @auth_token) that are defined in the tests where the module is used
• Can extract from API calls: Modules can create new variables by extracting values from API response bodies within the module
• Cannot define variables: Modules cannot create their own text, email, or random alphanumeric variables
• No file uploads: Modules do not support file management

• Standard navigation sequences
• Common setup or teardown operations
• Shared API authentication workflows
• Repeated multi-step interactions

​

Trigger Run

• Trigger any test: Select another test in your workspace to run as a step
• Variable mapping: Pass variables from the current test to the triggered test, allowing data to flow between tests
• Run skipped tests: Trigger Run is the programmatic way to execute tests with Suite Run Behavior set to “Skipped”

​

Lifecycle Hooks

1. Setup module: Create resources via API POST requests, extract their IDs to variables (e.g., @test_user_id, @order_id)
2. Test: Use these resources in your UI test flow by referencing the variables
3. Teardown module: Delete the resources via API DELETE requests using the stored IDs

​

Test Variables

​

Text Variables

​

Dynamic Variables

​

Email Variables

​

Extracted Variables

​

Advanced Test Configuration

​

Browser Zoom Level

​

Test Retries

​

Suite Run Behavior

• Included (default): Test runs in all scenarios
• Skipped: When a test suite is triggered to which this test belongs, this test is skipped and not run. The only way to run this test is via a Trigger Run step or manually through the UI

​

Persist Self-Healed Actions

​

File Download Behavior

• Save Only (default): The file is saved but its contents are not read
• Ingest Content: The file is saved and its contents are extracted and injected into the agent’s context, allowing subsequent assert steps to verify file contents

​

Typing Speed

​

Two-Factor Authentication (2FA)