Skip to content

Accept launch options as an array in BrowserBuilder::launch() #192

Open

Description

@aik099

Problem

Launch options reach Node only through BrowserBuilder setters (withHeadless(), withSlowMo(), withChannel(), withProxy(), withDownloadsPath(), withArgs(), withInspector()). Options without a setter can't be used at all, although the bridge already passes every launch option to browserType.launch() unchanged. Currently missing:

  • firefoxUserPrefs
  • ignoreDefaultArgs
  • env (only PWDEBUG via withInspector())
  • chromiumSandbox
  • timeout
  • tracesDir, artifactsDir
  • handleSIGINT / handleSIGTERM / handleSIGHUP

Each new option currently needs its own setter, often a PlaywrightConfig property and PlaywrightClient wiring too (as in #121, and #191 for executablePath), so users wait for a release for options Playwright already supports.

The official clients accept every option: Python's browser_type.launch() keyword arguments, Java's BrowserType.LaunchOptions and .NET's BrowserTypeLaunchOptions cover all of them, generated from the upstream API description.

Proposed API

$browser = $playwright->firefox()
    ->withHeadless(false)
    ->launch([
        'firefoxUserPrefs' => ['browser.tabs.warnOnClose' => false],
        'timeout' => 60000,
    ]);

launch(array $options = []) would merge $options over the options set by the setters before sending them, so the setters keep working and launch() without arguments behaves as today.

This is the signature BrowserTypeInterface::launch() already declares. BrowserBuilder matches that interface's connect() and connectOverCDP() exactly, so together with name() (and later launchPersistentContext()) it could implement BrowserTypeInterface, which currently has no implementation.

Alternatives considered

  • A setter per option: what the library does today; it never catches up with upstream.
  • A generic withOption(string $name, mixed $value) setter: works too, but doesn't match the upstream API or BrowserTypeInterface.
  • PlaywrightConfig properties: needed for fromEnv(), not for passing options directly.

Open questions: should the array or the setters win on conflicts (I'd say the array, as it's more explicit), and should unknown keys be rejected or passed through like args?

I'm happy to send a PR once the direction is agreed.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions