@buoy-gg/scenarios

Define repeatable test setups using actions from installed Buoy tools. A scenario can configure response overrides, edit storage, select a test user, or navigate. Review its steps and expected outcome before running it.

Install

npm install @buoy-gg/core @buoy-gg/scenarios @buoy-gg/network @buoy-gg/route-events

Account setup

Start in a development build. You need a Free or Pro Buoy account. Sign in from your app's folder:

npx --package=@buoy-gg/core buoy login

Your browser opens buoy.gg. Click Allow. The CLI then writes a dev token. It works in dev builds for 30 days.

On Expo, the token goes in .env.development.local. Buoy reads it by itself in dev builds. You can also pass it in yourself:

import { Buoy } from "@buoy-gg/core";

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

On React Native CLI, the token goes in .env.local as BUOY_KEY. React Native does not load that file by itself. Pass the token in with your app's own env setup. Keep the menu inside the providers used by your app. Restart the development server after installing packages. See the Quick Start for the complete root component.

Define a scenario

This integration fragment assumes your app has a matching menu endpoint and /cart route. Adapt the URL pattern, response body, route, and build label to your app, then render this menu inside your existing providers:

import { FloatingDevTools } from "@buoy-gg/core";
import { defineScenario, createScenariosTool } from "@buoy-gg/scenarios";

const outOfStock = defineScenario({
  id: "oos-item",
  name: "Out-of-stock item at store {{storeId}}",
  expectedOutcome: "Cart shows the item sold out; checkout is blocked.",
  authoredAgainst: "5.4.0",
  vars: [
    { key: "storeId", type: "enum", options: ["100", "220"], default: "100" },
  ],
  steps: [
    { tool: "network", action: "upsertOverrideRule",
      params: { rule: {
        urlPattern: "*/menu/{{storeId}}*", methods: ["GET"],
        kind: "respond", status: 200, body: '{"items":[{"id":"dbl","inStock":false}]}',
      } } },
    { tool: "route-events", action: "navigate", params: { path: "/cart" } },
  ],
});

<FloatingDevTools
  apps={[createScenariosTool({ scenarios: [outOfStock], currentBuild: "5.4.0" })]}
/>

Code-defined scenarios are read-only on the device. Install and configure every tool referenced by a step; declaring a step does not implement that tool's app integration.

Check activation and deactivation

Preview the scenario, supply its variables, and resolve any preflight errors. Run it in a development build, trigger the affected app request, and check the expected screen. Deactivate it and confirm that normal behavior returns.

Preflight validates known requirements before execution. Runtime failures can still leave partial effects; it is not a transaction across your app and backend. Review the result of each step.

The runner removes supported active overrides and impersonation effects during deactivation. Storage writes need explicit undo steps to restore prior values. Inspect reported irreversible effects and test cleanup as carefully as activation. Conflicting scenarios may require replacing the active setup; do not assume arbitrary scenarios can run together.

Remote drafts require acceptance on the device before they can run. In a React Native release build, the runner needs a paid plan and the Buoy menu on screen. See the Scenarios guide for variables, drafts, previews, and undo steps.

Desktop and MCP

React Native connections require @buoy-gg/external-sync. Follow the Desktop connection guide, sign in to Desktop separately, and confirm the selected device. MCP uses the sign-in from buoy login on your computer. Free has the basic MCP. Reading this tool from the MCP needs Pro.

Device data can travel over your LAN to the configured broker. Account validation makes network requests. See Telemetry for data-flow details.

Web support (unreleased)

Register this package’s /web namespace in FloatingDevTools modules to use its shared panels and actions in a browser app. The browser build is available in this checkout and has not been published yet. See the web setup guide for registration, dependencies, and browser boundaries.