playwright-core, Puppeteer and puppeteer-core are optional peers. Install one to use it instead.
Every function has a snake_case alias for code shared with the Python package: launch_context, launch_persistent_context, launch_process, ensure_binary, binary_info, discover_binary, discovery_report, clear_cache, load_catalogue, ensure_widevine and provision_widevine. translateOptions is an alias of toCanonicalLaunchConfig.
Launching
Every launch function resolves the options, looks up the locale and timezone of the connection’s exit, finds or downloads the browser, and starts it. They share the launch options.launch
Browser. Under Patchright or Playwright, it is Playwright’s Browser with pages in a normal profile. The browser runs on a temporary profile that the driver deletes when the browser closes or the process exits. Under Puppeteer, it is Puppeteer’s Browser, whose newPage() already uses the normal profile.
Under Patchright and Playwright these members differ from Playwright’s:
Under every driver the result has three extra properties:
launch() refuses userDataDir with ProfileResolutionError (code APOSTATE_USER_DATA_DIR_ON_LAUNCH). Use launchPersistentContext() to keep a profile.
The declared return type is any, because the package cannot name both drivers’ types. Annotate the call site:
launchPersistentContext
userDataDir if it does not exist and launches on it. Under Patchright and Playwright it returns the BrowserContext bound to the directory. Under Puppeteer it returns the Browser. The first launch stores a seed in userDataDir/apostate/identity, and every later launch without fingerprint presents the same machine. Seeds and identity has the details.
The result carries apostateDriverName, apostateExecutablePath and apostateDiagnostics. A userDataDir in options that names another directory throws TypeError.
launchContext
defaultBrowserContext(). It is a normal profile, not off-the-record. Closing it closes the browser. apostateBrowser holds the browser it came from.
launchProcess
--remote-debugging-port.
It takes cwd, stdio (default "ignore") and env for the child process, and passes --user-data-dir itself when userDataDir is set. It gives the browser a Widevine CDM first, as the other launch functions do. With headless: false on a Linux host with no display, it starts Xvfb and stops it when the browser exits.
From 0.4.4 it passes --no-first-run and --no-default-browser-check. In 0.4.3, add them to args for a headed launch on a new user data directory, or the browser can stop at a first-run dialog.
ApostateProcess
isConnected() is true until the process exits or close() is called. close() sends SIGTERM, waits up to 5 seconds, then sends SIGKILL.
Launch options
LaunchOptions is one object shared by every launch function. Several options have aliases, listed after the name.
Under Patchright and Playwright the package always passes
viewport: null, so the window sets the viewport. From 0.4.4 it also passes colorScheme: null, so a page reads the persona’s own prefers-color-scheme. In 0.4.3 Playwright emulates light. Call page.emulateMedia({ colorScheme: null }) there. See prefers-color-scheme in the 0.4.3 packages. From 0.4.4 it passes chromiumSandbox: true where the sandbox can start (macOS, Windows, and Linux as a regular user outside a container, with no seccomp filter and with user namespaces allowed), and a chromiumSandbox you pass is kept. Elsewhere Playwright passes --no-sandbox, and a headed first tab shows a 56-pixel bar for it. See A bar on the first tab. Other Playwright or Puppeteer launch options are not passed through.
humanize: true throws UnsupportedFeatureError.
A failed GeoIP lookup does not throw. It prints a warning starting with [Apostate], adds it to apostateDiagnostics.warnings, and sends no switch for the field it could not fill, so the persona uses en-US and the host’s timezone there. Errors shows the text.
Refused switches
These inargs throw ProfileResolutionError before anything is downloaded:
driverInfo
DRIVERS
The drivers the package can launch with, in preference order: ["patchright", "playwright", "playwright-core", "puppeteer", "puppeteer-core"].
Binary management
The launch functions call these for you. Installation explains the cache, discovery and verification.ensureBinary
binaryPath. It looks in this order, and downloads only when nothing answers:
executablePathorbinaryPath, thenAPOSTATE_BINARY, taken as given. A path that holds no browser throwsMissingBinaryError.- This package’s own install in the cache, when its record still matches the executable’s SHA-256.
- The well-known locations:
/Applicationsand~/Applicationson macOS,~/.cache/apostateand/opt/apostateon Linux,%LOCALAPPDATA%\apostateon Windows. A browser found there is used only when an Apostate build record or catalogue sits beside it and it reports Chromium 152.0.7977.83. - The release archive, downloaded, checked against the manifest’s SHA-256 before it is opened, and extracted into the cache.
APOSTATE_KEEP_ARCHIVEkeeps the verified archive.
force: true to reinstall even when a browser is found.
binaryInfo
apostate info prints. It never throws for a missing release.
discoverBinary
null. It resolves to an object, not a path:
discoveryReport
order, searched, found and rejected. Each entry of rejected has a path and a reason, such as no Apostate payload beside it (build/MANIFEST.lock or resources/profiles/catalogue.json) for a stock Chromium or reports Chromium <version>, not 152.0.7977.83 for another build.
clearCache
cacheDir. With target, it deletes only that target’s install for this Chromium version. With version, it deletes only that Chromium version’s directory.
verifyArtifact
archive (bytes, an ArrayBuffer or an async iterable of bytes) and throws BinaryIntegrityError unless it matches artifact.sha256.
expectedArtifactName
apostate-152.0.7977.83-linux-x64.tar.zst. It is exported but not declared in index.d.ts.
extractionFailureMessage
BinaryExtractionError carries when tar cannot read the archive. It is exported for the package’s tests and not declared in index.d.ts.
targetForHost
platform and arch, by default this host’s. Throws UnsupportedPlatformError for a host with no build, such as an Intel Mac.
normalizeTarget
UnsupportedPlatformError for any name that is not one of the four targets.
Profiles
The browser composes the machine from the seed. These functions check options and profiles, and report which path a launch takes. How it works explains composition.resolveProfile
source is native-composed for a seed or persona, host-inherited for host mode, and explicit-profile or explicit-file for a profile you wrote. platform is the persona the launch presents.
resolveLaunchConfig
locale, timezone and webrtc_ip filled in.
toCanonicalLaunchConfig
translateOptions.
validateProfile
config/profile.schema.json and returns a copy. Throws ProfileResolutionError with the first problem, such as profile.cpu.cores is not part of the schema.
loadCatalogue
path, and returns its shape: catalogue_version, profile_schema_version, browser_build, model, anchors (the GPU families, each with id, platform, backend, members and rotation_status), axes and policies.
normalizePersona
windows, macos, linux or null, and maps the aliases. Throws ProfileResolutionError for anything else.
hostPersona
windows, macos, linux, or null on another OS. This is not the persona a default launch presents on Linux.
defaultPersonaForHost
fingerprintPlatform presents: macos for macos, windows for windows and for linux. An unknown token is returned unchanged.
DEFAULT_PERSONA_BY_HOST
The frozen object defaultPersonaForHost() uses: { macos: "macos", windows: "windows", linux: "windows" }.
redactProxy
socks5://user:pass@proxy.example:1080 gives socks5://proxy.example:1080.
stableStringify
--apostate-profile in.
Widevine
The browser ships without the Widevine CDM. A launch copies one from a local Google Chrome, or downloads it from Google’s component update service and checks its SHA-256, then keeps it in the cache directory it shares with the Python package. Widevine explains when you need this.ensureWidevine
executable a CDM if it has none, and resolves to the browser’s CDM directory. On Linux it also writes the CDM’s location into userDataDir. It resolves to null when executable is not inside an Apostate install or no CDM could be had, and never rejects.
provisionWidevine
WidevineError when none can be had. source is a WidevineCdm directory, with or without a version directory inside. platform_verified is false for windows-x64, where Widevine has not been tried. The Node CLI has no command for this. The Python CLI has apostate provision-drm.
Constants
Errors
Every error the package throws for its own reasons is anApostateError with a code string and a details object. From 0.4.4 messages never contain a proxy credential. In 0.4.3 a BrowserLaunchError can echo the --apostate-profile value, which holds the credential base64-encoded. Invalid option types, such as a proxy that is not a URL, throw a plain TypeError. From 0.4.4 a timezone that is not an IANA zone name throws a RangeError. Errors lists the common messages and their fixes.
ProfileResolutionError carries a specific code for each refusal: