aite
Star
Fork
Watch
aite docs setup-extension.md
9.4 kB · 102 lines
Markdown
at main

Setting up the extension (a device that runs tests) #

The extension turns a browser into a device. It takes tests the central system offers it, runs them in tabs it opens, and uploads what happened. It is a separate extension from the one in extension/src that aite run drives from the command line. This page builds it, installs it and enrols it. To set up the central system it talks to, see setup-dispatcher.md; to put it on a second machine over the LAN, see runbook-laptop.md.

What you need #

  • The central system running, and its two public keys (npm run central -- key).
  • A Chromium-based browser on the device, with Developer mode available on its extensions page. The extension uses the debugger permission to click and type like a person, so the browser shows a "debugging this browser" bar while a test runs. That is expected.
  • A way for the browser to reach the central system. On the same machine it is 127.0.0.1. From another machine, an SSH tunnel to ports 4790 and 5290 keeps the address at 127.0.0.1 on that machine too. The extension only sends its tokens over https or to its own machine, so plain http to another address does not work.
  • Advised: a browser profile used only for this, with no personal accounts signed in. A test can drive any site that profile is signed in to.

Build it #

On the machine that has the repository, with the keys from npm run central -- key:

npm run build:worker -- --out dist/worker --central http://127.0.0.1:4790/api \
  --release-key RELEASE_KEY --dispatch-key DISPATCH_KEY --version 0.3.0
Option Meaning
--out DIR Where the unpacked extension goes.
--central URL The central system's API address, written into the extension. Plain http only to a loopback address; anything else must be https.
--release-key, --dispatch-key The two public keys (or --release-key-file and --dispatch-key-file). The build refuses a missing key or one that is not 32 bytes, because the extension would run nothing.
--allow ORIGIN Optional, repeatable. Fixes the sites tests may touch in this build.
--version V Up to four numbers separated by dots. Use a new one for each build so Chrome shows which is loaded.

An open build (no --allow) tests any site a signed job names, except the sites the person at the device lists as not allowed. Nothing about a site is fixed in it, so a new site never needs a new download. It asks Chrome for access to all sites and declares no content script: the page code is put only into the tabs a test opens, nothing is added to pages you browse yourself. Chrome's install prompt for it says it can read and change data on all sites, which is true, and the list of sites the person denies is what keeps important ones out.

A build with a list of sites (--allow https://SITE, repeat for more) can never touch a site that is not listed, whatever a job says, and the person must approve each listed site in the popup before it is used. A new site means a new build. Use it when you want a ceiling that nothing at run time can raise.

The output is five files: manifest.json, sw.js (the worker, with the keys and address pinned in), popup.html, popup.js and content.js. The same input gives the same files.

Install it #

  1. Copy the folder to the device if it is another machine (scp -r dist/worker USER@DEVICE:aite-worker).
  2. Open chrome://extensions, switch on Developer mode, choose Load unpacked and pick the folder. Pin the extension's icon so the popup is one click away.
  3. The extension starts on its own. Chrome stops idle extensions, so an alarm starts it again every half minute and when the browser starts; you do not need to open anything.

Enrol it #

  1. On the central machine make a one-time code: npm run central -- enrol --person NAME --any-site --name laptop --code-out /path/to/code.txt (--origin https://SITE instead of --any-site for a build with a list of sites). The code goes to the file, not the screen, works once and lasts an hour.
  2. Read the code from the file, click the extension's icon, paste it, and choose Enrol this device. The popup says Enrolled and shows the person, the device id and the central address.

Enrolling again is only needed if the central system revoked the device (the popup says so), or the extension was removed (its stored enrolment goes with it).

The popup #

Control What it does
Doorbell connected means the central system can wake the device at once. connecting means it is trying; the device still finds work by polling every 30 seconds.
Pause all work Nothing is taken, and a test that is running ends at once. The central system is told and gives the job to another device.
Check for work now Looks for a job immediately and shows what it found.
Sites this device will not test (open build) One site to a line, for example bank.example. A site also covers every site under it. A test on a listed site is refused, the central system stops sending this device tests for it, and adding a site while a test runs ends the run.
Site boxes (build with a list of sites) Tick the sites you approve. Nothing is approved until you do.
Allow tests that post Off until you switch it on. A test that publishes something public needs it, and the job must allow it.
Most per day The most posting tests this device takes in a UTC day (default 10); the device counts its own.
Allow tests that spend A separate switch, off until you switch it on, and off again after every enrolment.
Accounts For a test that signs in as a named profile: which account that profile is signed in as on this device. A test is refused if the start page shows another account.

Only the popup can change these. A page under test cannot reach them: the extension answers messages only from its own popup page.

Update it #

Build again with a new --version, copy the files over the old folder, and click Reload on the extension in chrome://extensions. Reload keeps the enrolment and the settings. You need a new code only if you remove the extension, or you change from a build with a list of sites to an open one (the enrolment's sites were fixed when it was made; enrol again with --any-site).

Check that it works #

  • The popup shows the device and Doorbell: connected.
  • npm run central -- device list on the central machine shows the device online with its Chrome version and the sites it allows.
  • Send a test that does something visible and read what the device reports about itself:
npm run central -- dispatch --ref main --file scripts/YOUR_TEST.aite \
  --start https://SITE/ --allow https://SITE --device DEVICE_ID
npm run central -- job archive JOB_ID --out result.zip   # then read device.json

device.json in the result names the browser, the operating system, the clock and the time zone of the machine that ran it, so you can tell which machine it was. The test opens a tab in the foreground of the browser profile with the extension, and closes the tabs it opened when it ends, so a short test is easy to miss: watch the right browser, and give a test pauses (sleep 2s) and checks of real content, not only a page load.

Remove it #

Revoke it centrally (npm run central -- device revoke ID), then remove the extension from chrome://extensions.

When something is wrong #

What you see Why
The popup says the extension did not answer The worker is starting; open the popup again.
Doorbell: connecting for long Port 5290 is not reachable from the browser (the tunnel is missing that forward). Jobs are still found by polling.
Enrolment says the code is not valid It was used, it expired, or the tunnel points at another service. Make a new one.
A job is refused origin-not-approved A build with a list of sites: tick the site in the popup.
A job is refused site-denied The site is on this device's list; take it off.
The central system says no device matches, "does not allow tests on" The same list, reported by the device.
A test fails at its opening step as load-failed The browser could not load the page (it showed its own error page): the site is down, cannot be reached from this machine, or the address is wrong. For a site on the central machine, forward its port through the tunnel too. The screenshot shows the browser's error.
A test fails with ambiguous The target matched several elements. It says so after about a second and a half and lists them; make the target more specific or add index:.
Nothing visible happened The tab opens in the browser profile that has the extension, which may not be the browser you were looking at. Read device.json in the result to see which machine and browser ran it.

What to know about safety #

The jobs are signed by the central system and the extension checks the signature, the expiry and its own device id before it runs anything, but an open build will test whatever site a correctly signed job names, in a browser that may be signed in there. Use a dedicated profile, put sites that matter on the list of sites to refuse, and leave posting and spending off unless a test needs them. What is protected and what is not is in security-review.md.