Skip to navigation
Actions

goTo

The goTo action navigates the browser to a specified URL. This is typically used to start a test at a specific page or navigate between pages during a test.

You can specify the target URL directly as a string, or use an object for more options:

  • String Shorthand: Provide the full URL, a path (starting with /), or a variable reference directly as the value for the goTo key. If a path is provided, it navigates relative to the current URL or the global origin if set in the configuration.
  • Object Format: Use an object with the following properties:
    • url: (Required) The URL to navigate to. Can be a full URL, a path, or a variable reference.
    • origin: (Optional) Protocol and domain prepended to url when url is a path. Overrides the global origin if set.
    • params: (Optional) Query parameters to append to the resolved URL. Merged with config-level originParams.
    • surface: (Optional) The browser (session, window, or tab) to navigate. Omit to navigate the active tab. Naming a browser that isn’t open yet opens it. To open a browser with explicit launch options (headless, window size, viewport) before navigating, use startSurface.
    • newTab / newWindow: (Optional) Open the URL in a new tab or window instead of navigating the current one. goTo is the only action that opens tabs and windows.

For comprehensive options, see the goTo reference.

Examples

Here are a few ways you might use the goTo action:

{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate to example.com.",
          "goTo": "https://example.com"
        }
      ]
    }
  ]
}

Assumes the browser is currently at https://example.com or a global origin is set.

{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate to the /about path.",
          "goTo": "/about"
        }
      ]
    }
  ]
}
{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate to example.com using object format.",
          "goTo": {
            "url": "https://example.com"
          }
        }
      ]
    }
  ]
}
{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate to Google search using a specific origin.",
          "goTo": {
            "url": "/search",
            "origin": "https://www.google.com"
          }
        }
      ]
    }
  ]
}

Query parameters

You can append query parameters to a URL using the params option. This is useful for authentication tokens or tracking parameters.

  • Step-level params: An object specifying query parameters to append to the URL. Applies to all URLs, both relative and absolute. Values support environment variable substitution with $VAR syntax.
  • Config-level originParams: Default query parameters in your configuration file that apply to relative URLs resolved against origin. Step-level params merge on top, with step keys taking precedence on collision.

When your URL contains a fragment such as /page#section, query parameters are inserted before the fragment, giving /page?token=value#section.

Values in params and originParams are embedded directly in request URLs and appear in test results, logs, and reports. Avoid storing long-lived secrets in these fields.

Append query parameters to a URL

{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate to dashboard with testing token.",
          "goTo": {
            "url": "/dashboard",
            "origin": "https://my-app.com",
            "params": {
              "__clerk_testing_token": "$CLERK_TESTING_TOKEN"
            }
          }
        }
      ]
    }
  ]
}

Use config-level default parameters

Set originParams in your configuration file to avoid repeating parameters on every step. For example, when testing a Clerk-protected application, set the testing token once:

Configuration file:

{
  "origin": "https://my-app.com",
  "originParams": {
    "__clerk_testing_token": "$CLERK_TESTING_TOKEN"
  }
}

Test specification:

{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate to dashboard (testing token applied automatically).",
          "goTo": "/dashboard"
        }
      ]
    }
  ]
}

Tabs, windows, and browsers

goTo is the only action that opens new tabs, windows, and browsers. Name what you open, then any later step can act in it with a surface reference.

  • newTab: Open the URL in a new tab of the target window and focus it. true opens an anonymous tab; a string (or { "name": … }) names the tab. false disables.
  • newWindow: Open the URL in a new window and focus it. true, a name string, or { "name": …, "tab": … }, where tab names the window’s first tab. false disables.
  • newTab and newWindow are mutually exclusive on one step.
  • surface: Without an opener, this selects the browser, window, or tab to navigate. It opens the browser if it isn’t running yet. With newTab, it selects the window the tab opens in.

Open a second browser

{
  "tests": [
    {
      "steps": [
        {
          "description": "Open a second, named browser session for the admin account.",
          "goTo": {
            "url": "https://my-app.com/admin",
            "surface": { "browser": "firefox", "name": "admin" }
          }
        },
        {
          "description": "A bare engine keyword opens (or selects) a browser of that engine.",
          "goTo": { "url": "https://my-app.com", "surface": "chrome" }
        }
      ]
    }
  ]
}

