Just a handy utility to make your life testing dotcom things easier.

As dotcom developers, we often need to configure our browser instance in certain ways and perform repetitive actions upon a task, so this utility aims to ease the burden by:

1. Let you put the browser configuration you need to apply for what you are working on into a configuration file, so you don't need to tweak them again and again. Say goodbye to messing up with your browsers for daily uses.
2. Manage your own browser automation scripts for repetitive tasks in a way that's less involving than a formal e2e test.

dot-handy uses Playwright internally to implement the above two concepts as configuration and actions.

Configuration here simply means browser configuration you want to use to initiatialize your browser instance. e.g. browser type, locale, cookies, and local storage. Except for general browser settings, there are also dotcom-specific properties available like --currency. Configuration can be supplied through either a JSON configuration file or commandline options. A configuration file is first looked up from local-configs directory and then configs directory. The coresponding properties supplied by the commandline options will override. -C or --config-files options are used to supply config files; the corresponding commandline options for the properties are a bit ad hoc. For the most up-to-date list of properties and their commandline options, referring to the source code will be the best.

Actions here refers to browser automation scripts that will be run after initiating. Currently they can only be supplied by -A or --action-files commandline option. e.g. yarn start -A new-user pick-free-domain pick-free-plan means to open a new browser instance and then to create a new user, pick a free domain, and then choose the Free plan. It's kind of limiting right now because we can't use them in-between our own manual testing. An action file is looked up in a similar manner like configuration files: local-actions will be looked up first, and then actions directory. Actions can require certain configuration properties to work, like the action for setting ExPlat variations.

If you have yarn installed already, running yarn install should be all that you need to start playing it.

> yarn start                 # default to chromium
> yarn start -B webkit
> yarn start -B firefox

> yarn start -E local

> yarn start --locale "zh-TW"

> yarn start --currency "PHP"

> yarn start -A login --username TestUserName --password YourSuperSecretPassword

or, you can supply username and password through a local configuration file. It shouldn't be in the shared configs file because ... it's just not a good idea. A configuration file with the same name as the action file will be loaded by default if no other is supplied. e.g. putting the following in local-configs/login.json:

{
	"username": ".......",
	"password": "..................."
}

and then simply yarn start -A login will do.

1. Enable the store sandbox and sandbox the public API. Otherwise the dummy credit card info won't work.
2. Create a local-configs/new-user.json with newUserGmailPrefix and password field. This new-user action relies on the gmail + trick to create an account, and suppliying a password is required. It's easy to put a random password, but that has given me a hard time closing test accounts. Thus it is implemented this way for now. e.g. Mine looks like this:

{
        "newUserGmailPrefix": "supertestingemail",  <- this is not real
        "password": "MySuperSecretPassword"   <- this is also not real, of course.
}

3. Run yarn start -A new-user pick-free-domain pick-business-plan checkout

This will sign up a new account with the Business plan by appending a random string by the gmail + trick. e.g. in this case, it could be [email protected].

Caution: By doing this rapidly, your test email could be blacklisted. The real blacklisting conditions are unknown to me though. I have a test email that never gets blacklisted while some others are not so lucky.

At the moment of writing this, the configuration properties for setting ExPlat variations can't be supplied by commandline options. Thus, we'd need to create a local config for it. e.g. Add a local-configs/test-explat.json like:

{
        "explatExperiments": [
                [ "explat_experiment_slug", "treatment" ]
        ]
}

then run:

> yarn start -A set-explat new-user pick-free-domain pick-free-plan -C test-explat

I often want to login to one of my test accounts and enable the analytics debug log, thus I have a local-configs/mine.json like this:

{
  "username": "..........",
  "password": ".............",
	"localStorage": [
		[ "debug", "calypso:analytics:*"]
	]
}

then I'll run the following command to begin with:

> yarn start -A login -C mine

yarn start -A login close-account --username xxx --password yyy

It's also possible to combine this with some good old shell trick to close test accounts in batch. Let's say all the test accounts are having the same password yyy and they are all listed in a plain text file, test-accounts, line-by-line. Then this will do:

> cat test-accounts | xargs -L1 yarn start -A login close-account --password yyy --username

When you have to compare several variations side by side, combining dot-handy with GNU parallel can be very powerful. On a macOS, run brew install parallel will have it installed for you.

e.g.

Comparing LOHP side by side per 3 different currencies:

> parallel ::: "yarn start --currency TWD" "yarn start --currency PHP" "yarn start --currency EUR"

Comparing the control and the treatment variation of an ExPlat variation:

> parallel ::: "yarn start -A set-explat login -C test-account-1 exp-1-control" "yarn start -A set-explat login -C test-account-2 exp-1-treatment"

We all know the domain resolution of webkit isnt' affected by /etc/hosts. Thus it can happen to be a convenient way to compare sandboxed vs unsandboxed version:

> parallel ::: "yarn start -B webkit" "yarn start"