@molecule/app-e2e-playwright 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,26 @@
+# @molecule/app-e2e-playwright
+
+Real Playwright browsers for the e2e bond — the user's machine and CI
+
+## Type
+
+`provider`
+
+## Implements
+
+`@molecule/app-e2e`
+
+## Injection Notes
+
+### Requirements
+
+- None
+
+### Post-Injection Steps
+
+- Run `npm install` to install dependencies
+- Run `npm run build` to compile
+
+### Known Limitations
+
+- None yet

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * E2E bond that opens real Playwright browsers. Inside a molecule sandbox the
+ * same specs drive the live preview through `@molecule/app-e2e-preview`; on
+ * your own machine and in CI this bond gives them Chromium, Firefox or WebKit
+ * with everything Playwright offers — screenshots, traces, videos, network
+ * interception.
+ *
+ * When the test runner picks the `playwright` provider, `@molecule/app-e2e`'s
+ * `test` IS Playwright's `test`, so this bond is only reached by scripts that
+ * call `connect()` themselves (a measurement script, a smoke check outside the
+ * runner). Under `npx playwright test`, Playwright's own fixtures launch the
+ * browser as usual.
+ *
+ * @example
+ * ```ts
+ * // e2e/bonds.ts (scaffolded)
+ * import { resolveE2EProviderName, setProvider } from '@molecule/app-e2e'
+ * import { provider as playwright } from '@molecule/app-e2e-playwright'
+ * import { provider as preview } from '@molecule/app-e2e-preview'
+ *
+ * setProvider(resolveE2EProviderName() === 'preview' ? preview : playwright)
+ *
+ * // a script
+ * import { connectPlaywright } from '@molecule/app-e2e-playwright'
+ * const page = await connectPlaywright({ baseURL: 'http://localhost:3000', viewport: { width: 390, height: 844 } })
+ * await page.goto('/')
+ * await page.screenshot({ path: 'home-phone.png' })
+ * await page.close() // closes the context and the browser too
+ * ```
+ *
+ * @remarks
+ * - Browsers are installed once with `npx playwright install chromium`
+ *   (`@playwright/test` never downloads them on `npm install`). The launch
+ *   error says so when they are missing.
+ * - `MOL_E2E_BROWSER=firefox|webkit` picks the engine; `MOL_E2E_HEADED=1`
+ *   shows the window.
+ * - Do not use this bond inside a molecule sandbox: there is no browser there
+ *   by design, and the preview bond is the one that works.
+ *
+ * @module
+ */
+export { connectPlaywright, provider } from './provider.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC3D,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,44 @@
+/**
+ * E2E bond that opens real Playwright browsers. Inside a molecule sandbox the
+ * same specs drive the live preview through `@molecule/app-e2e-preview`; on
+ * your own machine and in CI this bond gives them Chromium, Firefox or WebKit
+ * with everything Playwright offers — screenshots, traces, videos, network
+ * interception.
+ *
+ * When the test runner picks the `playwright` provider, `@molecule/app-e2e`'s
+ * `test` IS Playwright's `test`, so this bond is only reached by scripts that
+ * call `connect()` themselves (a measurement script, a smoke check outside the
+ * runner). Under `npx playwright test`, Playwright's own fixtures launch the
+ * browser as usual.
+ *
+ * @example
+ * ```ts
+ * // e2e/bonds.ts (scaffolded)
+ * import { resolveE2EProviderName, setProvider } from '@molecule/app-e2e'
+ * import { provider as playwright } from '@molecule/app-e2e-playwright'
+ * import { provider as preview } from '@molecule/app-e2e-preview'
+ *
+ * setProvider(resolveE2EProviderName() === 'preview' ? preview : playwright)
+ *
+ * // a script
+ * import { connectPlaywright } from '@molecule/app-e2e-playwright'
+ * const page = await connectPlaywright({ baseURL: 'http://localhost:3000', viewport: { width: 390, height: 844 } })
+ * await page.goto('/')
+ * await page.screenshot({ path: 'home-phone.png' })
+ * await page.close() // closes the context and the browser too
+ * ```
+ *
+ * @remarks
+ * - Browsers are installed once with `npx playwright install chromium`
+ *   (`@playwright/test` never downloads them on `npm install`). The launch
+ *   error says so when they are missing.
+ * - `MOL_E2E_BROWSER=firefox|webkit` picks the engine; `MOL_E2E_HEADED=1`
+ *   shows the window.
+ * - Do not use this bond inside a molecule sandbox: there is no browser there
+ *   by design, and the preview bond is the one that works.
+ *
+ * @module
+ */
+export { connectPlaywright, provider } from './provider.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC3D,cAAc,YAAY,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The bond: launches a real browser and returns its `Page`. Closing that page
+ * also closes the context and the browser opened for it.
+ *
+ * @module
+ */
+import { type Page } from '@playwright/test';
+import type { E2EProvider } from '@molecule/app-e2e';
+import type { PlaywrightConnectOptions } from './types.js';
+/** The bond: `setProvider(provider)` in your `e2e/bonds.ts`. */
+export declare const provider: E2EProvider;
+/** Open a real browser page from any script. */
+export declare const connectPlaywright: (options?: PlaywrightConnectOptions) => Promise<Page>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAqB,KAAK,IAAI,EAAU,MAAM,kBAAkB,CAAA;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,KAAK,EAAyB,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAcjF,gEAAgE;AAChE,eAAO,MAAM,QAAQ,EAAE,WAgCtB,CAAA;AAED,gDAAgD;AAChD,eAAO,MAAM,iBAAiB,GAAI,UAAS,wBAA6B,KAAG,OAAO,CAAC,IAAI,CAC5D,CAAA"}

