@serenity-js/playwright 3.42.1 → 3.43.0

package/lib/screenplay/models/PlaywrightBrowsingSessionWithPage.js

@@ -43,6 +43,9 @@ class PlaywrightBrowsingSessionWithPage extends PlaywrightBrowsingSession_js_1.P
             browserVersion: browser.version()
         };
     }
+    async discard() {
+        await this.closeAllPages();
+    }
 }
 exports.PlaywrightBrowsingSessionWithPage = PlaywrightBrowsingSessionWithPage;
 //# sourceMappingURL=PlaywrightBrowsingSessionWithPage.js.map

package/lib/screenplay/models/PlaywrightBrowsingSessionWithPage.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlaywrightBrowsingSessionWithPage.js","sourceRoot":"","sources":["../../../src/screenplay/models/PlaywrightBrowsingSessionWithPage.ts"],"names":[],"mappings":";;;AAAA,mDAAwD;AAKxD,iFAA2E;AAC3E,2DAAqD;AAErD;;GAEG;AACH,MAAa,iCAAkC,SAAQ,wDAAyB;IAIrD;IAHN,uBAAuB,GAAkB,qBAAa,CAAC,MAAM,EAAE,CAAC;IAEjF,YACuB,IAAqB,EACxC,qBAAiD,EACjD,SAA+B;QAE/B,KAAK,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC;QAJrB,SAAI,GAAJ,IAAI,CAAiB;IAK5C,CAAC;IAEkB,KAAK,CAAC,mBAAmB;QACxC,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAE5B,MAAM,cAAc,GAAG,IAAI,kCAAc,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,0BAA0B,EAAE,IAAI,CAAC,uBAAuB,CAAC,CAAC;QAE1H,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAE9B,OAAO,cAAc,CAAC;IAC1B,CAAC;IAEkB,KAAK,CAAC,oBAAoB;QACzC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa;QACf,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,IAAI,CAAE,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,uBAAuB,CAAC,EAAE,CAAC;gBACjD,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;QACL,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,kBAAkB,GAAG,SAAS,CAAC;IACxC,CAAC;IAEQ,KAAK,CAAC,mBAAmB;QAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;QAC9C,OAAO;YACH,WAAW,EAAG,OAAe,CAAC,YAAY,CAAC,IAAI,EAAI,4DAA4D;YAC/G,YAAY,EAAE,OAAO,CAAC,QAAQ,EAAqB,gDAAgD;YACnG,cAAc,EAAE,OAAO,CAAC,OAAO,EAAE;SACpC,CAAA;IACL,CAAC;CACJ;AA/CD,8EA+CC"}
+{"version":3,"file":"PlaywrightBrowsingSessionWithPage.js","sourceRoot":"","sources":["../../../src/screenplay/models/PlaywrightBrowsingSessionWithPage.ts"],"names":[],"mappings":";;;AAAA,mDAAwD;AAKxD,iFAA2E;AAC3E,2DAAqD;AAErD;;GAEG;AACH,MAAa,iCAAkC,SAAQ,wDAAyB;IAIrD;IAHN,uBAAuB,GAAkB,qBAAa,CAAC,MAAM,EAAE,CAAC;IAEjF,YACuB,IAAqB,EACxC,qBAAiD,EACjD,SAA+B;QAE/B,KAAK,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC;QAJrB,SAAI,GAAJ,IAAI,CAAiB;IAK5C,CAAC;IAEkB,KAAK,CAAC,mBAAmB;QACxC,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAE5B,MAAM,cAAc,GAAG,IAAI,kCAAc,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,0BAA0B,EAAE,IAAI,CAAC,uBAAuB,CAAC,CAAC;QAE1H,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAE9B,OAAO,cAAc,CAAC;IAC1B,CAAC;IAEkB,KAAK,CAAC,oBAAoB;QACzC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa;QACf,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,IAAI,CAAE,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,uBAAuB,CAAC,EAAE,CAAC;gBACjD,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;QACL,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,kBAAkB,GAAG,SAAS,CAAC;IACxC,CAAC;IAEQ,KAAK,CAAC,mBAAmB;QAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;QAC9C,OAAO;YACH,WAAW,EAAG,OAAe,CAAC,YAAY,CAAC,IAAI,EAAI,4DAA4D;YAC/G,YAAY,EAAE,OAAO,CAAC,QAAQ,EAAqB,gDAAgD;YACnG,cAAc,EAAE,OAAO,CAAC,OAAO,EAAE;SACpC,CAAA;IACL,CAAC;IAED,KAAK,CAAC,OAAO;QACT,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC;IAC/B,CAAC;CACJ;AAnDD,8EAmDC"}

