stablyai/stably-sdk-rules

Stably SDK Rules

Quick Rules

1. Prefer raw Playwright for deterministic actions/assertions (faster + cheaper).
2. Prioritize reliability over cost when Playwright becomes brittle.
3. Use agent.act() for canvas, coordinate-based drag/click, or unstable multi-step flows.
4. Use expect(...).aiAssert() for dynamic visual assertions; keep prompts specific.
5. Use page.extract() / locator.extract() when you need visual-to-data extraction.
6. Use page.getLocatorsByAI() when semantic selectors are hard with standard locators.
7. Use Inbox for OTP/magic-link/verification email flows.
8. All prompts must be self-contained; never rely on implicit previous context.
9. Keep agent.act() tasks small; do loops/calculations/conditionals in code.
10. Use fullPage: true only if content outside viewport matters.
11. Always add .describe("...") to locators for trace readability.
12. For email isolation, use unique Inbox.build({ suffix }) per test and clean up.

Setup (Single Block)

npm install -D @playwright/test @stablyai/playwright-test @stablyai/email
export STABLY_API_KEY=YOUR_KEY
export STABLY_PROJECT_ID=YOUR_PROJECT_ID

import { test, expect } from "@stablyai/playwright-test";
import { Inbox } from "@stablyai/email";

Optional: set API key programmatically.

import { setApiKey } from "@stablyai/playwright-test";
setApiKey("YOUR_KEY");

Core Rules

• Locator rule: every locator interaction should use .describe("...").
• Assertion choice:
  • Use Playwright assertions first.
  • Use aiAssert for dynamic/visual-heavy checks.
• Interaction choice:
  • Use Playwright for deterministic steps.
  • Use agent.act for brittle or semantic tasks (especially canvas/coordinates).
• Prompt quality:
  • Include explicit target, intent, and constraints.
  • Pass cross-step data through variables, not vague references.

Minimal Usage Patterns

aiAssert

await expect(page).aiAssert("Shows revenue trend chart and spotlight card");
await expect(page.locator(".header").describe("Header")).aiAssert("Has nav, avatar, and bell icon");

Use fullPage: true only when assertion needs off-screen content.

extract

const orderId = await page.extract("Extract the order ID from the first row");

With schema:

import { z } from "zod";
const Schema = z.object({ revenue: z.string(), users: z.number() });
const metrics = await page.extract("Get revenue and active users", { schema: Schema });

getLocatorsByAI

Requires Playwright >= 1.54.1.

const { locator, count } = await page.getLocatorsByAI("the login button");
expect(count).toBe(1);
await locator.describe("Login button located by AI").click();

agent.act

await agent.act("Find the first pending order and mark it as shipped", { page });

Good pattern: compute values in code, then pass concrete values into the prompt.

Inbox (Email Isolation)

Install: npm install -D @stablyai/email. Requires STABLY_API_KEY and STABLY_PROJECT_ID env vars (or pass to Inbox.build()).

const inbox = await Inbox.build({ suffix: `test-${Date.now()}` });
// inbox.address → "[email protected]"

await page.getByLabel("Email").describe("Email input").fill(inbox.address);

const email = await inbox.waitForEmail({ subject: "verification", timeoutMs: 60_000 });
const { data: otp } = await inbox.extractFromEmail({
  id: email.id,
  prompt: "Extract the 6-digit OTP code",
});

await inbox.deleteAllEmails();

Inbox.build Options

| Option | Type | Description | |--------|------|-------------| | suffix | string | Suffix for test isolation (e.g., "test-123" → "[email protected]") | | apiKey | string | Defaults to STABLY_API_KEY env var | | projectId | string | Defaults to STABLY_PROJECT_ID env var |

Always use a unique suffix per test for parallel isolation. The inbox automatically filters out emails received before it was created.

waitForEmail

const email = await inbox.waitForEmail({
  from: "[email protected]",    // filter by sender
  subject: "verification",         // contains match by default
  subjectMatch: "exact",           // or "contains" (default)
  timeoutMs: 60_000,               // default: 120000 (2 min)
  pollIntervalMs: 5000,            // default: 3000 (3 sec)
});

Throws EmailTimeoutError if no match arrives within the timeout.

