@esimplicitylabs/katalyst-xspec 0.7.1 → 0.8.0

package/README.md

@@ -22,7 +22,7 @@ npm test
 
 - **Fixtures**: `createBddTest` wiring world, api/ui/auth/cleanup adapters.
 - **Ports**: `ApiPort`, `UiPort`, `AuthPort`, `CleanupPort`.
-- **Adapters**: Playwright API/UI adapters, default cleanup, example auth adapter.
+- **Adapters**: Playwright API/UI adapters, default cleanup, `UniversalAuthAdapter` (role-based API and UI login).
 - **Step registrations**: API (auth/http/assertions), UI (basic + wizard), shared vars/cleanup, hybrid helpers.
 - **Config helpers**: `tagsForProject` / `resolveExtraTags` for optional tag filtering (`@Skip`/`@ignore`, `TEST_TAGS`).
 
@@ -57,6 +57,20 @@ registerApiSteps(test);
 
 3) Configure Playwright projects with your features/steps globs (each project selects feature files by folder; tags are optional). Keep `@playwright/test` and `playwright-bdd` aligned with peer ranges.
 
+## Logging in
+
+Set credentials per role in `.env` (`AUTH_ADMIN_USERNAME` / `AUTH_ADMIN_PASSWORD`, `AUTH_PM_USERNAME` / ..., any role name) and use the role in features:
+
+```gherkin
+Given I am authenticated as "pm" via API
+Given I am logged in as "pm"
+When I log in as "pm" in UI
+```
+
+Missing credentials fail the step with a message naming the variables. Login endpoint, body format, token location and form fields are set with `API_AUTH_*` / `UI_*` variables; see the [Authentication guide](https://github.com/esimplicityinc/katalyst-xspec/blob/main/docs/guides/authentication.md).
+
+`FRONTEND_URL` sets where UI steps go; `API_BASE_URL` is optional (API calls go to `FRONTEND_URL` without it).
+
 ## Publishing (npm)
 
 Publishing is automated. The `.github/workflows/publish.yml` workflow builds the package and publishes it to the

package/cli/init.cjs

@@ -301,7 +301,7 @@ function templates(packageName) {
       clean: 'rm -rf .features-gen node_modules test-results storage cucumber-report playwright-report'
     },
     devDependencies: {
-      '@esimplicitylabs/katalyst-xspec': '^0.7.0',
+      '@esimplicitylabs/katalyst-xspec': '^0.8.0',
       '@playwright/test': '^1.49.0',
       'playwright-bdd': '^9.1.0',
       dotenv: '^16.1.4',
@@ -335,7 +335,12 @@ function templates(packageName) {
 export const { test } = createBddTest({
   createApi: ({ apiRequest }) => new PlaywrightApiAdapter(apiRequest),
   createUi: ({ page }) => new PlaywrightUiAdapter(page),
-  createAuth: ({ api, ui }) => new UniversalAuthAdapter({ api, ui }),
+  // Logins read AUTH_<ROLE>_USERNAME / AUTH_<ROLE>_PASSWORD and the API_AUTH_* /
+  // UI_LOGIN_* settings in .env. You can also give credentials in code:
+  //   roles: { pm: { username: 'pm@example.com', password: process.env.PM_PASSWORD } },
+  // For SSO or unusual login flows, subclass UniversalAuthAdapter and override
+  // apiLogin() / uiLogin() (see the Authentication guide).
+  createAuth: ({ api, ui }) => new UniversalAuthAdapter({ api, ui, roles: {} }),
   createCleanup: () => new DefaultCleanupAdapter(),
   // TUI testing (optional - requires tui-tester and tmux installed)
   // Uncomment and configure for your CLI application:
@@ -370,7 +375,7 @@ export { test };
 
   const playwrightConfig = `import { defineConfig } from '@playwright/test';
 import { defineBddProject, cucumberReporter } from 'playwright-bdd';
-import { resolveWorkers, tagsForProject, resolveExtraTags } from '@esimplicitylabs/katalyst-xspec';
+import { resolveWorkers, tagsForProject, resolveExtraTags, resolveTargets, logTargets } from '@esimplicitylabs/katalyst-xspec';
 import dotenv from 'dotenv';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -388,6 +393,10 @@ if (fs.existsSync(localEnvPath)) {
   dotenv.config();
 }
 
+// UI and API base URLs from FRONTEND_URL / API_BASE_URL (API falls back to the
+// frontend URL). Printed once per run; silence with KATALYST_XSPEC_QUIET=true.
+const targets = logTargets(resolveTargets());
+
 // Each project runs the feature files in its folder. Any scenario can use any
 // step (API, UI, shared). Tags are optional: use your own (e.g. @smoke) and
 // filter with TEST_TAGS="@smoke"; scenarios tagged @Skip or @ignore are skipped.
@@ -425,7 +434,7 @@ export default defineConfig({
   // Add tuiBdd to this array when TUI testing is enabled
   projects: [apiBdd, uiBdd /* , tuiBdd */],
   use: {
-    baseURL: process.env.BASE_URL || process.env.FRONTEND_URL || 'http://localhost:3000',
+    baseURL: targets.frontendUrl,
     headless: process.env.HEADLESS === 'false' ? false : true,
   },
 });
@@ -480,27 +489,45 @@ storage
 .env
 `; 
 
-  const envExample = `# API defaults used by the auth and cleanup helpers
-DEFAULT_ADMIN_USERNAME=admin@example.com
-DEFAULT_ADMIN_PASSWORD=changeme
-API_AUTH_LOGIN_PATH=/auth/login
-API_BASE_URL=http://localhost:3000
-
-# UI defaults
+  const envExample = `# ── Where to test ──────────────────────────────────────────────
+# Relative paths in steps ("/login", "/api/users") use these.
+# API_BASE_URL is optional: without it, API calls go to FRONTEND_URL.
 FRONTEND_URL=http://localhost:3000
+# API_BASE_URL=http://localhost:4000
 HEADLESS=true
 
-# Cleanup rules (JSON array)
+# ── Who logs in ────────────────────────────────────────────────
+# One pair per role. Use any role name: "pm" reads AUTH_PM_USERNAME/PASSWORD.
+#   Given I am authenticated as "admin" via API
+#   Given I am logged in as "admin"
+AUTH_ADMIN_USERNAME=admin@example.com
+AUTH_ADMIN_PASSWORD=changeme
+# AUTH_USER_USERNAME=user@example.com
+# AUTH_USER_PASSWORD=changeme
+
+# ── API login (defaults shown) ─────────────────────────────────
+# API_AUTH_LOGIN_PATH=/auth/login
+# API_AUTH_BODY=form                 # or json
+# API_AUTH_USERNAME_FIELD=username   # e.g. email
+# API_AUTH_PASSWORD_FIELD=password
+# API_AUTH_TOKEN_PATH=access_token   # e.g. data.token; default tries common names.
+#                                    # No token but a session cookie also works.
+
+# ── UI login (defaults shown) ──────────────────────────────────
+# UI_LOGIN_PATH=/login
+# UI_USERNAME_FIELD=Username         # label, placeholder or name of the field
+# UI_PASSWORD_FIELD=Password
+# UI_LOGIN_BUTTON=Login
+# UI_LOGIN_SUCCESS_URL=/dashboard    # default: any page other than the login page
+# UI_LOGIN_SUCCESS_TEXT=Welcome      # use if the URL doesn't change after login
+# UI_SESSION_REUSE=true              # "I am logged in as" reuses the session
+
+# ── Other ──────────────────────────────────────────────────────
 # CLEANUP_RULES=[{"varMatch":"user","path":"/api/users/{id}"}]
-
-# TUI testing (optional)
-# Set DEBUG=true to see TUI tester output
-DEBUG=false
-
-# Worker configuration
-# Set to a number for explicit worker count, or "auto" to let Playwright decide
-# In CI, defaults to 1 for stability unless explicitly overridden
-# WORKERS=auto
+# TEST_TAGS=@smoke                   # run only scenarios with these tags
+# WORKERS=auto                       # defaults to 1 in CI
+# KATALYST_XSPEC_QUIET=true          # don't print the targets line
+# DEBUG=false                        # TUI tester output
 `;
 
   const readme = `# ${packageName}

package/cli/upgrade.cjs

@@ -553,7 +553,7 @@ function getTemplates() {
       clean: 'rm -rf .features-gen node_modules test-results storage cucumber-report playwright-report'
     },
     devDependencies: {
-      '@esimplicitylabs/katalyst-xspec': '^0.7.0',
+      '@esimplicitylabs/katalyst-xspec': '^0.8.0',
       '@playwright/test': '^1.49.0',
       'playwright-bdd': '^9.1.0',
       dotenv: '^16.1.4',
@@ -576,7 +576,12 @@ function getTemplates() {
 export const { test } = createBddTest({
   createApi: ({ apiRequest }) => new PlaywrightApiAdapter(apiRequest),
   createUi: ({ page }) => new PlaywrightUiAdapter(page),
-  createAuth: ({ api, ui }) => new UniversalAuthAdapter({ api, ui }),
+  // Logins read AUTH_<ROLE>_USERNAME / AUTH_<ROLE>_PASSWORD and the API_AUTH_* /
+  // UI_LOGIN_* settings in .env. You can also give credentials in code:
+  //   roles: { pm: { username: 'pm@example.com', password: process.env.PM_PASSWORD } },
+  // For SSO or unusual login flows, subclass UniversalAuthAdapter and override
+  // apiLogin() / uiLogin() (see the Authentication guide).
+  createAuth: ({ api, ui }) => new UniversalAuthAdapter({ api, ui, roles: {} }),
   createCleanup: () => new DefaultCleanupAdapter(),
   // TUI testing (optional - requires tui-tester and tmux installed)
   // Uncomment and configure for your CLI application:
@@ -634,6 +639,7 @@ async function migrate(cwd, options) {
   
   log('Starting migration...');
   log(`Backup directory: ${backupDir}`);
+  const templates = getTemplates();
   console.log('');
   
   // =========================================================================
@@ -714,6 +720,7 @@ async function migrate(cwd, options) {
     }
     if (existingFixturesTs) {
       fs.writeFileSync(path.join(backupDir, 'steps', 'fixtures.ts.original'), existingFixturesTs);
+      fs.writeFileSync(path.join(backupDir, 'steps', 'fixtures.ts.template'), templates['features/steps/fixtures.ts']);
     }
   }
   
@@ -728,7 +735,6 @@ async function migrate(cwd, options) {
   // =========================================================================
   log('Phase 3: Merging configurations...');
   
-  const templates = getTemplates();
   const filesToUpdate = {};
   
   // Merge package.json
@@ -745,13 +751,18 @@ async function migrate(cwd, options) {
   );
   console.log(`  steps.ts: merged (${customImports.length} custom imports preserved)`);
   
-  // Merge fixtures.ts
-  filesToUpdate['features/steps/fixtures.ts'] = mergeFixturesTs(
-    existingFixturesTs,
-    templates['features/steps/fixtures.ts'],
-    cleanupRules
-  );
-  console.log(`  fixtures.ts: merged (cleanup rules ${cleanupRules ? 'preserved' : 'using defaults'})`);
+  // fixtures.ts is your adapter wiring (custom auth, roles, cleanup rules): keep
+  // it, and leave the current template in the backup folder for comparison.
+  if (existingFixturesTs) {
+    console.log(`  fixtures.ts: kept (template saved as ${path.join(backupDir, 'steps', 'fixtures.ts.template')})`);
+  } else {
+    filesToUpdate['features/steps/fixtures.ts'] = mergeFixturesTs(
+      existingFixturesTs,
+      templates['features/steps/fixtures.ts'],
+      cleanupRules
+    );
+    console.log('  fixtures.ts: created');
+  }
   console.log('');
   
   // =========================================================================

package/dist/{chunk-UTTKW2SR.js → chunk-VHVH476W.js}

@@ -145,13 +145,34 @@ function registerApiAssertionSteps(test) {
 
 // src/steps/api.auth.ts
 import { createBdd as createBdd3 } from "playwright-bdd";
+
+// src/auth/login-steps.ts
+async function apiLoginAsRole(auth, world, role) {
+  const name = interpolate(role, world.vars);
+  if (auth.apiLoginAs) return auth.apiLoginAs(world, name);
+  if (name === "admin") return auth.apiLoginAsAdmin(world);
+  if (name === "user") return auth.apiLoginAsUser(world);
+  throw new Error(`Your auth adapter doesn't implement apiLoginAs(world, role), so it can't log in as "${name}".`);
+}
+async function uiLoginAsRole(auth, world, role, options) {
+  const name = interpolate(role, world.vars);
+  if (auth.uiLoginAs) return auth.uiLoginAs(world, name, options);
+  if (name === "admin") return auth.uiLoginAsAdmin(world);
+  if (name === "user") return auth.uiLoginAsUser(world);
+  throw new Error(`Your auth adapter doesn't implement uiLoginAs(world, role), so it can't log in as "${name}".`);
+}
+
+// src/steps/api.auth.ts
 function registerApiAuthSteps(test) {
   const { Given } = createBdd3(test);
+  Given("I am authenticated as {string} via API", async ({ auth, world }, role) => {
+    await apiLoginAsRole(auth, world, role);
+  });
   Given("I am authenticated as an admin via API", async ({ auth, world }) => {
-    await auth.apiLoginAsAdmin(world);
+    await apiLoginAsRole(auth, world, "admin");
   });
   Given("I am authenticated as a user via API", async ({ auth, world }) => {
-    await auth.apiLoginAsUser(world);
+    await apiLoginAsRole(auth, world, "user");
   });
   Given("I set bearer token from variable {string}", async ({ auth, world }, varName) => {
     const token = world.vars[varName];
@@ -353,11 +374,21 @@ function registerUiBasicSteps(test) {
   When("I fill in {string} with {string}", async ({ ui, world }, label, value) => {
     await ui.fillLabel(interpolate(label, world.vars), interpolate(value, world.vars));
   });
-  When("I log in as admin in UI", async ({ auth, world }) => {
-    await auth.uiLoginAsAdmin(world);
+  Given("I am logged in as {string}", async ({ auth, ui, world }, role) => {
+    void ui;
+    await uiLoginAsRole(auth, world, role, { reuseSession: true });
+  });
+  When("I log in as {string} in UI", async ({ auth, ui, world }, role) => {
+    void ui;
+    await uiLoginAsRole(auth, world, role);
+  });
+  When("I log in as admin in UI", async ({ auth, ui, world }) => {
+    void ui;
+    await uiLoginAsRole(auth, world, "admin");
   });
-  When("I log in as user in UI", async ({ auth, world }) => {
-    await auth.uiLoginAsUser(world);
+  When("I log in as user in UI", async ({ auth, ui, world }) => {
+    void ui;
+    await uiLoginAsRole(auth, world, "user");
   });
   When("I click the element {string}", async ({ page, world }, selector) => {
     await page.locator(interpolate(selector, world.vars)).click();
@@ -1528,6 +1559,8 @@ export {
   setupBearerAuth,
   registerApiHttpSteps,
   registerApiAssertionSteps,
+  apiLoginAsRole,
+  uiLoginAsRole,
   registerApiAuthSteps,
   registerHybridSteps,
   registerSharedCleanupSteps,

package/dist/index.d.ts

@@ -68,14 +68,51 @@ interface UiPort {
     expectElementWithTextVisible(elementType: string, text: string, shouldBeVisible: boolean): Promise<void>;
     expectElementState(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState): Promise<void>;
     expectElementStateWithin(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState, seconds: number): Promise<void>;
+    /**
+     * Fill a field found by (in order) exact label, exact placeholder, label,
+     * placeholder, or name attribute. Resolves false if none appears in time.
+     */
+    fillField?(name: string, value: string, options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    /** Wait until the URL satisfies `predicate`; resolves false on timeout. */
+    waitForUrl?(predicate: (url: string) => boolean, timeoutMs: number): Promise<boolean>;
+    /** Wait until `text` is visible; resolves false on timeout. */
+    waitForText?(text: string, timeoutMs: number): Promise<boolean>;
+    /** Snapshot cookies + localStorage (Playwright storageState). */
+    saveSession?(): Promise<UiSessionState>;
+    /** Apply a snapshot from saveSession() to the current browser context. */
+    restoreSession?(state: UiSessionState): Promise<void>;
 }
+/** Opaque browser session snapshot (Playwright `storageState()` shape). */
+type UiSessionState = {
+    cookies: Array<Record<string, unknown>>;
+    origins: Array<{
+        origin: string;
+        localStorage: Array<{
+            name: string;
+            value: string;
+        }>;
+    }>;
+};
 
+type UiLoginOptions = {
+    /** Log in through the form once per role (per worker), then restore the saved session. */
+    reuseSession?: boolean;
+};
 interface AuthPort {
     apiLoginAsAdmin(world: World): Promise<void>;
     apiLoginAsUser(world: World): Promise<void>;
     apiSetBearer(world: World, token: string): void;
     uiLoginAsAdmin(world: World): Promise<void>;
     uiLoginAsUser(world: World): Promise<void>;
+    /**
+     * Log in to the API as any named role. Optional so pre-0.8 custom adapters
+     * keep compiling; the built-in steps fall back to the admin/user methods.
+     */
+    apiLoginAs?(world: World, role: string): Promise<void>;
+    /** Log in through the UI as any named role. */
+    uiLoginAs?(world: World, role: string, options?: UiLoginOptions): Promise<void>;
 }
 
 interface CleanupPort {
@@ -363,6 +400,10 @@ type TuiFactory = () => TuiPort | undefined;
 type CreateBddTestOptions = {
     createApi?: (ctx: CreateContext) => ApiPort;
     createUi?: (ctx: CreateContext) => UiPort;
+    /**
+     * Build the auth adapter. `ui` is available to UI login methods once a step
+     * requests the `ui` fixture; API login never starts a browser.
+     */
     createAuth?: (ctx: CreateContext & {
         api: ApiPort;
         ui: UiPort;
@@ -407,6 +448,9 @@ declare function createBddTest(options?: CreateBddTestOptions): {
         cleanup: CleanupPort;
         tui: TuiPort | undefined;
         apiRequest: APIRequestContext;
+        uiBinding: {
+            current?: UiPort;
+        };
     }, PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions & playwright_bdd.BddWorkerFixtures>;
     expect: _playwright_test.Expect<{}>;
 };
@@ -458,24 +502,82 @@ declare class PlaywrightUiAdapter implements UiPort {
     expectElementStateWithin(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState, seconds: number): Promise<void>;
     private parseOrdinal;
     private locatorBy;
+    fillField(name: string, value: string, options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    waitForUrl(predicate: (url: string) => boolean, timeoutMs: number): Promise<boolean>;
+    waitForText(text: string, timeoutMs: number): Promise<boolean>;
+    saveSession(): Promise<UiSessionState>;
+    restoreSession(state: UiSessionState): Promise<void>;
     private performClick;
     private expectState;
     private assertUrlAgainst;
 }
 
+/**
+ * Login credentials by role.
+ *
+ * Any role name works: "pm" reads AUTH_PM_USERNAME / AUTH_PM_PASSWORD,
+ * "project manager" reads AUTH_PROJECT_MANAGER_USERNAME / ..._PASSWORD.
+ * Roles passed in code (UniversalAuthAdapter `roles` option) take precedence.
+ * "admin" and "user" also accept the pre-0.8 DEFAULT_* / NON_ADMIN_* names.
+ */
+type Env$3 = Record<string, string | undefined>;
+type Credentials = {
+    username: string;
+    password: string;
+};
+type RoleCredentials = Record<string, Partial<Credentials>>;
+declare class MissingCredentialsError extends Error {
+    constructor(message: string);
+}
+declare function roleEnvKeys(role: string): {
+    username: string;
+    password: string;
+};
+declare function resolveCredentials(role: string, { env, roles }?: {
+    env?: Env$3;
+    roles?: RoleCredentials;
+}): Credentials;
+
+type Env$2 = Record<string, string | undefined>;
+type UniversalAuthOptions = {
+    api: ApiPort;
+    ui: UiPort;
+    /** Credentials per role, e.g. { pm: { username, password } }. Overrides AUTH_<ROLE>_* env vars. */
+    roles?: RoleCredentials;
+    /** Settings source; defaults to process.env. */
+    env?: Env$2;
+};
+/** Forget saved UI sessions (e.g. after changing a password mid-run). */
+declare function clearUiSessions(): void;
+/**
+ * Logs in by role through the API or the UI, configured by environment
+ * variables (see docs/guides/authentication.md).
+ *
+ * Extend it by subclassing and overriding `apiLogin` / `uiLogin` (e.g. for SSO
+ * or a multi-step form); credentials, steps and session reuse keep working.
+ */
 declare class UniversalAuthAdapter implements AuthPort {
-    private readonly deps;
-    constructor(deps: {
-        api: ApiPort;
-        ui: UiPort;
-    });
+    protected readonly api: ApiPort;
+    protected readonly ui: UiPort;
+    protected readonly roles?: RoleCredentials;
+    protected readonly env: Env$2;
+    constructor(options: UniversalAuthOptions);
+    /** Credentials for a role; throws MissingCredentialsError with the variables to set. */
+    credentialsFor(role: string): Credentials;
     apiSetBearer(world: World, token: string): void;
+    apiLoginAs(world: World, role: string): Promise<void>;
+    uiLoginAs(world: World, role: string, options?: UiLoginOptions): Promise<void>;
     apiLoginAsAdmin(world: World): Promise<void>;
     apiLoginAsUser(world: World): Promise<void>;
-    private apiLogin;
     uiLoginAsAdmin(world: World): Promise<void>;
     uiLoginAsUser(world: World): Promise<void>;
-    private uiLogin;
+    /** POST credentials to the login endpoint; keep the bearer token or session cookie. */
+    protected apiLogin(world: World, role: string, creds: Credentials): Promise<void>;
+    /** Fill and submit the login form, then confirm the login worked. */
+    protected uiLogin(_world: World, role: string, creds: Credentials): Promise<void>;
+    private sessionReuseEnabled;
 }
 
 type CleanupRule = {
@@ -881,4 +983,54 @@ type ApiRequestTarget = {
 };
 declare function resolveApiRequestTarget(baseURL: string, env?: Record<string, string | undefined>): ApiRequestTarget;
 
-export { type ApiMethod, type ApiPort, type ApiRequestTarget, type ApiResult, type AuthPort, type CleanupAuthProvider, type CleanupItem, type CleanupPort, type CleanupRule, type CreateBddTestOptions, DefaultCleanupAdapter, type FetchInterceptAuthData, type FetchInterceptConfig, type OidcCleanupAuthConfig, PlaywrightApiAdapter, PlaywrightUiAdapter, type ResolveFeaturesOptions, type ResolveStepsOptions, type ResolveWorkersOptions, type TuiConfig, type TuiFactory, type TuiKeyModifiers, type TuiMouseButton, type TuiMouseEvent, type TuiMouseEventType, type TuiPort, type TuiScreenCapture, type TuiSnapshotResult, TuiTesterAdapter, type TuiWaitOptions, type UiClickMode, type UiElementState, type UiInputMode, type UiLocatorMethod, type UiPort, type UiUrlAssertMode, UniversalAuthAdapter, type World, assertMasked, clearFetchIntercept, createBddTest, createOidcCleanupAuth, defaultBearerConfig, defaultBypassConfig, getCpuCount, initWorld, interpolate, parseExpected, registerCleanup, resetOidcCleanupAuth, resolveApiRequestTarget, resolveBddPaths, resolveExtraTags, resolveFeatures, resolveSteps, resolveWorkers, selectPath, setupBearerAuth, setupBypassAuth, setupFetchIntercept, tagsForProject, tryParseJson };
+/**
+ * Where tests point: the frontend (UI) and the API.
+ *
+ * Canonical variables are FRONTEND_URL and API_BASE_URL. BASE_URL and
+ * TARGET_BASE_URL are accepted as older aliases. When no API URL is set, API
+ * requests go to the frontend URL, so same-origin apps (`/api/...`) and
+ * scenarios that mix API and UI steps work with a single setting.
+ */
+type Env$1 = Record<string, string | undefined>;
+type Targets = {
+    frontendUrl: string;
+    frontendSource: 'FRONTEND_URL' | 'BASE_URL' | 'default';
+    apiBaseUrl: string;
+    apiSource: 'API_BASE_URL' | 'TARGET_BASE_URL' | 'TARGET_PORT' | 'FRONTEND_URL' | 'default';
+};
+/** Resolve the frontend and API targets from environment variables. */
+declare function resolveTargets(env?: Env$1): Targets;
+/**
+ * Base URL for the API request context in a given Playwright project.
+ * Order: API_BASE_URL > TARGET_BASE_URL > baseURL of a project named like
+ * "api" > TARGET_PORT > the project's baseURL (any project) > localhost:3000.
+ */
+declare function resolveApiBaseUrl({ env, projectName, projectBaseURL, }: {
+    env?: Env$1;
+    projectName?: string;
+    projectBaseURL?: string;
+}): string;
+declare function formatTargets(t: Targets): string;
+/** Only the main `playwright test` process logs (not workers, not bddgen). */
+declare function shouldLogTargets(env?: Env$1, argv?: string[]): boolean;
+/**
+ * Print the resolved targets once per run. Call from playwright.config.ts.
+ * Silence with KATALYST_XSPEC_QUIET=true.
+ */
+declare function logTargets(targets?: Targets): Targets;
+
+type Env = Record<string, string | undefined>;
+type ApiLoginRequest = {
+    path: string;
+    body: 'form' | 'json';
+    fields: Record<string, string>;
+};
+declare function buildApiLoginRequest(creds: Credentials, env?: Env): ApiLoginRequest;
+declare function extractToken(json: unknown, env?: Env): string | undefined;
+
+/** Log in to the API as a role, supporting pre-0.8 adapters that only know admin/user. */
+declare function apiLoginAsRole(auth: AuthPort, world: World, role: string): Promise<void>;
+/** Log in through the UI as a role, supporting pre-0.8 adapters that only know admin/user. */
+declare function uiLoginAsRole(auth: AuthPort, world: World, role: string, options?: UiLoginOptions): Promise<void>;
+
+export { type ApiLoginRequest, type ApiMethod, type ApiPort, type ApiRequestTarget, type ApiResult, type AuthPort, type CleanupAuthProvider, type CleanupItem, type CleanupPort, type CleanupRule, type CreateBddTestOptions, type Credentials, DefaultCleanupAdapter, type FetchInterceptAuthData, type FetchInterceptConfig, MissingCredentialsError, type OidcCleanupAuthConfig, PlaywrightApiAdapter, PlaywrightUiAdapter, type ResolveFeaturesOptions, type ResolveStepsOptions, type ResolveWorkersOptions, type RoleCredentials, type Targets, type TuiConfig, type TuiFactory, type TuiKeyModifiers, type TuiMouseButton, type TuiMouseEvent, type TuiMouseEventType, type TuiPort, type TuiScreenCapture, type TuiSnapshotResult, TuiTesterAdapter, type TuiWaitOptions, type UiClickMode, type UiElementState, type UiInputMode, type UiLocatorMethod, type UiLoginOptions, type UiPort, type UiSessionState, type UiUrlAssertMode, UniversalAuthAdapter, type UniversalAuthOptions, type World, apiLoginAsRole, assertMasked, buildApiLoginRequest, clearFetchIntercept, clearUiSessions, createBddTest, createOidcCleanupAuth, defaultBearerConfig, defaultBypassConfig, extractToken, formatTargets, getCpuCount, initWorld, interpolate, logTargets, parseExpected, registerCleanup, resetOidcCleanupAuth, resolveApiBaseUrl, resolveApiRequestTarget, resolveBddPaths, resolveCredentials, resolveExtraTags, resolveFeatures, resolveSteps, resolveTargets, resolveWorkers, roleEnvKeys, selectPath, setupBearerAuth, setupBypassAuth, setupFetchIntercept, shouldLogTargets, tagsForProject, tryParseJson, uiLoginAsRole };