Skip to main content

How to Run an Exploration

You can run ExploreChimp—targeted UX analytics along SmartTest journeys—in two ways: locally through code agents (Playwright + /testchimp commands in your repository), or on the TestChimp platform (product UI, recipes, and Atlas). Both paths reuse the same analytics idea: checkpointed telemetry tied to screen–state markers so findings map to your product vocabulary.

Locally via Code Agents​

Use this path when a coding agent (for example in your IDE) should drive Playwright SmartTests with the @testchimp/playwright runtime and ExploreChimp enabled. The primary command is /testchimp explore: ExploreChimp is the main task—you choose which UI specs to run, without the full PR workflow from /testchimp test.

How /testchimp explore works​

ExploreChimp is not an unconstrained crawl of arbitrary URLs. It reuses the same browser journeys your SmartTests already execute, then sends structured telemetry (DOM, screenshots, console, optional network and metrics) to TestChimp for analysis.

The unit of attribution is the markScreenState Playwright fixture (registered via installTestChimp in your merged tests/fixtures): each await markScreenState('Screen', 'State') marks a stable UI boundary. Analytics for the interval before a call attach to the previous checkpoint; screenshot and DOM for the current checkpoint attach to that name. Without meaningful markScreenState calls, the pipeline has little structure for bug filing and Atlas alignment—see Screen-State Annotations and Creating Smart Tests.

Typical agent flow:

  1. SmartTests use test / expect from fixtures that call installTestChimp so markScreenState and the reporter apply—see Playwright runtime plugin.
  2. Environment — TESTCHIMP_API_KEY, EXPLORECHIMP_ENABLED, TESTCHIMP_BATCH_INVOCATION_ID (or project id file), and any network / defaults documented under plans/knowledge/ai-test-instructions.md → ## ExploreChimp when you use network analysis.
  3. Scope — The agent runs the chosen Playwright files or folders; correlation uses the batch id so TestChimp can dedupe and attribute work.

Full command reference, prerequisites table, and “what targeted exploratory analytics means”: /testchimp explore.

Same ExploreChimp inside /testchimp test and /testchimp evolve​

The runtime and telemetry model are the same as /testchimp explore; only when ExploreChimp runs and who picks scope differ:

CommandExploreChimp role
/testchimp testOptional Phase 5 after Validate, only when the approved branch plan opts in (cost and target specs). Same flags and markScreenState expectations as a dedicated explore pass. See /testchimp test.
/testchimp evolveOptional, plan-gated step on TrueCoverage-prioritized or otherwise high-signal UI slices after new/changed tests pass and markers are trustworthy. See /testchimp evolve.
/testchimp explorePrimary task: exploration analytics on a deliberately scoped set of UI SmartTests without running the full PR pipeline.

So /testchimp explore is the dedicated entry point; /testchimp test and /testchimp evolve can include the same ExploreChimp pass when your written plan says so.

On TestChimp Platform​

The sections below describe running explorations from the TestChimp web app: recipes, credits, and UI entry points. They complement the local agent + Playwright path above.

Entry Points​

There are several entry points for running explorations, each suited for different use cases:

Via Agent Explorations Tab​

  1. Navigate to the Explorations section
  2. Click "New Exploration"
  3. Select the recipe you want to use
  4. Configure the exploration settings (see Introduction to Explorations for common settings)
  5. Configure any recipe-specific settings
  6. Click "Start Exploration"

This entry point gives you full control over the recipe selection and all configuration options.

Via SmartTests Tab​

You can run explorations directly from the SmartTests section:

Guided by a SmartTest​
  1. Navigate to the SmartTests section
  2. Right-click on any test
  3. Select "Run ExploreChimp"
  4. Choose the recipe (defaults to Bug Source Analytics if SmartTests are present)
  5. Configure the exploration settings
  6. ExploreChimp will navigate your app guided by that SmartTest
Guided by a Test Folder​
  1. Navigate to the SmartTests section
  2. Right-click on any test folder
  3. Select "Run ExploreChimp"
  4. Choose the recipe (defaults to Bug Source Analytics if SmartTests are present)
  5. Configure the exploration settings
  6. ExploreChimp will run tests within that scope, creating journeys for each test (up to the configured number of journeys)
  7. TestChimp intelligently picks the next test to run based on which test covers the most untested ground in the given scope of the test tree

Via Screen Tree Viewer (Screen-Targeted Explorations)​

For screen-targeted explorations:

  1. Navigate to Atlas
  2. Find the screen or screen-state you want to explore
  3. Click the 3-dot menu (⋮) next to the screen or screen-state node
  4. Select "Run ExploreChimp" from the menu
  5. The exploration modal opens with:
    • The selected screen-state(s) pre-populated as target screen-states
    • The "Limit analytics to following screens" setting enabled by default
    • All known tests considered for selection
  6. Choose the recipe and configure settings
  7. Click "Start Exploration"

This workflow is ideal for:

  • Focused testing: Testing specific features or workflows
  • Efficient credit usage: Running analytics only on areas of interest
  • Targeted bug discovery: Finding issues in specific parts of your application

Exploration Configuration​

When you start an exploration, you can configure various settings:

Exploration Configuration
Exploration configuration settings

Common Settings​

All explorations share common configuration options (see Introduction to Explorations for details):

  • Advanced settings (test creation config, target screen-state config, update screen-state annotations)
  • Limits (max credits, max journeys)
  • Release and model selection

Recipe-Specific Settings​

Each recipe may have additional configuration options specific to its purpose. Refer to the individual recipe documentation for details:

Limiting Analytics to Specific Screen-States​

By default, ExploreChimp runs analytics (bug source analysis) after each screen-state change it encounters. However, you can limit analytics to run only when the agent is in specific screen-states of interest.

Limit Analytics to Screens Setting
Advanced settings: Limit analytics to specific screens

How it works:

  • Enable the "Limit analytics to following screens" checkbox in the Advanced Settings section
  • Select the screens where you want analytics to run using the multi-select tree dropdown
  • Analytics will be skipped for screen-states that don't match your selection

This feature is particularly useful when:

  • You want to focus on specific areas of your application
  • You want to reduce credit consumption by analyzing only critical screen-states
  • You're running targeted explorations on specific features or workflows