@serenity-js/playwright 3.42.1 → 3.43.0

package/src/screenplay/models/PlaywrightBrowsingSessionWithElectron.ts

@@ -0,0 +1,129 @@
+import { CorrelationId } from '@serenity-js/core/model';
+import type { BrowserCapabilities } from '@serenity-js/web';
+import type * as playwright from 'playwright-core';
+
+import type { ExtraBrowserContextOptions } from '../../ExtraBrowserContextOptions.js';
+import { PlaywrightBrowsingSession } from './PlaywrightBrowsingSession.js';
+import { PlaywrightPage } from './PlaywrightPage.js';
+
+/**
+ * Playwright-specific implementation of [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/)
+ * for Electron applications.
+ *
+ * Use this class when you have an already-launched `ElectronApplication` instance,
+ * typically in Playwright Test scenarios where the app is managed per-worker.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { _electron as electron } from 'playwright';
+ * import { actorCalled } from '@serenity-js/core';
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright';
+ *
+ * const electronApp = await electron.launch({ args: ['main.js'] });
+ *
+ * const actor = actorCalled('Tester').whoCan(
+ *     BrowseTheWebWithPlaywright.usingElectronApp(electronApp)
+ * );
+ *
+ * // After tests, close the app manually
+ * await electronApp.close();
+ * ```
+ *
+ * @group Models
+ */
+export class PlaywrightBrowsingSessionWithElectron extends PlaywrightBrowsingSession {
+
+    constructor(
+        protected electronApp: playwright.ElectronApplication,
+        extraBrowserContextOptions: Partial<ExtraBrowserContextOptions>,
+        selectors: playwright.Selectors,
+    ) {
+        super(extraBrowserContextOptions, selectors);
+    }
+
+    protected override async createBrowserContext(): Promise<playwright.BrowserContext> {
+        return this.electronApp.context();
+    }
+
+    protected override async registerCurrentPage(): Promise<PlaywrightPage> {
+        // Ensure browser context is initialized before accessing windows
+        await this.browserContext();
+        const windows = this.electronApp.windows();
+
+        let targetPage: playwright.Page;
+
+        if (windows.length === 0) {
+            // Wait for the first window to open
+            targetPage = await this.electronApp.firstWindow();
+        }
+        else {
+            // Use the last opened window
+            targetPage = windows.at(-1)!;
+        }
+
+        // Check if this window is already registered
+        const allPages = await this.allPages();
+        for (const page of allPages) {
+            const nativePage = await page.nativePage();
+            if (nativePage === targetPage) {
+                return page;
+            }
+        }
+
+        // Create and register a new PlaywrightPage
+        const playwrightPage = new PlaywrightPage(
+            this,
+            targetPage,
+            this.extraBrowserContextOptions,
+            CorrelationId.create()
+        );
+
+        this.register(playwrightPage);
+
+        // Set up close handler for automatic deregistration
+        targetPage.on('close', () => {
+            this.deregister(playwrightPage.id);
+        });
+
+        return playwrightPage;
+    }
+
+    /**
+     * Closes all Electron windows but does NOT close the Electron application itself.
+     * The application lifecycle is managed externally.
+     */
+    override async closeAllPages(): Promise<void> {
+        const pages = await this.allPages();
+        for (const page of pages) {
+            await page.close();
+        }
+    }
+
+    /**
+     * Returns [basic meta-data](https://serenity-js.org/api/web/interface/BrowserCapabilities/) about the Electron application.
+     *
+     * **Please note** that since Playwright does not expose information about the operating system
+     * the tests are running on, **Serenity/JS assumes that the tests are running locally**
+     * and therefore returns the value of Node.js `process.platform` for `platformName`.
+     */
+    override async browserCapabilities(): Promise<BrowserCapabilities> {
+        return {
+            browserName: 'electron',
+            platformName: process.platform,
+            browserVersion: await this.getElectronVersion(),
+        };
+    }
+
+    private async getElectronVersion(): Promise<string> {
+        try {
+            const version = await this.electronApp.evaluate(
+                () => process.versions.electron
+            );
+            return version || 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+}

package/src/screenplay/models/PlaywrightBrowsingSessionWithPage.ts

@@ -56,4 +56,8 @@ export class PlaywrightBrowsingSessionWithPage extends PlaywrightBrowsingSession
             browserVersion: browser.version()
         }
     }
+
+    async discard(): Promise<void> {
+        await this.closeAllPages();
+    }
 }

package/src/screenplay/models/SelfLaunchingPlaywrightBrowsingSessionWithElectron.ts

@@ -0,0 +1,85 @@
+import type { Discardable, Initialisable } from '@serenity-js/core';
+import * as playwright from 'playwright-core';
+
+import type { ExtraBrowserContextOptions } from '../../ExtraBrowserContextOptions.js';
+import type { ElectronLaunchOptions } from './ElectronLaunchOptions.js';
+import { PlaywrightBrowsingSessionWithElectron } from './PlaywrightBrowsingSessionWithElectron.js';
+
+/**
+ * Self-launching implementation of [`PlaywrightBrowsingSession`](https://serenity-js.org/api/playwright/class/PlaywrightBrowsingSession/)
+ * for Electron applications.
+ *
+ * This class launches the Electron application on first use and closes it when discarded.
+ * Use this for test runners like Mocha or Jasmine that don't manage Electron lifecycle.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core';
+ * import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright';
+ *
+ * const actor = actorCalled('Tester').whoCan(
+ *     BrowseTheWebWithPlaywright.launchingElectronApp({
+ *         args: ['path/to/main.js'],
+ *         cwd: 'path/to/app',
+ *     })
+ * );
+ *
+ * // The app is automatically closed when the actor is dismissed
+ * ```
+ *
+ * @group Models
+ */
+export class SelfLaunchingPlaywrightBrowsingSessionWithElectron
+    extends PlaywrightBrowsingSessionWithElectron
+    implements Initialisable, Discardable
+{
+    constructor(
+        private readonly launchOptions: ElectronLaunchOptions,
+        extraBrowserContextOptions: Partial<ExtraBrowserContextOptions>,
+        selectors: playwright.Selectors,
+    ) {
+        // setting electronApp to undefined since it's lazily initialised
+        super(undefined, extraBrowserContextOptions, selectors);
+    }
+
+    /**
+     * Launches the Electron application using the configured launch options.
+     *
+     * This method is idempotent - calling it multiple times will only launch
+     * the application once.
+     */
+    async initialise(): Promise<void> {
+        if (this.electronApp) {
+            return;
+        }
+
+        this.electronApp = await playwright._electron.launch(this.launchOptions);
+        this.currentBrowserPage = await this.registerCurrentPage();
+    }
+
+    /**
+     * Returns `true` if the Electron application has been launched.
+     */
+    isInitialised(): boolean {
+        return this.electronApp !== undefined;
+    }
+
+    /**
+     * Closes the Electron application that was launched by this session.
+     * Called when the ability is discarded.
+     */
+    async closeElectronApp(): Promise<void> {
+        if (this.electronApp) {
+            await this.electronApp.close();
+            this.electronApp = undefined;
+        }
+    }
+
+    async discard(): Promise<void> {
+        await this.closeElectronApp();
+
+        this.pages.clear();
+        this.currentBrowserPage = undefined;
+    }
+}

package/src/screenplay/models/index.ts

@@ -1,7 +1,10 @@
+export * from './ElectronLaunchOptions.js';
 export * from './locators/index.js';
 export * from './PlaywrightBrowsingSession.js';
 export * from './PlaywrightBrowsingSessionWithBrowser.js';
+export * from './PlaywrightBrowsingSessionWithElectron.js';
 export * from './PlaywrightBrowsingSessionWithPage.js';
 export * from './PlaywrightCookie.js';
 export * from './PlaywrightPage.js';
 export * from './PlaywrightPageElement.js';
+export * from './SelfLaunchingPlaywrightBrowsingSessionWithElectron.js';