Scenario Guide
The bug only happens when three endpoints are in a particular state at once, and writing that down as reproduction steps asks the next person to rebuild it by hand. A scenario is that combination, saved and shareable as one code.
Key Features
- Save Scenarios: Save current handler variants, delays, and other settings as a scenario.
- One-Click Apply: Instantly apply all handler configurations included in a saved scenario.
- Status Syncing: View the
Activestatus in the list when a scenario is enabled. - Share & Export: Copy scenario JSON data to share with teammates, or export/import them as files.
Scenario Status
- Active Status: When a scenario is applied, an
Activebadge appears next to its name. This status is maintained as long as at least one handler in the scenario is active. - Inactive Status: A scenario becomes inactive if all its handlers are deactivated or if a different scenario is applied.
How to Use
Open the Mocking GUI Panel.
Configure the state (Response Variant, Delay, etc.) of the handlers you want to batch process, then click the + (Add) icon on the handler to register it to the scenario draft list.
Go to the Scenarios tab.
Enter a scenario name and click the + (Add) button to save.
Draft Bar:
- Selecting a variant from the handler list brings up the Draft Bar at the bottom.
- Expanded View: Click the arrow on the left of the Draft Bar to preview the list of APIs included in the current draft.
- Clear Draft: Click the
Clear Allbutton to remove all currently selected handlers from the draft.
Save Scenario: Enter a name for the scenario and click Save to add it to the Scenario tab.
Apply & Deactivate: Click 'Apply' on a scenario card to enable it, or 'Deactivate' to disable it.
Exporting & Importing Scenarios
- Export JSON File: Click the 'Export' button at the top of the Scenario tab to download all saved scenarios as a
.jsonfile. - Import File: Upload a JSON file in the 'Import' section to register multiple scenarios at once.
- Direct JSON Input (Share): Click the share button on an individual scenario card to copy its JSON data. Paste this data into the Textarea in the 'Import' section to register it instantly.
Programmatic Scenarios & Test Injection (experimental)
Exported from
@kakaocloud/mocking-gui/experimental. See Entry Points for the stability policy.
Scenarios can be declared in code with full type inference and injected into a browser before the app boots, so E2E runs, screenshot jobs or Storybook stories start from a known mock state.
1. Declare a registry
// src/mocks/registry.ts
import { defineRegistry } from '@kakaocloud/mocking-gui/experimental';
export const registry = defineRegistry([
{
name: 'Users',
url: '/api/users',
method: 'get',
responseVariants: [
{ name: 'Success', status: 200, body: { items: [{ id: 1, name: 'kim' }] } },
{ name: 'Empty', status: 200, body: { items: [] } },
{ name: 'Error', status: 500, body: { message: 'internal error' } },
],
},
]);
// The same declaration drives the GUI at runtime:
export const mockConfig = { mocks: registry.handlers };Handler and variant names are literal types, so registry.pick('Usres', …) or registry.pick('Users', 'Nope') fail to compile.
2. Compose scenarios
import { defineScenario, extendScenario } from '@kakaocloud/mocking-gui/experimental';
import { registry } from '../src/mocks/registry';
export const happy = defineScenario('happy path', [registry.pick('Users', 'Success')]);
export const slow = defineScenario('slow list', [
registry.pick('Users', 'Success', { delay: 3000 }),
]);
export const failing = extendScenario(happy, 'list fails', [registry.pick('Users', 'Error')]);Picking the same handler twice inside one defineScenario is a compile error; use extendScenario to override deliberately.
3. Inject before boot
Playwright (verified target; any driver with addInitScript and addCookies or setCookies):
import { applyScenario } from '@kakaocloud/mocking-gui/experimental';
test('renders users', async ({ context, page }) => {
await applyScenario(context, happy, { origin: 'http://localhost:5173', ssr: true });
await page.goto('http://localhost:5173');
});ssr: true also writes the sync cookie so a server-rendered first paint sees the same scenario. WebdriverIO v9 drivers are accepted (addInitScript + setCookies), and localStorage seeding works before navigation, but its setCookies scopes cookies to the current page, so call applyScenario with ssr: true only after navigating to origin.
Cypress, Storybook, or anything running inside the page: use serializeScenario and write the pair to localStorage yourself.
import { serializeScenario } from '@kakaocloud/mocking-gui/experimental';
const { key, value } = serializeScenario(happy);
cy.visit('/', { onBeforeLoad: win => win.localStorage.setItem(key, value) });