docs(perps/agentic): eval-ref vocabulary rename, HUD propagation, flow system

[abretonc7s]

Description

Adds a deterministic recipe system for agentic validation of the perps feature. Recipes are JSON files that describe step-by-step app interactions (navigate, press, type, assert) — executed against a running app via CDP. They replace manual testing with reproducible, token-efficient automation.

Why recipes?

For agents doing PR review or bug fixing: An agent can generate a recipe that opens a position, sets TP/SL, closes it — and record the execution as video evidence. One JSON file replaces dozens of CDP tool calls, saving inference tokens and producing consistent results.

For developers working with agents on features (recipe-driven development): Write the recipe first — define expected navigation, interactions, and assertions — then implement the feature until the recipe passes. Like TDD but for agent workflows: define the expected output, iterate until green, get a fully reproducible validation artifact. Existing Gherkin scenarios from PRs can be directly migrated to recipes with 1:1 step mapping.

Composability via flow_ref: Common operations (open position, create TP/SL, close position) are packaged as reusable flows. A recipe composes flows instead of repeating raw steps — 4 lines of flow_ref replace 40 lines of navigate/press/wait.

What's in this PR

• 12 parameterized flows — trade-open-market, trade-close-position, tpsl-create, tpsl-edit, order-limit-place, order-limit-cancel, position-add-margin, market-discovery, market-watchlist, activity-view, select-account, setup-testnet
• validate-recipe.sh — recipe runner with flow_ref composition, wait_for condition polling, HUD overlay, pre-condition checks, {{param}} templating
• wait_for action — condition-based polling replacing all blind wait steps (route, testID visibility, or arbitrary expression)
• testID additions — keypad keys, tab bars, order view buttons, market header — enabling recipe-driven navigation without coordinates
• AgentStepHud — __DEV__-only overlay showing current step ID during recipe execution
• Team directory structure (teams/<team>/flows/, evals/, recipes/, pre-conditions.js)

Lifecycle recipe (used for validation video)

This recipe composes 4 flows to validate a complete trade lifecycle — the exact JSON that validate-recipe.sh executes (teams/perps/recipes/full-trade-lifecycle.json):

{
  "title": "Full BTC trade lifecycle — mainnet start, testnet switch, open, TP/SL, close",
  "validate": {
    "runtime": {
      "steps": [
        { "id": "nav-wallet-home", "action": "navigate", "target": "WalletView" },
        { "id": "switch-mainnet", "action": "toggle_testnet", "enabled": false },
        { "id": "wait-mainnet", "action": "wait_for",
          "expression": "JSON.stringify({isTestnet:Engine.context.PerpsController.state.isTestnet})",
          "assert": { "operator": "eq", "field": "isTestnet", "value": false } },
        { "id": "nav-perps-home", "action": "navigate", "target": "PerpsHomeView" },
        { "id": "wait-perps-home", "action": "wait_for", "route": "PerpsMarketListView" },
        { "id": "ensure-testnet", "action": "flow_ref", "ref": "setup-testnet" },
        { "id": "verify-provider", "action": "eval_ref", "ref": "providers",
          "assert": { "operator": "contains", "value": "hyperliquid" } },
        { "id": "open-long-btc", "action": "flow_ref", "ref": "trade-open-market",
          "params": { "symbol": "BTC", "side": "long", "usdAmount": "10", "leverage": "2" } },
        { "id": "wait-position", "action": "wait_for", "timeout_ms": 10000,
          "expression": "...",
          "assert": { "operator": "eq", "field": "found", "value": true } },
        { "id": "create-tpsl", "action": "flow_ref", "ref": "tpsl-create",
          "params": { "symbol": "BTC" } },
        { "id": "close-position", "action": "flow_ref", "ref": "trade-close-position",
          "params": { "symbol": "BTC" } },
        { "id": "wait-closed", "action": "wait_for", "timeout_ms": 10000,
          "expression": "...",
          "assert": { "operator": "eq", "field": "found", "value": false } }
      ]
    }
  }
}

Result: 14/14 steps pass, composing 4 nested flows (34 total steps across flows).

Risk profile

Shell scripts + JSON schemas — dev-only tooling, not shipped in production builds. React component changes limited to adding testID props (no logic changes). AgentStepHud.tsx gated behind __DEV__.

Changelog

CHANGELOG entry: null

Related issues

Internal perps agentic tooling — no external ticket.

Manual testing steps

Feature: Agentic recipe validation

  Scenario: Full trade lifecycle via recipe runner
    Given Metro and CDP bridge are connected to a running app
    And wallet is unlocked with testnet-capable account
    When developer runs: bash scripts/perps/agentic/validate-recipe.sh scripts/perps/agentic/teams/perps/recipes/full-trade-lifecycle.json
    Then recipe switches to testnet, opens BTC long, creates TP/SL, closes position
    And all 14 top-level steps pass (composing 4 nested flow_refs)
    And HUD overlay shows current step ID on screen during execution

  Scenario: Dry-run validates JSON without app
    When developer runs with --dry-run flag
    Then all steps are parsed and resolved without executing against the app