extractFromEmail

Returns { data, reason }. Throws EmailExtractionError on failure.

// String extraction
const { data: otp } = await inbox.extractFromEmail({
  id: email.id,
  prompt: "Extract the 6-digit OTP code",
});

// Structured extraction with Zod schema
import { z } from "zod";
const { data } = await inbox.extractFromEmail({
  id: email.id,
  prompt: "Extract the verification URL and expiration time",
  schema: z.object({ url: z.string().url(), expiresIn: z.string() }),
});

Inbox Properties

| Property | Type | Description | |----------|------|-------------| | address | string | Full email address (with suffix if provided) | | suffix | string | undefined | The suffix passed to Inbox.build() | | createdAt | Date | Inbox creation time; emails before this are auto-filtered |

listEmails

const { emails, nextCursor } = await inbox.listEmails(options?);

| Option | Type | Default | Description | |--------|------|---------|-------------| | from | string | — | Filter by sender address | | subject | string | — | Filter by subject | | subjectMatch | 'contains' | 'exact' | 'contains' | Subject matching mode | | limit | number | 20 | Max results (max: 100) | | cursor | string | — | Pagination cursor from previous nextCursor | | since | Date | — | Override the default creation-time filter | | includeOlder | boolean | false | Include emails received before inbox creation |

Other Methods

const email = await inbox.getEmail(id);                          // get by ID
await inbox.deleteEmail(email.id);                               // delete single
await inbox.deleteAllEmails();                                   // delete all (this inbox only)

Email Object Properties

| Property | Type | Description | |----------|------|-------------| | id | string | Unique identifier | | mailbox | string | Container (e.g., "INBOX") | | from | { address: string, name?: string } | Sender | | to | { address: string, name?: string }[] | Recipients | | subject | string | Subject line | | receivedAt | Date | Arrival timestamp | | text | string? | Plain text body | | html | string[]? | HTML body parts |

Playwright Fixture Pattern

import { test as base } from "@stablyai/playwright-test";
import { Inbox } from "@stablyai/email";

const test = base.extend<{ inbox: Inbox }>({
  inbox: async ({}, use, testInfo) => {
    const inbox = await Inbox.build({ suffix: `test-${testInfo.testId}` });
    await use(inbox);
    await inbox.deleteAllEmails();
  },
});

test("signup flow", async ({ page, inbox }) => {
  await page.fill("#email", inbox.address);
  await page.click("#signup");
  const email = await inbox.waitForEmail({ subject: "Welcome" });
  // ...
});

Finding Your Organization's Email Address

Your email address is visible in the Stably dashboard:

• Settings > Email Inbox: Displays the full address with a copy button
• In code: inbox.address after calling Inbox.build() returns your full address

The pattern is {org-name}@mail.stably.ai. If the user needs to allowlist, they should add mail.stably.ai to their email provider's allowlist.

Direct users to the dashboard Settings > Email Inbox to find their specific address.

Auth Flows (Google)

Use the helper instead of custom popup scripting:

import { authWithGoogle } from "@stablyai/playwright-test/auth";

await authWithGoogle({
  context,
  email: process.env.GOOGLE_AUTH_EMAIL!,
  password: process.env.GOOGLE_AUTH_PASSWORD!,
  otpSecret: process.env.GOOGLE_AUTH_OTP_SECRET!,
});

Required env vars:

• GOOGLE_AUTH_EMAIL
• GOOGLE_AUTH_PASSWORD
• GOOGLE_AUTH_OTP_SECRET

Use a dedicated test Google account only.

Troubleshooting (Short)

• aiAssert is slow/flaky: scope to a locator, tighten prompt, avoid unnecessary fullPage: true.
• agent.act fails: split into smaller tasks, pass explicit constraints, raise maxCycles only when needed.
• Email timeout: verify subject/from filter and use unique inbox suffixes.

Full References

• Stably docs: https://docs.stably.ai
• SDK setup skill: skills/stably-sdk-setup/SKILL.md
• Package docs: https://www.npmjs.com/package/@stablyai/playwright-test
• Email package docs: https://www.npmjs.com/package/@stablyai/email
• Local overview: skills/stably-sdk-rules/README.md