sfdx plugin for browser automation
Unlike the Scratch Org Definition Configuration which can only be used on the creation of a scratch org (sfdx force:org:create -f config/scratch-def.json
),
the Browserforce Configuration allows to "shape" any org, (e.g. scratch org, sandbox or production org) with similar preferences and unofficial preferences that are not (yet) available in the Scratch Org Definition Configuration or as Metadata (sf browserforce apply -f config/setup-admin-login-as-any.json -u myOrg@example.com
).
Further benefits:
apply
command only applies what's necessary and allows re-execution (concept similar to terraform)There are several different methods to install sfdx-browserforce-plugin
:
# as an sf plugin globally
sf plugins install sfdx-browserforce-plugin
# or standalone globally
npm install --global sfdx-browserforce-plugin
# or standalone locally (as a dependency in your Node.js project)
npm install --save-dev sfdx-browserforce-plugin
Depending on your choice of installation, you can find the browserforce
namespace:
# globally in the sf cli
sf browserforce
# globally in the sfdx-browserforce-plugin executable
sfdx-browserforce-plugin browserforce
# locally in the sfdx-browserforce-plugin executable (npx is awesome!)
npx sfdx-browserforce-plugin browserforce
$ sfdx-browserforce browserforce -h
browser automation
USAGE
$ sfdx-browserforce-plugin browserforce COMMAND
COMMANDS
browserforce apply apply a plan from a definition file
browserforce plan retrieve state and generate plan file
Both the browserforce apply
and browserforce plan
commands expect a config file and a target username or alias for the org.
To enable Setup -> Security Controls -> Login Access Policies -> Administrators Can Log in as Any User
, the config file (here: ./config/setup-admin-login-as-any.json
) should look like this:
{
"$schema": "https://raw.githubusercontent.com/amtrack/sfdx-browserforce-plugin/main/src/plugins/schema.json",
"settings": {
"security": {
"loginAccessPolicies": {
"administratorsCanLogInAsAnyUser": true
}
}
}
}
Tip: If you use Visual Studio Code, you can leverage tab completion to build the config (powered by the JSON Schema).
Next apply the config:
$ sf browserforce apply -f ./config/setup-admin-login-as-any.json --target-org myOrg@example.com
logging in... done
Applying definition file ./config/setup-admin-login-as-any.json to org myOrg@example.com
[Security] retrieving state... done
[Security] changing 'loginAccessPolicies' to '{"administratorsCanLogInAsAnyUser":true}'... done
logging out... done
See the JSON Schema for all supported settings.
Here is a full blown example showing most of the supported settings in action:
{
"$schema": "https://raw.githubusercontent.com/amtrack/sfdx-browserforce-plugin/main/src/plugins/schema.json",
"settings": {
"communities": { "enabled": true },
"customerPortal": { "enabled": true },
"deferSharingCalculation": {
"suspend": true
},
"highVelocitySalesSettings": {
"setUpAndEnable": true
},
"homePageLayouts": {
"homePageLayoutAssignments": [
{
"profile": "Standard User",
"layout": "Home Page Default"
},
{
"profile": "System Administrator",
"layout": "DE Default"
}
]
},
"picklists": {
"picklistValues": [
{
"metadataType": "StandardValueSet",
"metadataFullName": "LeadSource",
"value": "Partner",
"newValue": "Partner Referral"
},
{
"metadataType": "CustomField",
"metadataFullName": "Vehicle__c.Features__c",
"value": "CD",
"newValue": "Media",
"absent": true
},
{
"metadataType": "CustomField",
"metadataFullName": "Vehicle__c.Features__c",
"value": "CD",
"newValue": "AC",
"active": false
}
]
},
"recordTypes": { "deletions": [{ "fullName": "Vehicle__c.SUV" }] },
"salesforceToSalesforce": { "enabled": true },
"security": {
"loginAccessPolicies": { "administratorsCanLogInAsAnyUser": true },
"sharing": { "enableExternalSharingModel": true }
},
"companyInformation": {
"defaultCurrencyIsoCode": "English (Ireland) - EUR"
}
}
}
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
)We use Puppeteer for browser automation which comes with its own "Chrome for Testing" browser.
The puppeteer installation doc describes how this works:
When you install Puppeteer, it automatically downloads a recent version of Chrome for Testing (~170MB macOS, ~282MB Linux, ~280MB Windows) that is guaranteed to work with Puppeteer. The browser is downloaded to the
$HOME/.cache/puppeteer
folder by default (starting with Puppeteer v19.0.0).
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:
export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
sf plugins install sfdx-browserforce-plugin
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
sf browserforce:apply ...
Troubleshooting:
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.Please see CONTRIBUTING.md for getting started.
MIT © Matthias Rolke