@iblai/mcp 1.0.0 → 1.1.3

package/dist/tools/playwright-helper-info.js

@@ -0,0 +1,849 @@
+export const playwrightHelperInfoTool = {
+    name: 'get_playwright_helper_info',
+    description: 'Get detailed documentation for a specific Playwright test helper from @iblai/iblai-js/playwright',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            helperName: {
+                type: 'string',
+                description: 'Name of the Playwright helper (e.g., createPlaywrightConfig, reliableClick, safeWaitForURL, createAuthSetup)',
+            },
+        },
+        required: ['helperName'],
+    },
+};
+const helpers = {
+    // ============================================================================
+    // NAVIGATION
+    // ============================================================================
+    safeWaitForURL: `# safeWaitForURL
+
+\`\`\`typescript
+import { safeWaitForURL } from '@iblai/iblai-js/playwright';
+
+async function safeWaitForURL(
+  page: Page,
+  urlMatcher: string | RegExp | ((url: URL) => boolean),
+  options?: SafeWaitForURLOptions
+): Promise<void>
+
+interface SafeWaitForURLOptions {
+  timeout?: number;      // Default: 30000
+  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+  maxRetries?: number;   // Default: 3
+}
+\`\`\`
+
+**Use instead of \`page.waitForURL\`**. Handles Firefox \`NS_BINDING_ABORTED\` errors and Safari navigation policy issues by catching and retrying.
+
+## Example
+
+\`\`\`typescript
+// Wait for navigation to a specific path
+await safeWaitForURL(page, (url) => url.pathname.includes('/dashboard'));
+
+// With string pattern
+await safeWaitForURL(page, '**/dashboard');
+
+// With options
+await safeWaitForURL(page, /\\/settings/, { timeout: 10000, maxRetries: 5 });
+\`\`\`
+
+**Related:** \`waitForPageLoad\`, \`waitForPageReady\``,
+    waitForPageLoad: `# waitForPageLoad
+
+\`\`\`typescript
+import { waitForPageLoad } from '@iblai/iblai-js/playwright';
+
+async function waitForPageLoad(page: Page): Promise<void>
+\`\`\`
+
+Waits for complete page load: \`load\` event, \`domcontentloaded\`, \`networkidle\`, and dismisses any dialogs that appear. Comprehensive page load wait.
+
+## Example
+
+\`\`\`typescript
+await page.goto('https://app.example.com');
+await waitForPageLoad(page);
+\`\`\`
+
+**Related:** \`waitForPageReady\`, \`safeWaitForURL\``,
+    isFirefox: `# isFirefox
+
+\`\`\`typescript
+import { isFirefox } from '@iblai/iblai-js/playwright';
+
+function isFirefox(page: Page): boolean
+\`\`\`
+
+Check if current browser is Firefox. Useful for browser-specific test logic.
+
+## Example
+
+\`\`\`typescript
+if (isFirefox(page)) {
+  // Firefox-specific handling
+  await page.waitForTimeout(500);
+}
+\`\`\``,
+    // ============================================================================
+    // PAGE INTERACTION HELPERS
+    // ============================================================================
+    waitForPageReady: `# waitForPageReady
+
+\`\`\`typescript
+import { waitForPageReady } from '@iblai/iblai-js/playwright';
+
+async function waitForPageReady(page: Page, timeout?: number): Promise<void>
+\`\`\`
+
+Waits for \`document.readyState\` to be \`'complete'\`. Use in \`beforeEach\` after navigation.
+
+## Example
+
+\`\`\`typescript
+test.beforeEach(async ({ page }) => {
+  await page.goto(APP_HOST);
+  await waitForPageReady(page);
+});
+\`\`\`
+
+**Related:** \`waitForPageLoad\`, \`safeWaitForURL\``,
+    reliableClick: `# reliableClick
+
+\`\`\`typescript
+import { reliableClick } from '@iblai/iblai-js/playwright';
+
+async function reliableClick(
+  page: Page,
+  locator: Locator,
+  timeout?: number,    // Default: 5000
+  maxRetries?: number  // Default: 3
+): Promise<void>
+\`\`\`
+
+Click with automatic retry on detached elements, hidden elements, and race conditions. Waits for element to be stable before clicking.
+
+## Example
+
+\`\`\`typescript
+// Click a button
+await reliableClick(page, page.getByRole('button', { name: 'Save' }));
+
+// With custom timeout and retries
+await reliableClick(page, page.locator('[data-testid="submit"]'), 10000, 5);
+\`\`\`
+
+**Related:** \`reliableFill\`, \`waitForElementStable\``,
+    reliableFill: `# reliableFill
+
+\`\`\`typescript
+import { reliableFill } from '@iblai/iblai-js/playwright';
+
+async function reliableFill(
+  page: Page,
+  locator: Locator,
+  value: string,
+  timeout?: number,    // Default: 5000
+  maxRetries?: number  // Default: 3
+): Promise<void>
+\`\`\`
+
+Fill input with automatic retry. Clears existing value, fills new value, and verifies the value was set correctly.
+
+## Example
+
+\`\`\`typescript
+await reliableFill(page, page.getByLabel('Email'), 'user@example.com');
+await reliableFill(page, page.getByPlaceholder('Search'), 'query', 10000);
+\`\`\`
+
+**Related:** \`reliableClick\`, \`waitForElementStable\``,
+    waitForElementStable: `# waitForElementStable
+
+\`\`\`typescript
+import { waitForElementStable } from '@iblai/iblai-js/playwright';
+
+async function waitForElementStable(
+  page: Page,
+  locator: Locator,
+  timeout?: number  // Default: 5000
+): Promise<void>
+\`\`\`
+
+Waits for an element to be attached, visible, and not animating.
+
+## Example
+
+\`\`\`typescript
+const dialog = page.getByRole('dialog');
+await waitForElementStable(page, dialog);
+await dialog.getByRole('button', { name: 'Confirm' }).click();
+\`\`\`
+
+**Related:** \`waitForDialogReady\`, \`reliableClick\``,
+    waitForDialogReady: `# waitForDialogReady
+
+\`\`\`typescript
+import { waitForDialogReady } from '@iblai/iblai-js/playwright';
+
+async function waitForDialogReady(
+  page: Page,
+  dialogLocator: Locator,
+  timeout?: number  // Default: 5000
+): Promise<void>
+\`\`\`
+
+Wait for a dialog/modal to be visible and fully loaded (not just appearing but content rendered).
+
+## Example
+
+\`\`\`typescript
+await reliableClick(page, page.getByRole('button', { name: 'Edit' }));
+const dialog = page.getByRole('dialog');
+await waitForDialogReady(page, dialog);
+\`\`\`
+
+**Related:** \`closeWithEsc\`, \`waitForElementStable\``,
+    selectDateFromCalendar: `# selectDateFromCalendar
+
+\`\`\`typescript
+import { selectDateFromCalendar } from '@iblai/iblai-js/playwright';
+
+async function selectDateFromCalendar(
+  page: Page,
+  dialogLocator: Locator,
+  targetDate: Date,
+  timeout?: number  // Default: 5000
+): Promise<void>
+\`\`\`
+
+Select a date from a calendar date picker component.
+
+## Example
+
+\`\`\`typescript
+const datePicker = page.getByRole('dialog');
+await selectDateFromCalendar(page, datePicker, new Date('2024-03-15'));
+\`\`\``,
+    closeWithEsc: `# closeWithEsc
+
+\`\`\`typescript
+import { closeWithEsc } from '@iblai/iblai-js/playwright';
+
+async function closeWithEsc(page: Page): Promise<void>
+\`\`\`
+
+Press Escape key to close modals/dialogs/dropdowns.
+
+## Example
+
+\`\`\`typescript
+// Open a dialog, interact, then close
+await reliableClick(page, page.getByRole('button', { name: 'Settings' }));
+// ... interact with dialog ...
+await closeWithEsc(page);
+\`\`\`
+
+**Related:** \`waitForDialogReady\``,
+    checkAdminStatus: `# checkAdminStatus
+
+\`\`\`typescript
+import { checkAdminStatus } from '@iblai/iblai-js/playwright';
+
+async function checkAdminStatus(page: Page): Promise<boolean>
+\`\`\`
+
+Check if the current user has admin status by reading from localStorage.
+
+## Example
+
+\`\`\`typescript
+const isAdmin = await checkAdminStatus(page);
+if (isAdmin) {
+  // Test admin-only features
+  await expect(page.getByRole('link', { name: 'Admin' })).toBeVisible();
+}
+\`\`\``,
+    // ============================================================================
+    // UTILITY FUNCTIONS
+    // ============================================================================
+    retry: `# retry
+
+\`\`\`typescript
+import { retry } from '@iblai/iblai-js/playwright';
+
+async function retry(
+  action: () => Promise<void>,
+  errorMessage: string,
+  retryCount?: number  // Default: 3
+): Promise<void>
+\`\`\`
+
+Generic retry wrapper. Executes the action and retries on failure.
+
+## Example
+
+\`\`\`typescript
+await retry(
+  async () => {
+    await page.getByRole('button', { name: 'Load More' }).click();
+    await expect(page.getByTestId('items')).toHaveCount(20);
+  },
+  'Failed to load more items',
+  5
+);
+\`\`\``,
+    isJSON: `# isJSON
+
+\`\`\`typescript
+import { isJSON } from '@iblai/iblai-js/playwright';
+
+function isJSON(value: string): boolean
+\`\`\`
+
+Check if a string is valid JSON.
+
+## Example
+
+\`\`\`typescript
+const text = await page.locator('#response').textContent();
+if (isJSON(text)) {
+  const data = JSON.parse(text);
+}
+\`\`\``,
+    logger: `# logger
+
+\`\`\`typescript
+import { logger } from '@iblai/iblai-js/playwright';
+\`\`\`
+
+Winston logger instance. Shows \`info\` level output locally (colorized), silent in CI.
+
+## Example
+
+\`\`\`typescript
+logger.info('Navigating to dashboard');
+logger.warn('Retrying failed click');
+logger.error('Element not found after retries');
+\`\`\`
+
+Methods: \`info()\`, \`warn()\`, \`error()\`, \`debug()\``,
+    // ============================================================================
+    // ACCESSIBILITY
+    // ============================================================================
+    expectNoAccessibilityViolations: `# expectNoAccessibilityViolations
+
+\`\`\`typescript
+import { expectNoAccessibilityViolations } from '@iblai/iblai-js/playwright';
+
+async function expectNoAccessibilityViolations(page: Page): Promise<void>
+\`\`\`
+
+Run axe-core accessibility audit on the full page. Asserts no WCAG 2.1 AA violations.
+
+## Example
+
+\`\`\`typescript
+test('should have no accessibility violations', async ({ page }) => {
+  await page.goto(APP_HOST);
+  await waitForPageReady(page);
+  await expectNoAccessibilityViolations(page);
+});
+\`\`\`
+
+**Related:** \`expectNoAccessibilityViolationsOnDialogs\``,
+    expectNoAccessibilityViolationsOnDialogs: `# expectNoAccessibilityViolationsOnDialogs
+
+\`\`\`typescript
+import { expectNoAccessibilityViolationsOnDialogs } from '@iblai/iblai-js/playwright';
+
+async function expectNoAccessibilityViolationsOnDialogs(
+  page: Page,
+  rules?: string[],
+  exclude?: string[]
+): Promise<void>
+\`\`\`
+
+Run axe-core on dialog elements specifically. Useful when testing modals/dialogs that may have different accessibility contexts.
+
+## Example
+
+\`\`\`typescript
+await reliableClick(page, page.getByRole('button', { name: 'Open Settings' }));
+await waitForDialogReady(page, page.getByRole('dialog'));
+await expectNoAccessibilityViolationsOnDialogs(page);
+\`\`\`
+
+**Related:** \`expectNoAccessibilityViolations\``,
+    // ============================================================================
+    // AUTH HELPERS
+    // ============================================================================
+    createAuthSetup: `# createAuthSetup
+
+\`\`\`typescript
+import { test as setup, createAuthSetup } from '@iblai/iblai-js/playwright';
+
+function createAuthSetup(config: AuthSetupConfig): SetupFn
+
+interface AuthSetupConfig {
+  hostUrl: string;
+  authHost: string;
+  appName: string;
+  postLoginUrlMatcher: (url: URL) => boolean;
+  authFlow?: AuthFlowType;  // Default: 'username_password'
+  authIdp?: string;
+}
+\`\`\`
+
+Factory function that creates a Playwright auth setup test. Authenticates once per browser and saves storage state to \`playwright/.auth/user-{browser}.json\`.
+
+## Example
+
+\`\`\`typescript
+// e2e/auth.setup.ts
+import { test as setup, createAuthSetup } from '@iblai/iblai-js/playwright';
+
+setup(
+  'authenticate',
+  createAuthSetup({
+    hostUrl: process.env.MENTOR_NEXTJS_HOST || '',
+    authHost: process.env.AUTH_HOST || '',
+    appName: 'mentor',
+    postLoginUrlMatcher: (url) =>
+      url.href.includes('/platform/') || url.href.includes('/home'),
+  }),
+);
+\`\`\`
+
+**Related:** \`AuthFlowBuilder\`, \`loginWithEmailAndPassword\``,
+    AuthFlowBuilder: `# AuthFlowBuilder
+
+\`\`\`typescript
+import { AuthFlowBuilder } from '@iblai/iblai-js/playwright';
+
+class AuthFlowBuilder {
+  constructor(flow: AuthFlowType, idp: string, authHost: string)
+
+  async run(
+    page: Page,
+    step: StepFn,
+    username: string,
+    password: string,
+    hostUrl: string,
+    authUrl: string,
+    postLoginUrlMatcher?: (url: URL) => boolean
+  ): Promise<void>
+}
+
+type AuthFlowType = 'username_password' | 'magic_link' | 'sso' | 'direct_sso';
+\`\`\`
+
+Handles different authentication flows. Used internally by \`createAuthSetup\` but can be used directly for custom auth scenarios.
+
+## Supported Flows
+
+- **\`username_password\`**: Email/password form login
+- **\`magic_link\`**: Email magic link via Mailsac
+- **\`sso\`**: SSO via identity provider (navigates to IDP)
+- **\`direct_sso\`**: Direct SSO redirect
+
+**Related:** \`createAuthSetup\`, \`loginWithEmailAndPassword\``,
+    loginWithEmailAndPassword: `# loginWithEmailAndPassword
+
+\`\`\`typescript
+import { loginWithEmailAndPassword } from '@iblai/iblai-js/playwright';
+
+async function loginWithEmailAndPassword(
+  page: Page,
+  username: string,
+  password: string,
+  hostUrl: string,
+  postLoginUrlMatcher?: (url: URL) => boolean
+): Promise<void>
+\`\`\`
+
+Login using email and password. Navigates to auth page, fills credentials, submits, and waits for redirect.
+
+## Example
+
+\`\`\`typescript
+await loginWithEmailAndPassword(
+  page,
+  'test@example.com',
+  'password123',
+  'https://mentor.example.com',
+  (url) => url.pathname.includes('/home')
+);
+\`\`\`
+
+**Related:** \`createAuthSetup\`, \`signUpWithEmailAndPassword\``,
+    signUpWithEmailAndPassword: `# signUpWithEmailAndPassword
+
+\`\`\`typescript
+import { signUpWithEmailAndPassword } from '@iblai/iblai-js/playwright';
+
+async function signUpWithEmailAndPassword(
+  page: Page,
+  authHost: string,
+  postSignUpUrl: string,
+  credentials?: SignUpCredentials,
+  alreadyInSignupPage?: boolean
+): Promise<void>
+
+interface SignUpCredentials {
+  email: string;
+  password: string;
+}
+\`\`\`
+
+Sign up a new user with email/password. Navigates to signup page, fills form, submits, and waits for redirect.
+
+## Example
+
+\`\`\`typescript
+await signUpWithEmailAndPassword(
+  page,
+  'https://auth.example.com',
+  'https://mentor.example.com/home',
+  { email: 'newuser@example.com', password: 'SecurePass123!' }
+);
+\`\`\`
+
+**Related:** \`loginWithEmailAndPassword\``,
+    loginWithMicrosoftIdp: `# loginWithMicrosoftIdp
+
+\`\`\`typescript
+import { loginWithMicrosoftIdp } from '@iblai/iblai-js/playwright';
+
+async function loginWithMicrosoftIdp(
+  page: Page,
+  username: string,
+  password: string
+): Promise<void>
+\`\`\`
+
+Login through Microsoft identity provider (Azure AD / Entra ID).
+
+**Related:** \`AuthFlowBuilder\`, \`createAuthSetup\``,
+    canChatWithEmbedMentor: `# canChatWithEmbedMentor
+
+\`\`\`typescript
+import { canChatWithEmbedMentor } from '@iblai/iblai-js/playwright';
+
+async function canChatWithEmbedMentor(
+  page: Page,
+  openChatButton: Locator
+): Promise<void>
+\`\`\`
+
+Test helper to verify chat functionality with an embedded mentor widget.
+
+**Related:** \`getMentorIdFromUrl\``,
+    getMentorIdFromUrl: `# getMentorIdFromUrl
+
+\`\`\`typescript
+import { getMentorIdFromUrl } from '@iblai/iblai-js/playwright';
+
+function getMentorIdFromUrl(url: string): string
+\`\`\`
+
+Extract mentor ID from a URL path.`,
+    // ============================================================================
+    // CONFIG GENERATION
+    // ============================================================================
+    createPlaywrightConfig: `# createPlaywrightConfig
+
+\`\`\`typescript
+import { createPlaywrightConfig } from '@iblai/iblai-js/playwright';
+
+function createPlaywrightConfig(
+  options: CreatePlaywrightConfigOptions
+): PlaywrightTestConfig
+
+interface CreatePlaywrightConfigOptions {
+  testDir?: string;         // Default: '.'
+  devices?: string[];       // Default: ['Desktop Chrome', 'Desktop Firefox', 'Desktop Safari', 'Desktop Edge']
+  platforms: PlatformConfig[];
+  customReporterPath?: string;  // Default: './custom-reporter.ts'
+  extraProjects?: Project[];
+}
+
+interface PlatformConfig {
+  name: string;
+  devices?: string[];
+  dependencies?: string[];
+  otherTestMatch?: string[];
+  testIgnore?: string[];
+}
+\`\`\`
+
+Generates a complete Playwright config with per-browser auth setup projects. Produces:
+- Auth setup projects per browser (setup-chrome, setup-firefox, etc.)
+- Test projects per platform/browser combination
+- CI mode: retries=3, workers=1, headless, trace=retain-on-failure
+- Local mode: retries=0, headed (via HEADED env var), trace=on-first-retry
+
+## Example
+
+\`\`\`typescript
+// e2e/playwright.config.ts
+import { createPlaywrightConfig } from '@iblai/iblai-js/playwright';
+import dotenv from 'dotenv';
+import path from 'path';
+
+dotenv.config({ path: path.resolve(__dirname, '.env.development') });
+
+export default createPlaywrightConfig({
+  platforms: [
+    {
+      name: 'mentornextjs',
+      dependencies: ['setup'],
+      otherTestMatch: ['**mentornextjs/*/*.spec.ts'],
+    },
+  ],
+});
+\`\`\`
+
+**Related:** \`generateProjectConfig\`, \`generateBrowserSetupProjects\``,
+    generateProjectConfig: `# generateProjectConfig
+
+\`\`\`typescript
+import { generateProjectConfig } from '@iblai/iblai-js/playwright';
+\`\`\`
+
+Generate per-browser project configuration objects. Used internally by \`createPlaywrightConfig\`.
+
+**Related:** \`createPlaywrightConfig\``,
+    generateBrowserSetupProjects: `# generateBrowserSetupProjects
+
+\`\`\`typescript
+import { generateBrowserSetupProjects } from '@iblai/iblai-js/playwright';
+\`\`\`
+
+Generate auth setup projects for each browser. Used internally by \`createPlaywrightConfig\`.
+
+**Related:** \`createPlaywrightConfig\``,
+    getBrowserKey: `# getBrowserKey
+
+\`\`\`typescript
+import { getBrowserKey } from '@iblai/iblai-js/playwright';
+
+function getBrowserKey(deviceName: string): string
+\`\`\`
+
+Convert a Playwright device name to a browser key. Example: \`'Desktop Chrome'\` → \`'chrome'\`.
+
+**Related:** \`createPlaywrightConfig\``,
+    // ============================================================================
+    // ENVIRONMENT CONFIG
+    // ============================================================================
+    createEnvConfig: `# createEnvConfig
+
+\`\`\`typescript
+import { createEnvConfig } from '@iblai/iblai-js/playwright';
+
+function createEnvConfig(overrides?: Partial<EnvConfig>): EnvConfig
+
+interface EnvConfig {
+  skillHost: string;
+  authHost: string;
+  analyticsHost: string;
+  mentorHost: string;
+  mentorNextjsHost: string;
+  authNextjsHost: string;
+  playwrightUsername: string;
+  playwrightPassword: string;
+  inviteUsername: string;
+  inviteUserPassword: string;
+  authFlow: AuthFlowType;
+  authIdp: string;
+  enableStripeTest: boolean;
+  iblMentorDisabledTabs: string;
+  embedUrl: string;
+  wcagRange: string;
+}
+
+type AuthFlowType = 'username_password' | 'magic_link' | 'sso' | 'direct_sso';
+\`\`\`
+
+Typed environment variable reader. Reads from \`process.env\` and provides typed defaults.
+
+## Example
+
+\`\`\`typescript
+const env = createEnvConfig();
+await page.goto(env.mentorNextjsHost);
+\`\`\`
+
+**Related:** \`createAuthSetup\``,
+    // ============================================================================
+    // MAIL CLIENT
+    // ============================================================================
+    MailsacClient: `# MailsacClient
+
+\`\`\`typescript
+import { MailsacClient } from '@iblai/iblai-js/playwright';
+
+class MailsacClient {
+  constructor(apiKey: string)
+
+  async getEmails(inbox: string): Promise<Email[]>
+  async getEmailById(email: string, messageId: string): Promise<EmailDetail>
+  async deleteEmail(emailId: string): Promise<void>
+}
+\`\`\`
+
+Email testing client for Mailsac. Used with magic link auth flow testing.
+
+## Example
+
+\`\`\`typescript
+const mail = new MailsacClient(process.env.MAILSAC_API_KEY);
+const emails = await mail.getEmails('test@mailsac.com');
+\`\`\`
+
+**Related:** \`AuthFlowBuilder\` (magic_link flow)`,
+    // ============================================================================
+    // CUSTOM REPORTER
+    // ============================================================================
+    CustomReporter: `# CustomReporter
+
+\`\`\`typescript
+import { CustomReporter } from '@iblai/iblai-js/playwright';
+// or re-export:
+export { CustomReporter as default } from '@iblai/iblai-js/playwright';
+\`\`\`
+
+Playwright custom reporter with \`onBegin\`, \`onTestBegin\`, \`onTestEnd\`, \`onEnd\` hooks. Provides formatted console output for test results.
+
+## Usage
+
+Create \`e2e/custom-reporter.ts\`:
+\`\`\`typescript
+export { CustomReporter as default } from '@iblai/iblai-js/playwright';
+\`\`\`
+
+This is automatically referenced by \`createPlaywrightConfig\`.
+
+**Related:** \`createPlaywrightConfig\``,
+    // ============================================================================
+    // REPORT DOWNLOAD
+    // ============================================================================
+    buildReportUrl: `# buildReportUrl
+
+\`\`\`typescript
+import { buildReportUrl } from '@iblai/iblai-js/playwright';
+
+function buildReportUrl(baseUrl: string, platformKey: string, reportName: string): string
+\`\`\`
+
+Build a report download URL from base URL, platform key, and report name.
+
+**Related:** \`navigateToReportDownload\`, \`waitForReportDownload\``,
+    navigateToReportDownload: `# navigateToReportDownload
+
+\`\`\`typescript
+import { navigateToReportDownload } from '@iblai/iblai-js/playwright';
+
+async function navigateToReportDownload(
+  page: Page,
+  options: ReportDownloadOptions
+): Promise<void>
+
+interface ReportDownloadOptions {
+  baseUrl: string;
+  platformKey: string;
+  reportName: string;
+  timeout?: number;
+}
+\`\`\`
+
+Navigate to a report download page and wait for it to be ready.
+
+**Related:** \`buildReportUrl\`, \`verifyPreparingPhase\`, \`waitForReportDownload\``,
+    waitForReportDownload: `# waitForReportDownload
+
+\`\`\`typescript
+import { waitForReportDownload } from '@iblai/iblai-js/playwright';
+
+async function waitForReportDownload(
+  page: Page,
+  options: ReportDownloadOptions
+): Promise<void>
+\`\`\`
+
+Full report download flow: navigates, waits through preparing → downloading → done phases.
+
+**Related:** \`navigateToReportDownload\`, \`verifyPreparingPhase\`, \`verifyDownloadingPhase\`, \`verifyDonePhase\``,
+    // ============================================================================
+    // SHARED TEST HELPERS
+    // ============================================================================
+    inviteUserTest: `# inviteUserTest
+
+\`\`\`typescript
+import { inviteUserTest } from '@iblai/iblai-js/playwright';
+
+async function inviteUserTest(page: Page, inviteModal: Locator): Promise<void>
+\`\`\`
+
+Shared test helper for invite user flow. Opens invite modal, fills email, submits.
+
+**Related:** \`navigateToAccountComponent\``,
+    navigateToDataReports: `# navigateToDataReports
+
+\`\`\`typescript
+import { navigateToDataReports } from '@iblai/iblai-js/playwright';
+
+async function navigateToDataReports(page: Page): Promise<void>
+\`\`\`
+
+Navigate to the Data Reports section in analytics.
+
+**Related:** \`shouldDisplayReportCards\``,
+    shouldDisplayReportCards: `# shouldDisplayReportCards
+
+\`\`\`typescript
+import { shouldDisplayReportCards } from '@iblai/iblai-js/playwright';
+
+async function shouldDisplayReportCards(
+  page: Page,
+  reportCards: Array<{ name: string; testId: string }>
+): Promise<void>
+\`\`\`
+
+Verify that report cards are displayed with correct names and test IDs.
+
+**Related:** \`navigateToDataReports\``,
+};
+// Aliases — common alternate names
+helpers['safe_wait_for_url'] = helpers['safeWaitForURL'];
+helpers['wait_for_page_ready'] = helpers['waitForPageReady'];
+helpers['reliable_click'] = helpers['reliableClick'];
+helpers['reliable_fill'] = helpers['reliableFill'];
+helpers['wait_for_dialog_ready'] = helpers['waitForDialogReady'];
+helpers['close_with_esc'] = helpers['closeWithEsc'];
+helpers['create_auth_setup'] = helpers['createAuthSetup'];
+helpers['create_playwright_config'] = helpers['createPlaywrightConfig'];
+helpers['create_env_config'] = helpers['createEnvConfig'];
+helpers['expect_no_accessibility_violations'] = helpers['expectNoAccessibilityViolations'];
+helpers['login_with_email_and_password'] = helpers['loginWithEmailAndPassword'];
+helpers['wait_for_page_load'] = helpers['waitForPageLoad'];
+helpers['build_report_url'] = helpers['buildReportUrl'];
+helpers['wait_for_report_download'] = helpers['waitForReportDownload'];
+export function getPlaywrightHelperInfo(helperName) {
+    const info = helpers[helperName];
+    if (info)
+        return info;
+    // Fuzzy match
+    const lower = helperName.toLowerCase();
+    const match = Object.keys(helpers).find((k) => k.toLowerCase() === lower || k.toLowerCase().replace(/_/g, '') === lower.replace(/_/g, ''));
+    if (match)
+        return helpers[match];
+    const available = Object.keys(helpers)
+        .filter((k) => !k.includes('_'))
+        .sort()
+        .join(', ');
+    return `Helper "${helperName}" not found.\n\nAvailable helpers:\n${available}\n\nUse get_playwright_helper_info with any of the above names.`;
+}
+//# sourceMappingURL=playwright-helper-info.js.map