Open a named tab, then act in it

{
  "tests": [
    {
      "steps": [
        {
          "description": "Open the checkout in a new tab named 'cart'.",
          "goTo": {
            "url": "https://my-app.com/checkout",
            "newTab": "cart"
          }
        },
        {
          "description": "Click in the cart tab by name.",
          "click": {
            "elementText": "Place order",
            "surface": { "browser": "chrome", "tab": "cart" }
          }
        }
      ]
    }
  ]
}

Open a named window with a named first tab

{
  "tests": [
    {
      "steps": [
        {
          "description": "Open the admin console in its own window.",
          "goTo": {
            "url": "https://my-app.com/admin",
            "newWindow": { "name": "admin", "tab": "overview" }
          }
        }
      ]
    }
  ]
}
{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate the admin window to the orders page.",
          "goTo": {
            "url": "https://my-app.com/orders",
            "surface": { "browser": "chrome", "window": "admin" }
          }
        }
      ]
    }
  ]
}

See Test across multiple tabs, windows, and browsers for the full selector grammar. It covers names, indexes, -1 for newest, and title and URL criteria. It also covers addressing tabs a page opens itself, and driving multiple browsers at once.

Wait conditions

The goTo action supports advanced waiting conditions after navigation to ensure pages are fully loaded and ready before the next step runs.

When using the object format, you can configure:

  • timeout: (Optional) Maximum time in milliseconds to wait for all conditions to be met. If exceeded, the goTo action fails (default: 30000).
  • waitUntil: (Optional) Object specifying conditions to wait for:
    • networkIdleTime: (Optional) Wait for network activity to be idle, meaning no new requests, for this duration in milliseconds. This check always runs and you can’t skip it. Set it to 0 to treat the page as network-idle as soon as the first check completes, rather than waiting for a quiet period. Defaults to 500.
    • domIdleTime: (Optional) Wait for DOM mutations to stop for this duration in milliseconds. This check always runs; you can’t skip it. Set it to 0 to treat the DOM as stable as soon as the first check completes rather than waiting for a quiet period (default: 1000).
  • find: (Optional) Wait for a specific element to be present in the DOM. At least one of selector or elementText must be specified.
    • selector: (Optional) CSS selector for the element to wait for.
    • elementText: (Optional) Display text of the element to wait for. Doc Detective matches this against the element’s full visible text with whitespace normalized, so text that a framework splits across several nodes still matches. To match a substring with a regular expression instead of the whole text, wrap the value in slashes (/pattern/). See How text matching works.

Wait for network idle

Navigate to a page and wait for network activity to settle.

{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate and wait for network idle.",
          "goTo": {
            "url": "https://www.example.com",
            "waitUntil": {
              "networkIdleTime": 500
            }
          }
        }
      ]
    }
  ]
}

Wait for a specific element

Navigate to a dashboard and wait for a specific element to appear.

{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate to dashboard and wait for it to load.",
          "goTo": {
            "url": "https://www.example.com/dashboard",
            "waitUntil": {
              "find": {
                "selector": "[data-testid='dashboard-loaded']"
              }
            }
          }
        }
      ]
    }
  ]
}

Wait for element with text

Wait for an element with specific text to appear.

{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate to status page and wait for operational message.",
          "goTo": {
            "url": "https://www.example.com/status",
            "waitUntil": {
              "find": {
                "elementText": "System operational"
              }
            }
          }
        }
      ]
    }
  ]
}

Combine multiple wait conditions

Use multiple wait conditions together with a custom timeout.

{
  "tests": [
    {
      "steps": [
        {
          "description": "Navigate to app with comprehensive wait conditions.",
          "goTo": {
            "url": "https://www.example.com/app",
              "timeout": 60000,
            "waitUntil": {
              "networkIdleTime": 500,
              "domIdleTime": 1000,
              "find": {
                "selector": ".main-content",
                "elementText": "Dashboard"
              }
            }
          }
        }
      ]
    }
  ]
}