@iblai/iblai-js 1.0.20 → 1.0.22

package/README.md

@@ -30,6 +30,8 @@ npm install react react-dom @reduxjs/toolkit react-redux @iblai/iblai-api
 
 `next` (>= 15) is an **optional** peer dependency, required only when using `@iblai/iblai-js/web-containers/next`.
 
+`@playwright/test` and `@axe-core/playwright` are **optional** peer dependencies, required only when using `@iblai/iblai-js/playwright`.
+
 ## Framework Configuration
 
 ### Next.js
@@ -381,6 +383,150 @@ import {
 
 ---
 
+### `@iblai/iblai-js/playwright`
+
+Shared Playwright test utilities for E2E testing across IBL.ai apps. Unlike the other subpaths, this is **not** a re-export — it contains original source code for test infrastructure shared between standalone app repos (mentorai, skillsai).
+
+**Requires:** `@playwright/test` and `@axe-core/playwright` as dev dependencies.
+
+```bash
+pnpm add -D @playwright/test @axe-core/playwright dotenv cross-env
+```
+
+#### Config Generation
+
+Generate a complete Playwright config with per-browser auth setup projects:
+
+```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: 'skills',
+      dependencies: ['setup'],
+      otherTestMatch: ['**skills/*/*.spec.ts'],
+    },
+  ],
+});
+```
+
+`createPlaywrightConfig` generates browser-specific setup projects (Chrome, Firefox, Safari, Edge) that each run `auth.setup.ts`, then creates test projects for each platform/browser combination. The `devices` option defaults to `['Desktop Chrome', 'Desktop Firefox', 'Desktop Safari', 'Desktop Edge']`.
+
+#### Auth Setup
+
+Create an `auth.setup.ts` that authenticates once per browser and saves the storage state:
+
+```typescript
+// e2e/auth.setup.ts
+import { test as setup, createAuthSetup } from '@iblai/iblai-js/playwright';
+
+setup(
+  'authenticate',
+  createAuthSetup({
+    hostUrl: process.env.SKILLS_HOST || '',
+    authHost: process.env.AUTH_HOST || '',
+    appName: 'skills',
+    postLoginUrlMatcher: (url) =>
+      url.href.includes('/home') || url.href.includes('/start'),
+  })
+);
+```
+
+`createAuthSetup` supports four auth flows via the `authFlow` option: `'username_password'` (default), `'magic_link'`, `'sso'`, and `'direct_sso'`. Credentials are read from `PLAYWRIGHT_USERNAME` and `PLAYWRIGHT_PASSWORD` env vars.
+
+#### Custom Reporter
+
+Re-export the SDK's custom reporter for Playwright:
+
+```typescript
+// e2e/custom-reporter.ts
+export { CustomReporter as default } from '@iblai/iblai-js/playwright';
+```
+
+#### Test Helpers
+
+```typescript
+import {
+  // Extended test fixture with step support (optional — most tests use @playwright/test directly)
+  test,
+  expect,
+
+  // Navigation
+  safeWaitForURL,
+  waitForPageLoad,
+  isFirefox,
+
+  // Page interaction
+  waitForPageReady,
+  checkAdminStatus,
+  reliableClick,
+  reliableFill,
+  waitForDialogReady,
+  selectDateFromCalendar,
+
+  // Accessibility
+  expectNoAccessibilityViolations,
+  expectNoAccessibilityViolationsOnDialogs,
+
+  // Auth helpers
+  loginWithEmailAndPassword,
+  signUpWithEmailAndPassword,
+  loginWithMicrosoftIdp,
+  AuthFlowBuilder,
+  createAuthSetup,
+
+  // Logging
+  logger,
+
+  // Email testing
+  MailsacClient,
+
+  // Config generation
+  createPlaywrightConfig,
+  createEnvConfig,
+  CustomReporter,
+} from '@iblai/iblai-js/playwright';
+```
+
+#### Environment Variables
+
+Tests expect these env vars (set them in `.env.development` or CI):
+
+| Variable | Description |
+| --- | --- |
+| `SKILLS_HOST` / `MENTOR_NEXTJS_HOST` | App host URL |
+| `AUTH_HOST` | Auth service URL |
+| `PLAYWRIGHT_USERNAME` | Login username |
+| `PLAYWRIGHT_PASSWORD` | Login password |
+| `AUTH_FLOW` | Auth flow type (`username_password`, `magic_link`, `sso`, `direct_sso`) |
+| `AUTH_IDP` | SSO identity provider name (required for `sso`/`direct_sso` flows) |
+
+#### Directory Structure
+
+Both mentorai and skillsai follow this layout:
+
+```
+e2e/
+├── playwright.config.ts     # Uses createPlaywrightConfig()
+├── auth.setup.ts            # Uses createAuthSetup()
+├── custom-reporter.ts       # Re-exports CustomReporter
+├── .env.development         # Environment variables
+├── tests/
+│   ├── utils.ts             # App-specific env var exports
+│   ├── helpers.ts           # App-specific auth/login helpers
+│   ├── shared.ts            # Shared test helper functions
+│   └── <platform>/          # Test spec files by feature
+└── utils/                   # App-specific helper modules
+```
+
+---
+
 ## Relationship to Standalone Packages
 
 `@iblai/iblai-js` is a convenience wrapper. Each subpath is a direct re-export from its standalone package:
@@ -392,8 +538,9 @@ import {
 | `@iblai/iblai-js/web-containers/next` | `@iblai/web-containers/next`|
 | `@iblai/iblai-js/web-containers/sso`  | `@iblai/web-containers/sso` |
 | `@iblai/iblai-js/web-utils`           | `@iblai/web-utils`          |
+| `@iblai/iblai-js/playwright`          | Original source (not a re-export) |
 
-You can use the standalone packages directly if you only need one module. This unified package is useful when you need multiple IBL libraries and prefer a single dependency.
+You can use the standalone packages directly if you only need one module. This unified package is useful when you need multiple IBL libraries and prefer a single dependency. The `playwright` subpath is unique — it contains original source code rather than re-exporting a standalone package.
 
 ## TypeScript