Skip to main content

externalSelfLaunchingPlaywrightBrowsingSessionWithElectron

Self-launching implementation of 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

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

Hierarchy

Implements

Index

Constructors

Methods

Constructors

externalconstructor

  • new SelfLaunchingPlaywrightBrowsingSessionWithElectron(launchOptions: { acceptDownloads?: boolean; args?: string[]; artifactsDir?: string; bypassCSP?: boolean; chromiumSandbox?: boolean; colorScheme?: light | dark | no-preference; cwd?: string; env?: {}; executablePath?: string; extraHTTPHeaders?: {}; geolocation?: { latitude: number; longitude: number; accuracy?: number }; httpCredentials?: { username: string; password: string; origin?: string; send?: unauthorized | always }; ignoreHTTPSErrors?: boolean; locale?: string; offline?: boolean; recordHar?: { omitContent?: boolean; content?: omit | embed | attach; path: string; mode?: full | minimal; urlFilter?: string | RegExp }; recordVideo?: { dir?: string; size?: { width: number; height: number }; showActions?: { duration?: number; position?: top-left | top | top-right | bottom-left | bottom | bottom-right; fontSize?: number } }; timeout?: number; timezoneId?: string; tracesDir?: string }, extraBrowserContextOptions: Partial<ExtraBrowserContextOptions>, selectors: Selectors): SelfLaunchingPlaywrightBrowsingSessionWithElectron

  • Parameters

    • externallaunchOptions: { acceptDownloads?: boolean; args?: string[]; artifactsDir?: string; bypassCSP?: boolean; chromiumSandbox?: boolean; colorScheme?: light | dark | no-preference; cwd?: string; env?: {}; executablePath?: string; extraHTTPHeaders?: {}; geolocation?: { latitude: number; longitude: number; accuracy?: number }; httpCredentials?: { username: string; password: string; origin?: string; send?: unauthorized | always }; ignoreHTTPSErrors?: boolean; locale?: string; offline?: boolean; recordHar?: { omitContent?: boolean; content?: omit | embed | attach; path: string; mode?: full | minimal; urlFilter?: string | RegExp }; recordVideo?: { dir?: string; size?: { width: number; height: number }; showActions?: { duration?: number; position?: top-left | top | top-right | bottom-left | bottom | bottom-right; fontSize?: number } }; timeout?: number; timezoneId?: string; tracesDir?: string }
      • externaloptionalacceptDownloads: boolean

        Whether to automatically download all the attachments. Defaults to true where all the downloads are accepted.

      • externaloptionalargs: string[]

        Additional arguments to pass to the application when launching. You typically pass the main script name here.

      • externaloptionalartifactsDir: string

        If specified, artifacts (traces, videos, downloads, HAR files, etc.) are saved into this directory. The directory is not cleaned up when the browser closes. If not specified, a temporary directory is used and cleaned up when the browser closes.

      • externaloptionalbypassCSP: boolean

        Toggles bypassing page's Content-Security-Policy. Defaults to false.

      • externaloptionalchromiumSandbox: boolean

        Enable Chromium sandboxing. Defaults to false.

      • externaloptionalcolorScheme: light | dark | no-preference

        Emulates prefers-colors-scheme media feature, supported values are 'light' and 'dark'. See page.emulateMedia([options]) for more details. Passing null resets emulation to system defaults. Defaults to 'light'.

      • externaloptionalcwd: string

        Current working directory to launch application from.

      • externaloptionalenv: {}

        Specifies environment variables that will be visible to Electron. Defaults to process.env.

      • externaloptionalexecutablePath: string

        Launches given Electron application. If not specified, launches the default Electron executable installed in this package, located at node_modules/.bin/electron.

      • externaloptionalextraHTTPHeaders: {}

        An object containing additional HTTP headers to be sent with every request. Defaults to none.

      • externaloptionalgeolocation: { latitude: number; longitude: number; accuracy?: number }
      • externaloptionalhttpCredentials: { username: string; password: string; origin?: string; send?: unauthorized | always }

        Credentials for HTTP authentication. If no origin is specified, the username and password are sent to any servers upon unauthorized responses.

      • externaloptionalignoreHTTPSErrors: boolean

        Whether to ignore HTTPS errors when sending network requests. Defaults to false.

      • externaloptionallocale: string

        Specify user locale, for example en-GB, de-DE, etc. Locale will affect navigator.language value, Accept-Language request header value as well as number and date formatting rules. Defaults to the system default locale. Learn more about emulation in our emulation guide.

      • externaloptionaloffline: boolean

        Whether to emulate network being offline. Defaults to false. Learn more about network emulation.

      • externaloptionalrecordHar: { omitContent?: boolean; content?: omit | embed | attach; path: string; mode?: full | minimal; urlFilter?: string | RegExp }

        Enables HAR recording for all pages into recordHar.path file. If not specified, the HAR is not recorded. Make sure to await browserContext.close([options]) for the HAR to be saved.

      • externaloptionalrecordVideo: { dir?: string; size?: { width: number; height: number }; showActions?: { duration?: number; position?: top-left | top | top-right | bottom-left | bottom | bottom-right; fontSize?: number } }

        Enables video recording for all pages into recordVideo.dir directory. If not specified videos are not recorded. Make sure to await browserContext.close([options]) for videos to be saved.

      • externaloptionaltimeout: number

        Maximum time in milliseconds to wait for the application to start. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.

      • externaloptionaltimezoneId: string

        Changes the timezone of the context. See ICU's metaZones.txt for a list of supported timezone IDs. Defaults to the system timezone.

      • externaloptionaltracesDir: string

        If specified, traces are saved into this directory.

    • externalextraBrowserContextOptions: Partial<ExtraBrowserContextOptions>
    • externalselectors: Selectors

    Returns SelfLaunchingPlaywrightBrowsingSessionWithElectron