package/lib/screenplay/models/SelfLaunchingPlaywrightBrowsingSessionWithElectron.d.ts

@@ -0,0 +1,52 @@
+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 declare class SelfLaunchingPlaywrightBrowsingSessionWithElectron extends PlaywrightBrowsingSessionWithElectron implements Initialisable, Discardable {
+    private readonly launchOptions;
+    constructor(launchOptions: ElectronLaunchOptions, extraBrowserContextOptions: Partial<ExtraBrowserContextOptions>, selectors: playwright.Selectors);
+    /**
+     * Launches the Electron application using the configured launch options.
+     *
+     * This method is idempotent - calling it multiple times will only launch
+     * the application once.
+     */
+    initialise(): Promise<void>;
+    /**
+     * Returns `true` if the Electron application has been launched.
+     */
+    isInitialised(): boolean;
+    /**
+     * Closes the Electron application that was launched by this session.
+     * Called when the ability is discarded.
+     */
+    closeElectronApp(): Promise<void>;
+    discard(): Promise<void>;
+}
+//# sourceMappingURL=SelfLaunchingPlaywrightBrowsingSessionWithElectron.d.ts.map

package/lib/screenplay/models/SelfLaunchingPlaywrightBrowsingSessionWithElectron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelfLaunchingPlaywrightBrowsingSessionWithElectron.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/SelfLaunchingPlaywrightBrowsingSessionWithElectron.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAC;AAE9C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACtF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,qCAAqC,EAAE,MAAM,4CAA4C,CAAC;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,kDACT,SAAQ,qCACR,YAAW,aAAa,EAAE,WAAW;IAGjC,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,qBAAqB,EACrD,0BAA0B,EAAE,OAAO,CAAC,0BAA0B,CAAC,EAC/D,SAAS,EAAE,UAAU,CAAC,SAAS;IAMnC;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IASjC;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;;OAGG;IACG,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAMjC"}

package/lib/screenplay/models/SelfLaunchingPlaywrightBrowsingSessionWithElectron.js

