docs: update some docs

Author: amtrack

CONTRIBUTING.md

@@ -16,9 +16,10 @@
 
 2. Install dependencies
 
-> Note: Make sure to run these commands in your `sfdx-browserforce-plugin` directory.
+> [!NOTE]
+> Make sure to run these commands in your `sfdx-browserforce-plugin` directory.
 
-```console
+```shell
 npm ci
 ```
 
@@ -29,44 +30,58 @@ Please note that this is only an example. In fact this is supported in the Metad
 
 You can scaffold a new plugin by running:
 
-```console
+```shell
 npm run generate:plugin --name AdminsCanLogInAsAnyUser
 ```
 
-Run `git status` afterwards to see what files have been generated.
-
-Want to see it in action?
+Bravo 👏, you have just generated a working browserforce plugin!
 
 ## Building
 
 TypeScript code needs to be transpiled to JavaScript.
 To do this, run the following command:
 
-```console
+```shell
 npm run build
 ```
 
-Bravo 👏, you have just generated a working browserforce plugin!
+Want to see it in action?
 
-Create a scratch org and try it yourself:
+Let's create a Scratch Org
 
-```console
-sf org create scratch -f config/project-scratch-def.json -a browserforce-dev -d
-BROWSER_DEBUG=true ./bin/run browserforce apply -f src/plugins/admins-can-log-in-as-any-user/enable.json -o browserforce-dev
-BROWSER_DEBUG=true ./bin/run browserforce apply -f src/plugins/admins-can-log-in-as-any-user/disable.json -o browserforce-dev
+```shell
+npm run develop
 ```
 
-Now it's your turn!
+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
+```
+
+> [!TIP]
+> Instead of manually running these commands while developing, we will run the E2E tests instead:
+
+```shell
+npm run test:e2e -- -g "AdminsCanLogInAsAnyUser"
+  AdminsCanLogInAsAnyUser
+    ✔ should enable
+    ✔ should already be enabled
+    ✔ should disable
+    ✔ should already be disabled
+  4 passing (6s)
+```
 
 ## Developing plugins
 
 For the following, we assume that your scaffolded plugin lives in `src/plugins/admins-can-log-in-as-any-user`.
 
-```console
+```shell
 $ tree src/plugins/admins-can-log-in-as-any-user
 src/plugins/admins-can-log-in-as-any-user
-├── disable.json        <-- example config file for e2e test
-├── enable.json         <-- example config file for e2e test
+├── disable.json        <-- example config file for manual testing
+├── enable.json         <-- example config file for manual testing
 ├── index.e2e-spec.ts   <-- end-to-end test
 ├── index.ts            <-- implementation
 └── schema.json         <-- schema for configuration
@@ -149,32 +164,35 @@ The execution will apply as few changes as necessary and so you will be able to
 Both the result of the `retrieve` function and the argument of the `apply` function are objects in the format defined in your `schema.json`.
 In this example, you would return `{enabled: boolean}` as part of `retrieve`, and expect `{enabled: boolean}` as argument in `apply`.
 
-## 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.
-
 ## Testing
 
 To run **unit tests**:
 
-> Note: Make sure to run these commands in your sfdx-browserforce-plugin directory.
+> [!NOTE]
+> Make sure to run these commands in your sfdx-browserforce-plugin directory.
 
-```console
+```shell
 npm run test
 ```
 
-To run the **end to end tests**, you might want to create a new **default scratch org** first.
+To run **end to end tests**:
 
-> Note: Your default scratch org will be used in the tests!
+> [!CAUTION]
+> Your default scratch org will be used in the E2E tests!
 
-```console
-sf org create scratch -f config/project-scratch-def.json -d
+```shell
+npm run test:e2e -- -g "AdminsCanLogInAsAnyUser" # will only run tests matching `AdminsCanLogInAsAnyUser`
 ```
 
-```console
-npm run test:e2e
-npm run test:e2e -- -g "AdminsCanLogInAsAnyUser" # will only run tests matching `AdminsCanLogInAsAnyUser`
+> [!IMPORTANT]
+> E2E tests should be implemented to be **re-runnable**.
+>
+> Please run the test at least 7 times to reduce the risk of a flaky implementation:
+
+```shell
+for i in {1..7}; do npm run test:e2e -- -g "AdminsCanLogInAsAnyUser"; done
 ```
 
-> Note: You can run the e2e tests in non-headless mode (opening a browser) by setting the environment variable `BROWSER_DEBUG=true`.
-> Note: You can also slow down the e2e test in non-headless mode by setting the environmnet variable, where the number is milliseconds of delay `BROWSER_SLOWMO=250`.
+## 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.

README.md

@@ -24,7 +24,7 @@ For example, the Currency Locale in `Setup -> Company Settings -> Company Inform
 
 👉 This is where Browserforce (sfdx-browserforce-plugin) comes to the rescue. It fills this gap by applying these unsupported settings through browser automation!
 
-# Example
+## Example
 
 To change the Currency Locale, the Browserforce config file (here: `./config/currency.json`) looks like this:
 
@@ -50,13 +50,13 @@ $ sf browserforce apply -f ./config/currency.json --target-org myOrg@example.com
   logging out... done
 ```
 
-# Key Concepts
+## Key Concepts
 
 - 🔧 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)
 
-# Supported Browserforce Settings
+## Supported Browserforce Settings
 
 Top settings:
 
@@ -75,11 +75,11 @@ But there's more:
 - Please see the [Browserforce Settings](https://github.com/amtrack/sfdx-browserforce-plugin/wiki/Browserforce-Settings) wiki page with screenshots.
 - Explore the JSON schema powered configuration using a [full-blown example](https://github.dev/amtrack/sfdx-browserforce-plugin/blob/main/examples/full.json) or start with an [empty configuration](https://github.dev/amtrack/sfdx-browserforce-plugin/blob/main/examples/empty.json).
 
-# Installation
+## Installation
 
 There are several different methods to install `sfdx-browserforce-plugin`:
 
-```console
+```shell
 # as an sf plugin globally
 sf plugins install sfdx-browserforce-plugin
 
@@ -90,11 +90,11 @@ npm install --global sfdx-browserforce-plugin
 npm install --save-dev sfdx-browserforce-plugin
 ```
 
-# Usage
+## Usage
 
 Depending on your choice of installation, you can find the `browserforce` namespace:
 
-```console
+```shell
 # globally in the sf cli
 sf browserforce
 
@@ -119,14 +119,14 @@ COMMANDS
 
 Both the `browserforce apply` and `browserforce plan` commands expect a config file and a target username or alias for the org.
 
-# Environment Variables
+## Environment Variables
 
 - `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`)
 
-# Puppeteer
+## Puppeteer
 
 We use [Puppeteer](https://github.com/puppeteer/puppeteer) for browser automation which comes with its own "Chrome for Testing" browser.
 
@@ -147,19 +147,19 @@ export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
 sf browserforce:apply ...
 ```
 
-Troubleshooting:
+## 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.
 
-# Contributing
+## Contributing
 
 Please see [CONTRIBUTING.md](CONTRIBUTING.md) for getting started.
 
-# Sponsors
+## Sponsors
 
 - [PARX](https://www.parx.com)
 - [IPfolio](https://www.ipfolio.com)
 
-# License
+## License
 
 MIT © [Matthias Rolke](mailto:mr.amtrack@gmail.com)