Methods

externalcookie

  • cookie(name: string): Promise<Cookie>

  • Parameters

    • externalname: string

    Returns Promise<Cookie>

externalsetCookie

  • Parameters

    Returns Promise<void>

externaldeleteAllCookies

  • deleteAllCookies(): Promise<void>

  • Returns Promise<void>

externalcloseAllPages

  • closeAllPages(): Promise<void>

  • Closes all Electron windows but does NOT close the Electron application itself. The application lifecycle is managed externally.

    Returns Promise<void>

externalbrowserCapabilities

  • Returns basic meta-data 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.

    Returns Promise<BrowserCapabilities>

externalinitialise

  • initialise(): Promise<void>

  • Launches the Electron application using the configured launch options.

    This method is idempotent - calling it multiple times will only launch the application once.

    Returns Promise<void>

externalisInitialised

  • isInitialised(): boolean

  • Returns true if the Electron application has been launched.

    Returns boolean

externalcloseElectronApp

  • closeElectronApp(): Promise<void>

  • Closes the Electron application that was launched by this session. Called when the ability is discarded.

    Returns Promise<void>

externaldiscard

  • discard(): Promise<void>

  • Returns Promise<void>

externalclosePagesOtherThan

  • Parameters

    Returns Promise<void>

externalcurrentPage

  • Returns a Page representing the currently active top-level browsing context.

    Returns Promise<PlaywrightPage>

externalregister

  • Registers specified pages to be managed by this BrowsingSession.

    Parameters

    Returns void

externalderegister

  • deregister(...pageIds: CorrelationId[]): void

  • Informs this BrowsingSession that it should no longer manage pages identified by the given pageIds.

    Parameters

    • externalrest...pageIds: CorrelationId[]

    Returns void

externalallPages

  • Returns a pages representing all the available top-level browsing context, e.g. all the open browser tabs.

    Returns Promise<PlaywrightPage[]>

externalregisteredPageIds

  • registeredPageIds(): CorrelationId[]

  • Returns the ids of any pages this BrowsingSession is aware of.

    Returns CorrelationId[]

externalchangeCurrentPageTo

  • Informs the BrowsingSession that the "current page" has changed to page.

    Please note that different Web integration tools have a different definition of what a "current page" is. For example, Selenium or WebdriverIO use a single "focused" window that a developer needs to explicitly "switch to" in their tests in order to interact with it. This is similar to how a regular user would interact with Web pages; switching from one tab to another, but not interacting with more than one window/tab simultaneously.

    Playwright and Puppeteer, on the other hand, don't have a concept of the "current" page at all, since they allow the developer to interact with multiple open tabs/windows at the same time.

    Web integration-specific implementations of this class should override this method to define how the concept of the "current page" should be interpreted by Serenity/JS.

    Parameters

    Returns Promise<void>

Page Options