package/dist/provider.js

@@ -0,0 +1,54 @@
+/**
+ * The bond: launches a real browser and returns its `Page`. Closing that page
+ * also closes the context and the browser opened for it.
+ *
+ * @module
+ */
+import process from 'node:process';
+import { chromium, firefox, webkit } from '@playwright/test';
+const BROWSERS = { chromium, firefox, webkit };
+const browserName = (options) => {
+    const name = options.browser ??
+        process.env['MOL_E2E_BROWSER'] ??
+        'chromium';
+    if (!(name in BROWSERS))
+        throw new Error(`unknown browser "${name}" — use chromium, firefox or webkit`);
+    return name;
+};
+/** The bond: `setProvider(provider)` in your `e2e/bonds.ts`. */
+export const provider = {
+    name: 'playwright',
+    async connect(options = {}) {
+        const headless = !(options.headed ?? process.env['MOL_E2E_HEADED'] === '1');
+        let browser;
+        try {
+            browser = await BROWSERS[browserName(options)].launch({ headless, ...options.launchOptions });
+        }
+        catch (error) {
+            const message = String(error.message ?? error);
+            if (/Executable doesn't exist|browserType\.launch/.test(message)) {
+                throw new Error(`${message}\n\nInstall the browsers once with: npx playwright install ${browserName(options)}\n(inside a molecule sandbox use @molecule/app-e2e-preview instead — it drives the live preview and needs no browser).`, { cause: error });
+            }
+            throw error;
+        }
+        const context = await browser.newContext({
+            ...(options.baseURL ? { baseURL: options.baseURL } : {}),
+            ...(options.viewport === undefined ? {} : { viewport: options.viewport }),
+        });
+        if (options.timeout)
+            context.setDefaultTimeout(options.timeout);
+        if (options.navigationTimeout)
+            context.setDefaultNavigationTimeout(options.navigationTimeout);
+        const page = await context.newPage();
+        const closePage = page.close.bind(page);
+        page.close = async (closeOptions) => {
+            await closePage(closeOptions).catch(() => undefined);
+            await context.close().catch(() => undefined);
+            await browser.close().catch(() => undefined);
+        };
+        return page;
+    },
+};
+/** Open a real browser page from any script. */
+export const connectPlaywright = (options = {}) => provider.connect(options);
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Options for opening a real Playwright browser through the bond.
+ *
+ * @module
+ */
+import type { LaunchOptions } from '@playwright/test';
+import type { E2EConnectOptions } from '@molecule/app-e2e';
+/** Which Playwright browser to launch. */
+export type PlaywrightBrowserName = 'chromium' | 'firefox' | 'webkit';
+/** Options for `provider.connect()` beyond the core's. */
+export interface PlaywrightConnectOptions extends E2EConnectOptions {
+    /** Browser to launch; default `chromium` (also `MOL_E2E_BROWSER`). */
+    browser?: PlaywrightBrowserName;
+    /** Show the browser window; default headless (also `MOL_E2E_HEADED=1`). */
+    headed?: boolean;
+    /** Extra launch options passed through to Playwright. */
+    launchOptions?: LaunchOptions;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE1D,0CAA0C;AAC1C,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAA;AAErE,0DAA0D;AAC1D,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE,sEAAsE;IACtE,OAAO,CAAC,EAAE,qBAAqB,CAAA;IAC/B,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,yDAAyD;IACzD,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Options for opening a real Playwright browser through the bond.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@molecule/app-e2e-playwright",
+  "version": "1.0.0",
+  "description": "E2E bond that opens real Playwright browsers — the same specs that drive the live preview inside a molecule sandbox run here on your machine and in CI, with screenshots, traces and network interception.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "molecule",
+    "e2e",
+    "playwright",
+    "browser"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/app/bonds/e2e/playwright"
+  },
+  "homepage": "https://molecule.dev",
+  "bugs": {
+    "url": "https://github.com/molecule-dev/molecule/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@molecule/app-bond": "^1.0.1",
+    "@molecule/app-e2e": "^1.0.0",
+    "@playwright/test": "^1.40.0"
+  },
+  "devDependencies": {
+    "@molecule/app-bond": "1.0.1",
+    "@molecule/app-e2e": "1.0.0",
+    "@playwright/test": "1.62.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  }
+}