Interface Electron

Playwright has experimental support for Electron automation. You can access electron namespace via:

const { _electron } = require('playwright');

An example of the Electron automation script would be:

const { _electron: electron } = require('playwright');

(async () => {
  // Launch Electron app.
  const electronApp = await electron.launch({ args: ['main.js'] });

  // Evaluation expression in the Electron context.
  const appPath = await electronApp.evaluate(async ({ app }) => {
    // This runs in the main Electron process, parameter here is always
    // the result of the require('electron') in the main app script.
    return app.getAppPath();
  });
  console.log(appPath);

  // Get the first window that the app opens, wait if necessary.
  const window = await electronApp.firstWindow();
  // Print the title.
  console.log(await window.title());
  // Capture a screenshot.
  await window.screenshot({ path: 'intro.png' });
  // Direct Electron console to Node terminal.
  window.on('console', console.log);
  // Click button.
  await window.click('text=Click me');
  // Exit app.
  await electronApp.close();
})();

Supported Electron versions are:

v12.2.0+
v13.4.0+
v14+

Known issues:

If you are not able to launch Electron and it will end up in timeouts during launch, try the following:

Ensure that nodeCliInspect (FuseV1Options.EnableNodeCliInspectArguments) fuse is not set to false.

Mocking native dialogs:

Playwright does not intercept the native Electron dialog API (dialog.showOpenDialog, dialog.showSaveDialog, dialog.showMessageBox, etc.) because those calls happen in the Electron main process and go straight to OS APIs. Use electronApplication.evaluate(pageFunction[, arg]) to replace the relevant methods in the main process so tests run deterministically without any OS-level UI:

// Stub the open dialog to always return a fixed path.
await electronApp.evaluate(({ dialog }, filePaths) => {
  dialog.showOpenDialog = () => Promise.resolve({ canceled: false, filePaths });
}, ['/path/to/file.txt']);

// Stub the save dialog.
await electronApp.evaluate(({ dialog }, filePath) => {
  dialog.showSaveDialog = () => Promise.resolve({ canceled: false, filePath });
}, '/path/to/saved.txt');

// Stub showMessageBox to click the first button.
await electronApp.evaluate(({ dialog }) => {
  dialog.showMessageBox = () => Promise.resolve({ response: 0, checkboxChecked: false });
});

The replacement persists until the application is closed. Synchronous variants (showOpenDialogSync, showSaveDialogSync, showMessageBoxSync) can be stubbed the same way — just return the value directly instead of a Promise.

interface Electron {
    launch(
        options?: {
            acceptDownloads?: boolean;
            args?: string[];
            artifactsDir?: string;
            bypassCSP?: boolean;
            chromiumSandbox?: boolean;
            colorScheme?: "light" | "dark" | "no-preference" | null;
            cwd?: string;
            env?: { [key: string]: string };
            executablePath?: string;
            extraHTTPHeaders?: { [key: string]: string };
            geolocation?: { accuracy?: number; latitude: number; longitude: number };
            httpCredentials?: {
                origin?: string;
                password: string;
                send?: "always" | "unauthorized";
                username: string;
            };
            ignoreHTTPSErrors?: boolean;
            locale?: string;
            offline?: boolean;
            recordHar?: {
                content?: "embed"
                | "attach"
                | "omit";
                mode?: "full" | "minimal";
                omitContent?: boolean;
                path: string;
                urlFilter?: string | RegExp;
            };
            recordVideo?: {
                dir?: string;
                showActions?: {
                    cursor?: "none"
                    | "pointer";
                    duration?: number;
                    fontSize?: number;
                    position?:
                        | "top-left"
                        | "top"
                        | "top-right"
                        | "bottom-left"
                        | "bottom"
                        | "bottom-right";
                };
                size?: { height: number; width: number };
            };
            timeout?: number;
            timezoneId?: string;
            tracesDir?: string;
        },
    ): Promise<ElectronApplication>;
}

Index

Methods

launch

Methods

launch