@@ -0,0 +1,107 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SelfLaunchingPlaywrightBrowsingSessionWithElectron = void 0;
+const playwright = __importStar(require("playwright-core"));
+const PlaywrightBrowsingSessionWithElectron_js_1 = require("./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
+ */
+class SelfLaunchingPlaywrightBrowsingSessionWithElectron extends PlaywrightBrowsingSessionWithElectron_js_1.PlaywrightBrowsingSessionWithElectron {
+    launchOptions;
+    constructor(launchOptions, extraBrowserContextOptions, selectors) {
+        // setting electronApp to undefined since it's lazily initialised
+        super(undefined, extraBrowserContextOptions, selectors);
+        this.launchOptions = launchOptions;
+    }
+    /**
+     * 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() {
+        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() {
+        return this.electronApp !== undefined;
+    }
+    /**
+     * Closes the Electron application that was launched by this session.
+     * Called when the ability is discarded.
+     */
+    async closeElectronApp() {
+        if (this.electronApp) {
+            await this.electronApp.close();
+            this.electronApp = undefined;
+        }
+    }
+    async discard() {
+        await this.closeElectronApp();
+        this.pages.clear();
+        this.currentBrowserPage = undefined;
+    }
+}
+exports.SelfLaunchingPlaywrightBrowsingSessionWithElectron = SelfLaunchingPlaywrightBrowsingSessionWithElectron;
+//# sourceMappingURL=SelfLaunchingPlaywrightBrowsingSessionWithElectron.js.map

package/lib/screenplay/models/SelfLaunchingPlaywrightBrowsingSessionWithElectron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelfLaunchingPlaywrightBrowsingSessionWithElectron.js","sourceRoot":"","sources":["../../../src/screenplay/models/SelfLaunchingPlaywrightBrowsingSessionWithElectron.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,4DAA8C;AAI9C,yGAAmG;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAa,kDACT,SAAQ,gFAAqC;IAIxB;IADrB,YACqB,aAAoC,EACrD,0BAA+D,EAC/D,SAA+B;QAE/B,iEAAiE;QACjE,KAAK,CAAC,SAAS,EAAE,0BAA0B,EAAE,SAAS,CAAC,CAAC;QALvC,kBAAa,GAAb,aAAa,CAAuB;IAMzD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU;QACZ,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,OAAO;QACX,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACzE,IAAI,CAAC,kBAAkB,GAAG,MAAM,IAAI,CAAC,mBAAmB,EAAE,CAAC;IAC/D,CAAC;IAED;;OAEG;IACH,aAAa;QACT,OAAO,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,gBAAgB;QAClB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YAC/B,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QACjC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO;QACT,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAE9B,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,kBAAkB,GAAG,SAAS,CAAC;IACxC,CAAC;CACJ;AApDD,gHAoDC"}

package/lib/screenplay/models/index.d.ts

@@ -1,8 +1,11 @@
+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';
 //# sourceMappingURL=index.d.ts.map

package/lib/screenplay/models/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,wCAAwC,CAAC;AACvD,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yDAAyD,CAAC"}

package/lib/screenplay/models/index.js

@@ -14,11 +14,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ElectronLaunchOptions.js"), exports);
 __exportStar(require("./locators/index.js"), exports);
 __exportStar(require("./PlaywrightBrowsingSession.js"), exports);
 __exportStar(require("./PlaywrightBrowsingSessionWithBrowser.js"), exports);
+__exportStar(require("./PlaywrightBrowsingSessionWithElectron.js"), exports);
 __exportStar(require("./PlaywrightBrowsingSessionWithPage.js"), exports);
 __exportStar(require("./PlaywrightCookie.js"), exports);
 __exportStar(require("./PlaywrightPage.js"), exports);
 __exportStar(require("./PlaywrightPageElement.js"), exports);
+__exportStar(require("./SelfLaunchingPlaywrightBrowsingSessionWithElectron.js"), exports);
 //# sourceMappingURL=index.js.map

package/lib/screenplay/models/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,iEAA+C;AAC/C,4EAA0D;AAC1D,yEAAuD;AACvD,wDAAsC;AACtC,sDAAoC;AACpC,6DAA2C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6DAA2C;AAC3C,sDAAoC;AACpC,iEAA+C;AAC/C,4EAA0D;AAC1D,6EAA2D;AAC3D,yEAAuD;AACvD,wDAAsC;AACtC,sDAAoC;AACpC,6DAA2C;AAC3C,0FAAwE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-js/playwright",
-  "version": "3.42.1",
+  "version": "3.43.0",
   "description": "Adapter that integrates @serenity-js/web with Playwright, enabling Serenity/JS reporting and using the Screenplay Pattern to write component and end-to-end test scenarios",
   "author": {
     "name": "Jan Molak",
@@ -22,9 +22,14 @@
   "module": "./esm/index.js",
   "exports": {
     ".": {
-      "types": "./esm/index.d.ts",
-      "import": "./esm/index.js",
-      "require": "./lib/index.js"
+      "import": {
+        "types": "./esm/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "require": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      }
     },
     "./lib/*": "./lib/*",
     "./esm/*": "./esm/*",
@@ -54,7 +59,7 @@
   "scripts": {
     "clean": "rimraf target",
     "~test": "c8 npm run test:no-coverage",
-    "~test:no-coverage": "mocha --config ../../.mocharc.yml --spec='spec/**/*.spec.*'",
+    "~test:no-coverage": "mocha --config .mocharc.yml --spec='spec/**/*.spec.*'",
     "compile": "npm run compile:clean && npm run compile:esm && npm run compile:cjs-package && npm run compile:cjs",
     "compile:clean": "rimraf lib esm",
     "compile:esm": "tsc --project tsconfig-esm.build.json",
@@ -73,8 +78,8 @@
     "node": "^20 || ^22 || ^24"
   },
   "dependencies": {
-    "@serenity-js/core": "3.42.1",
-    "@serenity-js/web": "3.42.1",
+    "@serenity-js/core": "3.43.0",
+    "@serenity-js/web": "3.43.0",
     "tiny-types": "2.0.5"
   },
   "peerDependencies": {
@@ -83,13 +88,20 @@
   "devDependencies": {
     "@integration/testing-tools": "3.0.0",
     "@types/chai": "4.3.20",
+    "@types/chai-as-promised": "7.1.8",
     "@types/mocha": "10.0.10",
+    "@types/sinon": "21.0.1",
     "c8": "11.0.0",
+    "chai": "4.5.0",
+    "chai-as-promised": "7.1.2",
     "mocha": "11.7.5",
     "mocha-multi": "1.1.7",
     "playwright-core": "1.59.1",
-    "ts-node": "10.9.2",
+    "sinon": "20.0.0",
+    "sinon-chai": "3.7.0",
+    "tiny-types": "2.0.5",
+    "tsx": "4.20.3",
     "typescript": "5.9.3"
   },
-  "gitHead": "42dc1d09e9c09db93669395939e386162a08be29"
+  "gitHead": "96ffb7ecba111082c92d7b107fef007d9f56bb83"
 }

package/src/screenplay/abilities/BrowseTheWebWithPlaywright.ts

@@ -1,11 +1,14 @@
-import type { Discardable } from '@serenity-js/core';
+import { Discardable, Initialisable } from '@serenity-js/core';
 import { BrowseTheWeb } from '@serenity-js/web';
 import * as playwright from 'playwright-core';
 
 import type { ExtraBrowserContextOptions } from '../../ExtraBrowserContextOptions.js';
 import {
+    type ElectronLaunchOptions,
     PlaywrightBrowsingSessionWithBrowser,
-    PlaywrightBrowsingSessionWithPage
+    PlaywrightBrowsingSessionWithElectron,
+    PlaywrightBrowsingSessionWithPage,
+    SelfLaunchingPlaywrightBrowsingSessionWithElectron
 } from '../models/index.js';
 
 /**
@@ -154,24 +157,126 @@ import {
  *
  * @group Abilities
  */
-export class BrowseTheWebWithPlaywright extends BrowseTheWeb<playwright.Locator> implements Discardable {
-
-    static using(browser: playwright.Browser, browserContextOptions?: playwright.BrowserContextOptions, extraBrowserContextOptions?: ExtraBrowserContextOptions): BrowseTheWebWithPlaywright {
+export class BrowseTheWebWithPlaywright
+    extends BrowseTheWeb<playwright.Locator>
+    implements Initialisable, Discardable
+{
+    static using(
+        browser: playwright.Browser,
+        browserContextOptions?: playwright.BrowserContextOptions,
+        extraBrowserContextOptions?: ExtraBrowserContextOptions
+    ): BrowseTheWebWithPlaywright {
         return new BrowseTheWebWithPlaywright(new PlaywrightBrowsingSessionWithBrowser(browser, browserContextOptions, extraBrowserContextOptions, playwright.selectors));
     }
 
-    static usingPage(page: playwright.Page, extraBrowserContextOptions?: ExtraBrowserContextOptions): BrowseTheWebWithPlaywright {
+    static usingPage(
+        page: playwright.Page,
+        extraBrowserContextOptions?: ExtraBrowserContextOptions
+    ): BrowseTheWebWithPlaywright {
         return new BrowseTheWebWithPlaywright(new PlaywrightBrowsingSessionWithPage(page, extraBrowserContextOptions, playwright.selectors));
     }
 
+    /**
+     * Creates an ability to browse the web using an already-launched Electron application.
+     *
+     * Use this method when the Electron application lifecycle is managed externally,
+     * such as in Playwright Test where the app is launched 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();
+     * ```
+     *
+     * @param electronApp - An already-launched Playwright ElectronApplication instance
+     * @param extraBrowserContextOptions - Optional configuration for timeouts and navigation
+     */
+    static usingElectronApp(
+        electronApp: playwright.ElectronApplication,
+        extraBrowserContextOptions?: ExtraBrowserContextOptions
+    ): BrowseTheWebWithPlaywright {
+        return new BrowseTheWebWithPlaywright(
+            new PlaywrightBrowsingSessionWithElectron(
+                electronApp,
+                extraBrowserContextOptions ?? {},
+                playwright.selectors
+            )
+        );
+    }
+
+    /**
+     * Creates an ability to browse the web by launching and managing an Electron application.
+     *
+     * Use this method when you want Serenity/JS to manage the Electron application lifecycle.
+     * The app is launched on first use and closed when the ability is discarded.
+     *
+     * ## 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
+     * ```
+     *
+     * @param launchOptions - Options for launching the Electron application
+     * @param extraBrowserContextOptions - Optional configuration for timeouts and navigation
+     */
+    static launchingElectronApp(
+        launchOptions: ElectronLaunchOptions,
+        extraBrowserContextOptions?: ExtraBrowserContextOptions
+    ): BrowseTheWebWithPlaywright {
+        return new BrowseTheWebWithPlaywright(
+            new SelfLaunchingPlaywrightBrowsingSessionWithElectron(
+                launchOptions,
+                extraBrowserContextOptions ?? {},
+                playwright.selectors
+            )
+        );
+    }
+
+    async initialise(): Promise<void> {
+        if (Initialisable.isInitialisable(this.session)) {
+            await this.session.initialise();
+        }
+    }
+
+    isInitialised(): boolean {
+        return Initialisable.isInitialisable(this.session)
+            ? this.session.isInitialised()
+            : true;
+    }
+
     /**
      * Automatically closes any open [pages](https://serenity-js.org/api/web/class/Page/) when the [SceneFinishes](https://serenity-js.org/api/core-events/class/SceneFinishes/)
      *
+     * For self-launching Electron sessions, also closes the Electron application.
+     *
      * #### Learn more
      * - [`PlaywrightBrowsingSession.closeAllPages`](https://serenity-js.org/api/playwright/class/PlaywrightBrowsingSession/#closeAllPages)
      * - [`Discardable`](https://serenity-js.org/api/core/interface/Discardable/)
      */
     async discard(): Promise<void> {
-        await this.session.closeAllPages();
+        if (Discardable.isDiscardable(this.session)) {
+            await this.session.discard();
+        }
     }
 }

package/src/screenplay/models/ElectronLaunchOptions.ts

@@ -0,0 +1,55 @@
+import type * as playwright from 'playwright-core';
+
+/**
+ * Options for launching an Electron application via Playwright.
+ *
+ * This type re-exports Playwright's Electron launch options with additional documentation
+ * for commonly used properties.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core';
+ * import { BrowseTheWebWithPlaywright, ElectronLaunchOptions } from '@serenity-js/playwright';
+ *
+ * const options: ElectronLaunchOptions = {
+ *     executablePath: '/path/to/electron',
+ *     args: ['main.js'],
+ *     cwd: '/path/to/app',
+ *     env: { NODE_ENV: 'test' },
+ *     timeout: 30000,
+ * };
+ *
+ * const actor = actorCalled('Tester').whoCan(
+ *     BrowseTheWebWithPlaywright.launchingElectronApp(options)
+ * );
+ * ```
+ *
+ * ## Common Options
+ *
+ * - **executablePath**: Path to the Electron executable. If not specified, uses the default
+ *   Electron installed in `node_modules/.bin/electron`.
+ * - **args**: Command-line arguments passed to the application. Typically includes the path
+ *   to the main script (e.g., `['main.js']`).
+ * - **cwd**: Current working directory for the Electron process.
+ * - **env**: Environment variables visible to the Electron process. Defaults to `process.env`.
+ * - **timeout**: Maximum time in milliseconds to wait for the application to start.
+ *   Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
+ *
+ * ## Additional Options
+ *
+ * - **acceptDownloads**: Whether to automatically download all attachments. Defaults to `true`.
+ * - **bypassCSP**: Toggles bypassing page's Content-Security-Policy. Defaults to `false`.
+ * - **colorScheme**: Emulates `prefers-colors-scheme` media feature. Supported values are `'light'`, `'dark'`, and `'no-preference'`.
+ * - **locale**: Specify user locale, for example `en-GB`, `de-DE`, etc.
+ * - **offline**: Whether to emulate network being offline. Defaults to `false`.
+ * - **recordVideo**: Enables video recording for all pages.
+ * - **timezoneId**: Changes the timezone of the context.
+ *
+ * ## Learn more
+ * - [Playwright Electron API](https://playwright.dev/docs/api/class-electron)
+ * - [Electron Testing with Playwright](https://playwright.dev/docs/electron)
+ *
+ * @group Configuration
+ */
+export type ElectronLaunchOptions = Parameters<typeof playwright._electron.launch>[0];

package/src/screenplay/models/PlaywrightBrowsingSessionWithBrowser.ts

@@ -1,3 +1,4 @@
+import type { Discardable } from '@serenity-js/core';
 import type { BrowserCapabilities } from '@serenity-js/web';
 import type * as playwright from 'playwright-core';
 
@@ -8,7 +9,10 @@ import type { PlaywrightPage } from './PlaywrightPage.js';
 /**
  *  @group Models
  */
-export class PlaywrightBrowsingSessionWithBrowser extends PlaywrightBrowsingSession {
+export class PlaywrightBrowsingSessionWithBrowser
+    extends PlaywrightBrowsingSession
+    implements Discardable
+{
 
     constructor(
         protected readonly browser: playwright.Browser,
@@ -20,6 +24,7 @@ export class PlaywrightBrowsingSessionWithBrowser extends PlaywrightBrowsingSess
     }
 
     protected override async createBrowserContext(): Promise<playwright.BrowserContext> {
+        // todo: move to initialise?
         return this.browser.newContext(this.browserContextOptions);
     }
 
@@ -37,13 +42,6 @@ export class PlaywrightBrowsingSessionWithBrowser extends PlaywrightBrowsingSess
         return allPages.at(-1);
     }
 
-    override async closeAllPages(): Promise<void> {
-        await super.closeAllPages();
-
-        const context = await this.browserContext();
-        await context.close();
-    }
-
     override async browserCapabilities(): Promise<BrowserCapabilities> {
         return {
             browserName: (this.browser as any)._initializer.name,   // todo: raise a PR to Playwright to expose this information
@@ -51,4 +49,11 @@ export class PlaywrightBrowsingSessionWithBrowser extends PlaywrightBrowsingSess
             browserVersion: this.browser.version()
         }
     }
+
+    async discard(): Promise<void> {
+        await this.closeAllPages();
+
+        const context = await this.browserContext();
+        await context.close();
+    }
 }