feat: replace Puppeteer with Playwright

Playwright offers better auto-waiting, a more intuitive locator-based API, and built-in debugging tools like trace viewer and inspector.
Puppeteer's auto-download of Chrome via postinstall scripts poses security risks.

Key changes:
- Add "sf browserforce playwright" wrapper command
- Use locators instead of selectors and eliminate evaluate() calls
- Leverage "await using" for automatic page cleanup
- Enable trace capture via BROWSERFORCE_TRACE
- Increase viewport to 1280x1536 to reduce scrolling
- Re-enable Slack and UserAccessPolicies tests

Huge kudos to @itkevin for initiating this migration and providing documentation!

Closes #706
Co-authored-by: Kevin Lindecke <kevin@lindecke.co>

BREAKING CHANGE: Puppeteer has been replaced with Playwright.

Browsers are no longer installed automatically.
Install a browser explicitly:

```shell
sf browserforce playwright -- install chromium
```

Or configure an existing browser via any of these environment variables:

```shell
BROWSERFORCE_BROWSER_CHANNEL="chrome"
BROWSERFORCE_BROWSER_EXECUTABLE_PATH="/usr/bin/google-chrome"
CHROME_BIN="/usr/bin/google-chrome"
```

Author: amtrack

.github/workflows/default.yml

@@ -29,7 +29,6 @@ jobs:
         run: |
           npm ci --ignore-scripts
           npm install --ignore-scripts --global @salesforce/cli@${SF_CLI_VERSION:-"latest"}
-          npx puppeteer browsers install chrome
       - name: Run unit tests
         run: npm run test
       - name: Check formatting
@@ -46,6 +45,15 @@ jobs:
         if: always()
         run: |
           sf org delete scratch --no-prompt