Screenshots/Recordings

Before

N/A — new tooling, no prior state.

After

full-trade-lifecycle.mp4

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

---

Note

Low Risk
Mostly adds/renames testID props across Keypad, Tabs, and Perps UI plus a __DEV__-only HUD overlay; behavior changes are minimal and largely test/automation-facing.

Overview
Improves agentic/E2E automation hooks by adding stable testIDs across shared UI (Keypad, Tabs) and many Perps surfaces (order rows, TP/SL inputs, limit price sheet, adjust margin actions, transactions tabs, and various touchable rows/buttons), including fixing a mislabeled TAKE_PROFIT_BUTTON selector.

Adds a dev-only AgentStepHud overlay to App (rendered only in __DEV__) to display the currently executing agent step, and updates Perps tests/snapshots to match the new identifiers. Also updates CODEOWNERS for scripts/perps/agentic/teams/perps/ and ignores local .task/ working directories.

^{Written by Cursor Bugbot for commit a568618. This will update automatically on new commits. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokePerps, SmokeWalletPlatform, SmokeRamps, SmokeTrade, SmokeConfirmations, SmokePredictions
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 85%

click to see 🤖 AI reasoning details

E2E Test Selection:

The PR introduces the agentic testing framework infrastructure with the following key changes:

1. AgenticService + AgentStepHud (DEV-only): New showStep, hideStep, findFiberByTestId methods added to the __AGENTIC__ bridge, plus a new AgentStepHud overlay component. Both are strictly guarded by __DEV__ checks - no production impact. Added to App.tsx root with {__DEV__ && <AgentStepHud />}.

2. Perps testID additions (primary change): Extensive testID additions across Perps views and components:

   • PerpsOrderView: LEVERAGE_ROW, LIMIT_PRICE_ROW, KEYPAD_25_PCT, KEYPAD_50_PCT, KEYPAD_MAX, KEYPAD_DONE
   • PerpsTPSLView: TAKE_PROFIT_PRICE_INPUT, STOP_LOSS_PRICE_INPUT
   • PerpsAdjustMarginView: CONFIRM_BUTTON, DONE_BUTTON
   • PerpsMarketHeader: FAVORITE_BUTTON (also fixed MORE_BUTTON assignment)
   • PerpsLimitPriceBottomSheet: PRICE_DISPLAY, CONFIRM_BUTTON
   • PerpsOrderTypeBottomSheet: MARKET_OPTION, LIMIT_OPTION
   • PerpsAdjustMarginActionSheet: ADD_MARGIN_OPTION, REDUCE_MARGIN_OPTION
   • PerpsTransactionsView: TAB_TRADES, TAB_ORDERS, TAB_FUNDING, TAB_DEPOSITS
   • PerpsOrderDetailsView: CANCEL_BUTTON
   • PerpsMarketDetailsView: Uses FAVORITE_BUTTON (was incorrectly using MORE_BUTTON)
   • PerpsMarketTabs: POSITION_TAB, ORDERS_TAB, STATISTICS_TAB
   • BUG FIX: TAKE_PROFIT_BUTTON was incorrectly set to 'perps-order-view-stop-loss-button', now corrected to 'perps-order-view-take-profit-button'

3. Keypad testID additions: Added testIDs to all keypad buttons (1-9, 0, dot). The Keypad component is shared across Ramp, Earn, Bridge, Perps, Confirmations, and Predictions flows.

4. TabsBar/TabsList: Added optional testID prop to TabItem interface - backward compatible, used by PerpsMarketTabs.

5. Scripts/docs: New agentic scripts and documentation - no app code impact.

Tag selection rationale:

• SmokePerps: Primary target - extensive Perps component changes including testID fixes that could affect existing E2E tests referencing old testIDs. The TAKE_PROFIT_BUTTON fix is a breaking change for any test using the old incorrect testID.
• SmokeWalletPlatform: Perps is a section inside Trending tab; TabsBar changes affect shared tab infrastructure.
• SmokeTrade: Perps is accessed via TradeWalletActions; Keypad used in Bridge/Swap flows.
• SmokeConfirmations: Required when selecting SmokeTrade; Keypad used in deposit-keyboard and edit-amount-keyboard in confirmations.
• SmokeRamps: Keypad is used in Ramp BuildQuote views (both Aggregator and Deposit).
• SmokePredictions: Keypad used in PredictKeypad; Predictions is in Trending tab (SmokeWalletPlatform dependency).

Performance Test Selection:
The changes are primarily additive testID additions to existing components and a DEV-only overlay (AgentStepHud). No changes to rendering logic, data fetching, state management, or component structure that would impact performance. The testID props are lightweight string attributes with negligible performance impact. The AgentStepHud is strictly DEV-only and never renders in production builds. No performance tests are warranted.

View GitHub Actions results

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.1% Coverage on New Code
1.1% Duplication on New Code

See analysis details on SonarQube Cloud

[georgewrmarshall]

LGTM! We should definitely have testID props for all of our components.

[github-actions]

✅ E2E Fixture Validation — Schema is up to date
17 value mismatches detected (expected — fixture represents an existing user).
View details