shiplightai 0.1.74 → 0.1.76

package/dist/fixture.d.ts

@@ -32,6 +32,76 @@ interface AuthSpec {
  * so multiple tests sharing the same auth path reuse the same instance.
  */
 declare function resolveAuthState(spec: AuthSpec): Promise<string>;
+/**
+ * Standard Playwright context-option `use:` keys whose resolved (per-test aware)
+ * values we overlay onto `testInfo.project.use`. Must stay identical to the
+ * fixture-arg destructure and the `resolvedContextOptions` object in the
+ * `context` fixture below — the drift guard test
+ * (fixture.contextOptions.test.ts) asserts this set, together with
+ * EXCLUDED_CONTEXT_OPTION_KEYS, equals the full set Playwright actually resolves.
+ */
+declare const HANDLED_CONTEXT_OPTION_KEYS: readonly ["acceptDownloads", "baseURL", "bypassCSP", "colorScheme", "deviceScaleFactor", "extraHTTPHeaders", "geolocation", "hasTouch", "httpCredentials", "ignoreHTTPSErrors", "isMobile", "javaScriptEnabled", "locale", "offline", "permissions", "proxy", "serviceWorkers", "timezoneId", "userAgent", "viewport"];
+/**
+ * Context-option keys Playwright resolves that we deliberately do NOT overlay:
+ * - `storageState`: the fixture's auth system owns it (see resolveAuthState).
+ * - `contextOptions`: raw escape-hatch object, left to flow through unchanged.
+ * - `clientCertificates`: specially resolved by Playwright; left untouched.
+ */
+declare const EXCLUDED_CONTEXT_OPTION_KEYS: readonly ["storageState", "contextOptions", "clientCertificates"];
+/**
+ * Context options Playwright rejects when `viewport` is `null` (no fixed
+ * viewport / `noDefaultViewport`). Each entry's `conflicts` predicate mirrors
+ * the exact condition in Playwright's `validateBrowserContextOptions`:
+ *   - `deviceScaleFactor`: throws when `!== void 0` (any defined value).
+ *   - `isMobile`: throws when `!!isMobile` (any truthy value).
+ * The drift guard test asserts these keys stay in sync with that function, so a
+ * future Playwright that adds a new `viewport: null` conflict fails loudly
+ * instead of crashing context creation unguarded.
+ */
+declare const VIEWPORT_INCOMPATIBLE_OPTIONS: ReadonlyArray<{
+    key: string;
+    conflicts: (value: unknown) => boolean;
+}>;
+/**
+ * Resolve the `viewport: null` ⇄ emulation conflict that Playwright rejects.
+ *
+ * An explicit `viewport: null` (no fixed viewport, for responsive testing) is
+ * incompatible with `deviceScaleFactor` / `isMobile: true` — `browser.newContext`
+ * and `launchPersistentContext` THROW on the combination. `viewport: null` is the
+ * more specific, intentional per-test signal, so we honor it and drop the
+ * incompatible emulation options (e.g. a project sets `deviceScaleFactor: 2`
+ * globally and a single test wants a responsive `viewport: null`).
+ *
+ * Mutates `options` in place; returns the names of the keys that were dropped
+ * (so the caller can warn). A no-op unless `options.viewport === null`.
+ */
+declare function dropViewportIncompatibleOptions(options: Record<string, unknown>): string[];
+/**
+ * Merge the project-level `use: { ... }` with the per-test context options
+ * Playwright resolved for THIS test.
+ *
+ * Why this is needed: the Shiplight `context` fixture overrides Playwright's
+ * built-in `context` fixture and builds context options from
+ * `testInfo.project.use`. That object only carries the PROJECT-level `use:`
+ * block — it does NOT contain a per-test `test.use({ ... })` (which is exactly
+ * what the transpiled YAML `use:` block emits). When the project sets a context
+ * option (e.g. `viewport: 1280x720`), it pre-seeds that key, and Playwright's
+ * fill-missing merge (`runBeforeCreateBrowserContext`, which only fills keys NOT
+ * already present) can then never apply the per-test value. Options the project
+ * did NOT set got filled from the per-test values, so they appeared to work —
+ * only project-set keys (viewport, in the typical config) were silently dropped.
+ *
+ * `resolved` holds the values of Playwright's standard context-option fixtures
+ * (viewport, colorScheme, locale, isMobile, ...). Those honor the full override
+ * chain (file-level test.use() > project use: > defaults), so applying them over
+ * the project use restores the documented precedence for every context option.
+ * Keys resolved to `undefined` are skipped so we never inject options the test
+ * never asked for.
+ *
+ * Finally, `dropViewportIncompatibleOptions` resolves the `viewport: null` ⇄
+ * emulation conflict that Playwright would otherwise throw on.
+ */
+declare function mergeResolvedContextOptions(projectUse: Record<string, unknown>, resolved: Record<string, unknown>): Record<string, unknown>;
 /**
  * TestContext — Proxy-backed object for reading/writing runtime variables.
  * Supports property-style access: testContext.myVar = 'value' / const v = testContext.myVar
@@ -118,4 +188,4 @@ type ShiplightFixtures = {
 };
 declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & ShiplightFixtures, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
 
-export { type AuthSpec, SDK_ENV_ALLOWLIST, type TestContext, applyVarsOverride, buildSdkEnv, createTestContext, isDeclaredSensitive, parseVarsOverrideEnv, resolveAuthState, test };
+export { type AuthSpec, EXCLUDED_CONTEXT_OPTION_KEYS, HANDLED_CONTEXT_OPTION_KEYS, SDK_ENV_ALLOWLIST, type TestContext, VIEWPORT_INCOMPATIBLE_OPTIONS, applyVarsOverride, buildSdkEnv, createTestContext, dropViewportIncompatibleOptions, isDeclaredSensitive, mergeResolvedContextOptions, parseVarsOverrideEnv, resolveAuthState, test };