+      - name: Upload Playwright traces
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: playwright-traces
+          path: trace-*.zip
+          compression-level: 0
+          if-no-files-found: ignore
+          retention-days: 14
   release:
     needs: test
     if: ${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/next' }}

.gitignore

@@ -14,3 +14,6 @@ coverage/
 .vscode/settings.json
 
 /oclif.manifest.json
+
+# Playwright traces
+trace-*.zip

CONTRIBUTING.md

@@ -21,6 +21,7 @@
 
 ```shell
 npm ci
+npx playwright install chromium
 ```
 
 ## Scaffolding a new plugin
@@ -31,7 +32,7 @@ Please note that this is only an example. In fact this is supported in the Metad
 You can scaffold a new plugin by running:
 
 ```shell
-npm run generate:plugin --name AdminsCanLogInAsAnyUser
+npm run generate:plugin -- --name AdminsCanLogInAsAnyUser
 ```
 
 Bravo 👏, you have just generated a working browserforce plugin!
@@ -56,8 +57,8 @@ npm run develop
 and now we can run it:
 
 ```shell
-BROWSER_DEBUG=true ./bin/run browserforce apply -f src/plugins/admins-can-log-in-as-any-user/enable.json
-BROWSER_DEBUG=true ./bin/run browserforce apply -f src/plugins/admins-can-log-in-as-any-user/disable.json
+BROWSERFORCE_HEADLESS=false ./bin/run browserforce apply -f src/plugins/admins-can-log-in-as-any-user/enable.json
+BROWSERFORCE_HEADLESS=false ./bin/run browserforce apply -f src/plugins/admins-can-log-in-as-any-user/disable.json
 ```
 
 > [!TIP]
@@ -133,8 +134,8 @@ This allows to run multiple actions (from multiple plugins) using a single confi
 
 Plugins are written in [Typescript](https://www.typescriptlang.org), just like `sf` and most of the available sf plugins.
 
-[Puppeteer](https://pptr.dev) is being used as a library for browser automation.
-If you need more inspiration regarding Puppeteer, checkout [this curated list](https://github.com/transitive-bullshit/awesome-puppeteer) of awesome Puppeteer resources.
+[Playwright](https://playwright.dev) is being used as a library for browser automation.
+If you need more inspiration regarding Playwright, checkout the [official documentation](https://playwright.dev/docs/intro) and our [best practices guide](./docs/PLAYWRIGHT.md).
 
 The simplified browserforce plugin lifecycle can be described as follows
 
@@ -196,3 +197,41 @@ for i in {1..7}; do npm run test:e2e -- -g "AdminsCanLogInAsAnyUser"; done
 ## Debugging
 
 The [Salesforce CLI Plug-In Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_plugins.meta/sfdx_cli_plugins/cli_plugins_debug.htm) describes debugging sfdx plugins using VS Code very well.
+
+### Playwright Debugging and Tracing
+
+When developing or debugging Playwright-based plugins, you have several tools at your disposal:
+
+#### Visual Debugging
+
+To see the browser while tests run:
+
+```bash
+BROWSERFORCE_HEADLESS=false npm run test:e2e -- --grep "YourPlugin"
+```
+
+To slow down execution for better observation (value in milliseconds):
+
+```bash
+BROWSERFORCE_SLOWMO=1000 npm run test:e2e -- --grep "YourPlugin"
+```
+
+#### Playwright Tracing
+
+Playwright tracing captures detailed information about test execution including screenshots, DOM snapshots, network activity, and console logs. This is invaluable for debugging test failures.
+
+To generate a trace for a specific test:
+
+```bash
+BROWSERFORCE_TRACE=true npm run test:e2e -- --grep "YourPlugin"
+```
+
+After the test completes, a trace file will be saved with a timestamp (e.g., `trace-2025-11-23T19-00-00-000Z.zip`).
+
+To view the trace:
+
+```bash
+npx playwright show-trace trace-2025-11-23T19-00-00-000Z.zip
+```
+
+This opens an interactive viewer in your browser where you can step through each action, view screenshots and DOM snapshots, inspect network requests, and review console logs.

README.md

@@ -1,9 +1,12 @@
 # sfdx-browserforce-plugin
 
-> sfdx plugin to apply settings in the Salesforce Setup Menu using browser automation
+> sf plugin to apply settings in the Salesforce Setup Menu using browser automation
 
 [![Actions Status](https://github.com/amtrack/sfdx-browserforce-plugin/actions/workflows/default.yml/badge.svg?branch=main)](https://github.com/amtrack/sfdx-browserforce-plugin/actions?query=branch:main)
 
+> [!NOTE]
+> Since v6 we're using Playwright instead of Puppeteer. Please see the [release notes](https://github.com/amtrack/sfdx-browserforce-plugin/releases) for migration instructions.
+
 ✅ Most settings in the Salesforce Setup Menu are represented as [Settings](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_settings.htm) in the Metadata API.
 
 For example, the highlighted checkbox "Show View Hierarchy link on account pages" in Account Settings is indeed represented in the Metadata `AccountSettings` as `showViewHierarchyLink`.
@@ -54,7 +57,7 @@ $ sf browserforce apply -f ./config/currency.json --target-org myOrg@example.com
 
 - 🔧 configuration using JSON Schema (similar to the [Scratch Org Definition Configuration](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_def_file.htm))
 - 🧠 idempotency of the `apply` command only applies what's necessary and allows re-execution (concept similar to [terraform](https://www.terraform.io/docs/commands/apply.html))
-- 🏎️ browser automation powered by Puppeteer and "Chrome for Testing", [learn more about Puppeteer and Browserforce](#puppeteer)
+- 🏎️ browser automation powered by Playwright, [learn more about Playwright and Browserforce](#playwright)
 
 ## Supported Browserforce Settings
 
@@ -77,79 +80,165 @@ But there's more:
 
 ## Installation
 
-There are several different methods to install `sfdx-browserforce-plugin`:
-
 ```shell
-# as an sf plugin globally
 sf plugins install sfdx-browserforce-plugin
+```
 
-# or standalone globally
-npm install --global sfdx-browserforce-plugin
+> [!IMPORTANT]
+> Playwright does not come with a browser automatically
 
-# or standalone locally (as a dependency in your Node.js project)
-npm install --save-dev sfdx-browserforce-plugin
-```
+You might need to install a browser explicitly or configure Browserforce to use an existing browser.
 
-## Usage
+> [!TIP]
+> If you're using Browserforce on GitHub Actions with the `ubuntu-latest` (v24) Docker image, we can use the preinstalled Google Chrome automatically.
+> No further configuration and installation needed, because the `CHROME_BIN` environment variable is already set.
 
-Depending on your choice of installation, you can find the `browserforce` namespace:
+### Option 1: Install a browser using our Playwright wrapper command
 
 ```shell
-# globally in the sf cli
-sf browserforce
+sf browserforce playwright -- install chromium
+```
+
+> [!IMPORTANT]
+> The two hyphens `--` are intentional and separate the sf command from the arguments to be passed to the playwright executable.
+
+### Option 2: Configure Browserforce to use an existing browser
 
-# globally in the sfdx-browserforce-plugin executable
-sfdx-browserforce-plugin browserforce
+You can use any of the following environment variables:
 
-# locally in the sfdx-browserforce-plugin executable (npx is awesome!)
-npx sfdx-browserforce-plugin browserforce
+```shell
+BROWSERFORCE_BROWSER_CHANNEL="chrome"
+BROWSERFORCE_BROWSER_CHANNEL="chromium"
+BROWSERFORCE_BROWSER_EXECUTABLE_PATH="/usr/bin/google-chrome"
+CHROME_BIN="/usr/bin/google-chrome"
 ```
 
-```console
-$ sfdx-browserforce browserforce -h
-browser automation
+## Usage
 
+<!-- commands -->
+* [`sf browserforce apply`](#sf-browserforce-apply)
+* [`sf browserforce playwright`](#sf-browserforce-playwright)
+
+## `sf browserforce apply`
+
+apply a plan from a config file
+
+```
 USAGE
-  $ sfdx-browserforce-plugin browserforce COMMAND
+  $ sf browserforce apply -o <value> [--json] [--flags-dir <value>] [-f <value>] [-d] [--headless] [--slow-mo <value>]
+    [--timeout <value>] [--trace] [--browser-executable-path <value>] [--browser-channel <value>] [--max-retries
+    <value>] [--retry-timeout <value>]
+
+FLAGS
+  -d, --dry-run                 [env: BROWSERFORCE_DRY_RUN] dry run
+  -f, --definitionfile=<value>  path to a browserforce config file
+  -o, --target-org=<value>      (required) Username or alias of the target org. Not required if the `target-org`
+                                configuration variable is already set.
+
+BROWSER CONFIGURATION FLAGS
+  --browser-channel=<value>          [env: BROWSERFORCE_BROWSER_CHANNEL] the channel (e.g. chromium or chrome) to use
+  --browser-executable-path=<value>  [env: BROWSERFORCE_BROWSER_EXECUTABLE_PATH] the path to a browser executable
+  --[no-]headless                    [env: BROWSERFORCE_HEADLESS] run in headless mode (default: true)
+  --slow-mo=<value>                  [env: BROWSERFORCE_SLOWMO] slow motion in milliseconds (default: 0)
+  --timeout=<value>                  [default: 90000, env: BROWSERFORCE_NAVIGATION_TIMEOUT_MS] the default navigation
+                                     timeout in milliseconds
+  --trace                            [env: BROWSERFORCE_TRACE] create a Playwright trace file
+
+GLOBAL FLAGS
+  --flags-dir=<value>  Import flag values from a directory.
+  --json               Format output as json.
+
+RETRY CONFIGURATION FLAGS
+  --max-retries=<value>    [default: 6, env: BROWSERFORCE_RETRY_MAX_RETRIES] the maximum number of retries for retryable
+                           actions
+  --retry-timeout=<value>  [default: 4000, env: BROWSERFORCE_RETRY_TIMEOUT_MS] the inital timeout in milliseconds for
+                           retryable actions (exponentially increased)
+
+DESCRIPTION
+  apply a plan from a config file
+
+EXAMPLES
+  $ sf browserforce apply -f ./config/currency.json --target-org myOrg@example.com
+    logging in... done
+    Applying config file ./config/currency.json to org myOrg@example.com
+    [CompanyInformation] retrieving state... done
+    [CompanyInformation] changing 'defaultCurrencyIsoCode' to '"English (South Africa) - ZAR"'... done
+    logging out... done
+  
+
+FLAG DESCRIPTIONS
+  -d, --dry-run  dry run
+
+    Retrieve the config and show the diff, but don't apply it.
 
-COMMANDS
-  browserforce apply  apply a plan from a definition file
-  browserforce plan   retrieve state and generate plan file
+  --browser-channel=<value>  the channel (e.g. chromium or chrome) to use
+
+    Playwright will try to figure out the path to the browser executable automatically.
+
+  --browser-executable-path=<value>  the path to a browser executable
+
+    Note: The environment variable CHROME_BIN can also be used. On GitHub Actions with ubuntu-latest, CHROME_BIN is set
+    to /usr/bin/google-chrome.
+
+  --trace  create a Playwright trace file
+
+    The trace file can be viewed with "sf browserforce playwright -- show-trace trace-<date>.zip".
 ```
 
-Both the `browserforce apply` and `browserforce plan` commands expect a config file and a target username or alias for the org.
+_See code: [src/commands/browserforce/apply.ts](https://github.com/amtrack/sfdx-browserforce-plugin/blob/v0.0.0-development/src/commands/browserforce/apply.ts)_
 
-## Environment Variables
+## `sf browserforce playwright`
 
-- `BROWSER_DEBUG` run in non-headless mode (default: `false`)
-- `BROWSERFORCE_NAVIGATION_TIMEOUT_MS`: adjustable for slow internet connections (default: `90000`)
-- `BROWSERFORCE_RETRY_MAX_RETRIES`: number of retries on failures opening a page (default: `4`)
-- `BROWSERFORCE_RETRY_TIMEOUT_MS`: initial time between retries in exponential mode (default: `4000`)
+access the Playwright CLI
 
-## Puppeteer
+```
+USAGE
+  $ sf browserforce playwright
 
-We use [Puppeteer](https://github.com/puppeteer/puppeteer) for browser automation which comes with its own "Chrome for Testing" browser.
+DESCRIPTION
+  access the Playwright CLI
 
-The puppeteer [installation doc](https://github.com/puppeteer/puppeteer#installation) describes how this works:
+EXAMPLES
+  $ sf browserforce playwright -- --help
 
-> When you install Puppeteer, it automatically downloads a recent version of
-> [Chrome for Testing](https://goo.gle/chrome-for-testing) (~170MB macOS, ~282MB Linux, ~280MB Windows) that is [guaranteed to
-> work](https://pptr.dev/faq#q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy)
-> with Puppeteer. The browser is downloaded to the `$HOME/.cache/puppeteer` folder
-> by default (starting with Puppeteer v19.0.0).
+  $ sf browserforce playwright -- --version
 
-In most of the cases this just works! If you still want to skip the download and use another browser installation, you can do this as follows:
+  $ sf browserforce playwright -- install --list
 
-```console
-export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
-sf plugins install sfdx-browserforce-plugin
-export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
-sf browserforce:apply ...
+  $ sf browserforce playwright -- install chromium
+```
+
+_See code: [src/commands/browserforce/playwright.ts](https://github.com/amtrack/sfdx-browserforce-plugin/blob/v0.0.0-development/src/commands/browserforce/playwright.ts)_
+<!-- commandsstop -->
+
+## Playwright
+
+We use [Playwright](https://playwright.dev/) for browser automation.
+
+For more information on browser automation best practices, see the [Playwright documentation](./docs/PLAYWRIGHT.md).
+
+## Alternative Installation
+
+You can also install the `sfdx-browserforce-plugin` NPM package without `sf`. The package exports a `sfdx-browserforce-plugin` executable:
+
+Example:
+
+```shell
+npm install --save-dev sfdx-browserforce-plugin
+npx sfdx-browserforce-plugin browserforce -h
 ```
 
 ## Troubleshooting
 
-- The installation is triggered via the `postinstall` hook of npm/yarn. If you've disabled running scripts with npm (`--ignore-scripts` or via config file), it will not download the browser.
+If no browser is installed or launching fails, you'll get an error message from Playwright with a suggestion.
+
+Typically this will guide you to install a browser.
+If you've installed sfdx-browserforce-plugin using `sf`, you can replace the following:
+
+```diff
+- npx playwright install chromium
++ sf browserforce playwright -- install chromium
+```
 
 ## Contributing
 

_templates/plugin/new/index.e2e-spec.ejs.t

@@ -7,7 +7,7 @@ import { type Config, <%= h.changeCase.pascalCase(name) %> } from './index.js';
 describe(<%= h.changeCase.pascalCase(name) %>.name, function() {
   let plugin: <%= h.changeCase.pascalCase(name) %>;
   before(() => {
-    plugin = new <%= h.changeCase.pascalCase(name) %>(global.bf);
+    plugin = new <%= h.changeCase.pascalCase(name) %>(global.browserforce);
   });
 
   const configEnabled: Config = {