launch(
    options?: {
        acceptDownloads?: boolean;
        args?: string[];
        artifactsDir?: string;
        bypassCSP?: boolean;
        chromiumSandbox?: boolean;
        colorScheme?: "light" | "dark" | "no-preference" | null;
        cwd?: string;
        env?: { [key: string]: string };
        executablePath?: string;
        extraHTTPHeaders?: { [key: string]: string };
        geolocation?: { accuracy?: number; latitude: number; longitude: number };
        httpCredentials?: {
            origin?: string;
            password: string;
            send?: "always" | "unauthorized";
            username: string;
        };
        ignoreHTTPSErrors?: boolean;
        locale?: string;
        offline?: boolean;
        recordHar?: {
            content?: "embed"
            | "attach"
            | "omit";
            mode?: "full" | "minimal";
            omitContent?: boolean;
            path: string;
            urlFilter?: string | RegExp;
        };
        recordVideo?: {
            dir?: string;
            showActions?: {
                cursor?: "none"
                | "pointer";
                duration?: number;
                fontSize?: number;
                position?:
                    | "top-left"
                    | "top"
                    | "top-right"
                    | "bottom-left"
                    | "bottom"
                    | "bottom-right";
            };
            size?: { height: number; width: number };
        };
        timeout?: number;
        timezoneId?: string;
        tracesDir?: string;
    },
): Promise<ElectronApplication>
Launches electron application specified with the executablePath.
Parameters
- Optionaloptions: {
      acceptDownloads?: boolean;
      args?: string[];
      artifactsDir?: string;
      bypassCSP?: boolean;
      chromiumSandbox?: boolean;
      colorScheme?: "light" | "dark" | "no-preference" | null;
      cwd?: string;
      env?: { [key: string]: string };
      executablePath?: string;
      extraHTTPHeaders?: { [key: string]: string };
      geolocation?: { accuracy?: number; latitude: number; longitude: number };
      httpCredentials?: {
          origin?: string;
          password: string;
          send?: "always" | "unauthorized";
          username: string;
      };
      ignoreHTTPSErrors?: boolean;
      locale?: string;
      offline?: boolean;
      recordHar?: {
          content?: "embed"
          | "attach"
          | "omit";
          mode?: "full" | "minimal";
          omitContent?: boolean;
          path: string;
          urlFilter?: string | RegExp;
      };
      recordVideo?: {
          dir?: string;
          showActions?: {
              cursor?: "none"
              | "pointer";
              duration?: number;
              fontSize?: number;
              position?:
                  | "top-left"
                  | "top"
                  | "top-right"
                  | "bottom-left"
                  | "bottom"
                  | "bottom-right";
          };
          size?: { height: number; width: number };
      };
      timeout?: number;
      timezoneId?: string;
      tracesDir?: string;
  }
  - OptionalacceptDownloads?: boolean
    
    Whether to automatically download all the attachments. Defaults to true where all the downloads are accepted.
  - Optionalargs?: string[]
    
    Additional arguments to pass to the application when launching. You typically pass the main script name here.
  - OptionalartifactsDir?: 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.
  - OptionalbypassCSP?: boolean
    
    Toggles bypassing page's Content-Security-Policy. Defaults to false.
  - OptionalchromiumSandbox?: boolean
    
    Enable Chromium sandboxing. Defaults to false.
  - OptionalcolorScheme?: "light" | "dark" | "no-preference" | null
    
    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'.
  - Optionalcwd?: string
    
    Current working directory to launch application from.
  - Optionalenv?: { [key: string]: string }
    
    Specifies environment variables that will be visible to Electron. Defaults to process.env.
  - OptionalexecutablePath?: string
    
    Launches given Electron application. If not specified, launches the default Electron executable installed in this package, located at node_modules/.bin/electron.
  - OptionalextraHTTPHeaders?: { [key: string]: string }
    
    An object containing additional HTTP headers to be sent with every request. Defaults to none.
  - Optionalgeolocation?: { accuracy?: number; latitude: number; longitude: number }
    
    Optionalaccuracy?: number
    
    Non-negative accuracy value. Defaults to 0.
    
    latitude: number
    
    Latitude between -90 and 90.
    
    longitude: number
    
    Longitude between -180 and 180.
  - OptionalhttpCredentials?: {
        origin?: string;
        password: string;
        send?: "always" | "unauthorized";
        username: string;
    }
    
    Credentials for HTTP authentication. If no origin is specified, the username and password are sent to any servers upon unauthorized responses.
    
    Optionalorigin?: string
    
    Restrain sending http credentials on specific origin (scheme://host:port).
    
    password: string
    
    Optionalsend?: "always" | "unauthorized"
    
    This option only applies to the requests sent from corresponding APIRequestContext and does not affect requests sent from the browser. 'always' - Authorization header with basic authentication credentials will be sent with the each API request. 'unauthorized - the credentials are only sent when 401 (Unauthorized) response with WWW-Authenticate header is received. Defaults to 'unauthorized'.
    
    username: string
  - OptionalignoreHTTPSErrors?: boolean
    
    Whether to ignore HTTPS errors when sending network requests. Defaults to false.
  - Optionallocale?: 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.
  - Optionaloffline?: boolean
    
    Whether to emulate network being offline. Defaults to false. Learn more about network emulation.
  - OptionalrecordHar?: {
        content?: "embed" | "attach" | "omit";
        mode?: "full" | "minimal";
        omitContent?: boolean;
        path: string;
        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.
    
    Optionalcontent?: "embed" | "attach" | "omit"
    
    Optional setting to control resource content management. If omit is specified, content is not persisted. If attach is specified, resources are persisted as separate files or entries in the ZIP archive. If embed is specified, content is stored inline the HAR file as per HAR specification. Defaults to attach for .zip output files and to embed for all other file extensions.
    
    Optionalmode?: "full" | "minimal"
    
    When set to minimal, only record information necessary for routing from HAR. This omits sizes, timing, page, cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to full.
    
    OptionalomitContent?: boolean
    
    Optional setting to control whether to omit request content from the HAR. Defaults to false. Deprecated, use content policy instead.
    
    path: string
    
    Path on the filesystem to write the HAR file to. If the file name ends with .zip, content: 'attach' is used by default.
    
    OptionalurlFilter?: string | RegExp
    
    A glob or regex pattern to filter requests that are stored in the HAR. When a baseURL via the context options was provided and the passed URL is a path, it gets merged via the new URL() constructor. Defaults to none.
  - OptionalrecordVideo?: {
        dir?: string;
        showActions?: {
            cursor?: "none" | "pointer";
            duration?: number;
            fontSize?: number;
            position?:
                | "top-left"
                | "top"
                | "top-right"
                | "bottom-left"
                | "bottom"
                | "bottom-right";
        };
        size?: { height: number; width: 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.
    
    Optionaldir?: string
    
    Path to the directory to put videos into. If not specified, the videos will be stored in artifactsDir (see browserType.launch([options]) options).
    
    OptionalshowActions?: {
        cursor?: "none" | "pointer";
        duration?: number;
        fontSize?: number;
        position?:
            | "top-left"
            | "top"
            | "top-right"
            | "bottom-left"
            | "bottom"
            | "bottom-right";
    }
    
    If specified, enables visual annotations on interacted elements during video recording.
    
    Optionalcursor?: "none" | "pointer"
    
    Cursor decoration shown for pointer actions. "pointer" (the default) renders a mouse pointer that animates from the previous action point to the next one. "none" disables the cursor decoration.
    
    Optionalduration?: number
    
    How long each annotation is displayed in milliseconds. Defaults to 500.
    
    OptionalfontSize?: number
    
    Font size of the action title in pixels. Defaults to 24.
    
    Optionalposition?: "top-left" | "top" | "top-right" | "bottom-left" | "bottom" | "bottom-right"
    
    Position of the action title overlay. Defaults to "top-right".
    
    Optionalsize?: { height: number; width: number }
    
    Optional dimensions of the recorded videos. If not specified the size will be equal to viewport scaled down to fit into 800x800. If viewport is not configured explicitly the video size defaults to 800x450. Actual picture of each page will be scaled down if necessary to fit the specified size.
    
    height: number
    
    Video frame height.
    
    width: number
    
    Video frame width.
  - Optionaltimeout?: number
    
    Maximum time in milliseconds to wait for the application to start. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
  - OptionaltimezoneId?: string
    
    Changes the timezone of the context. See ICU's metaZones.txt for a list of supported timezone IDs. Defaults to the system timezone.
  - OptionaltracesDir?: string
    
    If specified, traces are saved into this directory.
Returns Promise<ElectronApplication>
- Defined in node_modules/.pnpm/playwright-core@1.62.1/node_modules/playwright-core/types/types.d.ts:23474

Interface Electron

Index

Methods

Methods

launch

Parameters

OptionalacceptDownloads?: boolean

Optionalargs?: string[]

OptionalartifactsDir?: string

OptionalbypassCSP?: boolean

OptionalchromiumSandbox?: boolean

OptionalcolorScheme?: "light" | "dark" | "no-preference" | null

Optionalcwd?: string

Optionalenv?: { [key: string]: string }

OptionalexecutablePath?: string

OptionalextraHTTPHeaders?: { [key: string]: string }

Optionalgeolocation?: { accuracy?: number; latitude: number; longitude: number }

Optionalaccuracy?: number

latitude: number

longitude: number

OptionalhttpCredentials?: { origin?: string; password: string; send?: "always" | "unauthorized"; username: string;}

Optionalorigin?: string

password: string

Optionalsend?: "always" | "unauthorized"

username: string

OptionalignoreHTTPSErrors?: boolean

Optionallocale?: string

Optionaloffline?: boolean

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

Optionalcontent?: "embed" | "attach" | "omit"

Optionalmode?: "full" | "minimal"

OptionalomitContent?: boolean

path: string

OptionalurlFilter?: string | RegExp

OptionalrecordVideo?: { dir?: string; showActions?: { cursor?: "none" | "pointer"; duration?: number; fontSize?: number; position?: | "top-left" | "top" | "top-right" | "bottom-left" | "bottom" | "bottom-right"; }; size?: { height: number; width: number };}

Optionaldir?: string

OptionalshowActions?: { cursor?: "none" | "pointer"; duration?: number; fontSize?: number; position?: | "top-left" | "top" | "top-right" | "bottom-left" | "bottom" | "bottom-right";}

Optionalcursor?: "none" | "pointer"

Optionalduration?: number

OptionalfontSize?: number

Optionalposition?: "top-left" | "top" | "top-right" | "bottom-left" | "bottom" | "bottom-right"

Optionalsize?: { height: number; width: number }

height: number

width: number

Optionaltimeout?: number

OptionaltimezoneId?: string

OptionaltracesDir?: string

Returns Promise<ElectronApplication>

Settings

On This Page

`Optional`acceptDownloads?: boolean

`Optional`args?: string[]

`Optional`artifactsDir?: string

`Optional`bypassCSP?: boolean

`Optional`chromiumSandbox?: boolean

`Optional`colorScheme?: "light" | "dark" | "no-preference" | null

`Optional`cwd?: string

`Optional`env?: { [key: string]: string }

`Optional`executablePath?: string

`Optional`extraHTTPHeaders?: { [key: string]: string }

`Optional`geolocation?: { accuracy?: number; latitude: number; longitude: number }

`Optional`accuracy?: number

`Optional`httpCredentials?: {
origin?: string;
password: string;
send?: "always" | "unauthorized";
username: string;
}

`Optional`origin?: string

`Optional`send?: "always" | "unauthorized"

`Optional`ignoreHTTPSErrors?: boolean

`Optional`locale?: string

`Optional`offline?: boolean

`Optional`recordHar?: {
content?: "embed" | "attach" | "omit";
mode?: "full" | "minimal";
omitContent?: boolean;
path: string;
urlFilter?: string | RegExp;
}

`Optional`content?: "embed" | "attach" | "omit"

`Optional`mode?: "full" | "minimal"

`Optional`omitContent?: boolean

`Optional`urlFilter?: string | RegExp

`Optional`recordVideo?: {
dir?: string;
showActions?: {
cursor?: "none" | "pointer";
duration?: number;
fontSize?: number;
position?:
| "top-left"
| "top"
| "top-right"
| "bottom-left"
| "bottom"
| "bottom-right";
};
size?: { height: number; width: number };
}

`Optional`dir?: string

`Optional`showActions?: {
cursor?: "none" | "pointer";
duration?: number;
fontSize?: number;
position?:
| "top-left"
| "top"
| "top-right"
| "bottom-left"
| "bottom"
| "bottom-right";
}

`Optional`cursor?: "none" | "pointer"

`Optional`duration?: number

`Optional`fontSize?: number

`Optional`position?: "top-left" | "top" | "top-right" | "bottom-left" | "bottom" | "bottom-right"

`Optional`size?: { height: number; width: number }

`Optional`timeout?: number

`Optional`timezoneId?: string

`Optional`tracesDir?: string