Gremlin UAT

How to use gremlin_uat

gremlin_uat turns what you do on a website into a UAT script: every click, entry and page change becomes a step with a screenshot, saved in MongoDB and shown on this site.

1. Start the database and the site

Copy the example settings once, then fill in a recorder token:

bash
cp .env.example .env.local
node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"

Paste the printed value after RECORDER_TOKEN= in .env.local. Then start MongoDB (Docker) and the site:

bash
npm run db:up
npm run db:check
npm run dev

The site runs at http://localhost:3000.

2. Try the recorder on the practice page

  1. Open the practice page.
  2. Tick Save to MongoDB in the Recorder panel if you want to keep the result, then press Record.
  3. Use the page: fill in the form, pick from the dropdowns, open the menu, switch tabs, place the order.
  4. Each action appears in the panel as a step, for example “Click the Place order button”.
  5. Type a check such as the total shows $40 and press Add check to add a “Verify” step.
  6. Press Stop, then Open the script.

On Record, Chrome asks to share this tab. Pick it and press Share, and each step gets a full screenshot with a red box around what you used.

With Whole-page pictures ticked, the panel scrolls down the page after each step and stitches it into one tall picture, like GoFullPage, then scrolls back. It takes about a second a step: while the pointer shows busy, clicks are ignored, so wait for it before the next click. Untick it for pictures of the window only.

3. Record any website with the Chrome plugin

bash
npm run ext:build
  1. In Chrome open chrome://extensions, turn on Developer mode, press Load unpacked and pick apps/chrome-extension/dist.
  2. Open the plugin’s Settings: server URL http://localhost:3000 and the same recorder token as .env.local. Press Test connection.
  3. Go to the site you want to test, open the plugin, name the script and press Record.
  4. Use the site. A small badge shows it’s recording and the step count. Press Alt+Shift+V to add a check.
  5. Press Stop. The finished script opens here with a screenshot for every step.

With Whole-page pictures ticked in the plugin, each step’s screenshot shows the whole page; untick it for the window only. The script page can show the pictures whole or cut to the window, for the whole script or one step. To picture the whole page the plugin uses Chrome’s debugger, so Chrome shows a “started debugging this browser” bar while you record. Leave it open. Pressing Cancel on it switches back to pictures of the visible part only.

Chrome’s own pages (chrome://, the Web Store) and pages inside frames can’t be recorded.

4. Or record without the plugin: the page overlay

Add ?uat=1 to any page of this site (for example the practice page) and a recorder toolbar appears in the corner. It works in any browser and keeps recording across page loads.

  • Name the script, press Record, use the site, press Stop.
  • Tick Screenshots (share this tab) and allow sharing once per page load to get a picture with every step.
  • Whole-page pictures, before Record, scrolls and stitches the whole page for each step. Untick it for the window only.
  • Drag the toolbar by its name, or hide it with –. ?uat=0 turns it off.

To use it on another site you run, add one line to that site’s pages:

html
<script src="http://localhost:3000/uat-overlay.js" data-token="YOUR_RECORDER_TOKEN" defer></script>

That site’s address also has to be listed in RECORDER_ALLOWED_ORIGINS in .env.local.

5. Review and hand it over

When you press Stop, Gremlin writes the UAT from what you did: it fills in the expected results it can see (“The Order summary page opens”), turns a page change into the expected result of the click before it, drafts an objective and flags anything that looks like a recording mistake. Anything it can’t be sure of says Expected result needs review. Open the script from Scripts to check it.

  • Edit a step to fix its wording or expected result. The recorded wording is kept, so you can restore it.
  • A flagged step says why. Keep it or Delete it.
  • Move up / Move down, Combine with next, Replace screenshot and Delete tidy the steps.
  • Re-record a step that went wrong: press it on the step, open the step’s page, then press Re-record step N in the Chrome plugin, the page toolbar or the practice panel and do the step again. That one action takes the step’s place, with new wording and a new picture, and recording stops by itself.
  • Download zip in a UAT plan’s action menu saves the whole plan, pictures included, as one file. Import zip above the UAT plans table adds one to a project, on this site or another Gremlin site.
  • Edit test details for the objective, environment, what to set up first and the test data.
  • Approve this UAT, then Print / PDF: cover page, step list, one page per step with Pass / Fail / N/A / Blocked boxes, and a sign-off page. Choose “Save as PDF” in the print dialog for a PDF.
  • On the print page, Pass / Fail boxes and notes on each step and Pictures under each step (untick it for all the pictures at the end) change the printout. They are saved for the project, so every script and plan in it prints the same way.

Testers fill in the printed script. Problems they find go into your own bug tracker.

Privacy

  • Hide passwords and card numbers (ticked by default, before Record): password and card fields are blacked out, card numbers are removed from all text, and the step just says “Enter the password”. Untick it for test logins and test cards you hand the testers anyway: the step then says what to type.
  • When the browser refuses a form (an email without an @, a required field left empty), its message shows under the field, where the screenshot can see it, and a “Verify the error” step records it.
  • Add data-uat-mask to anything on your own site to hide it from steps and black it out in screenshots.