Screen memory

StepTrail can remember what it has learned about a system: the screens it has seen, the elements on them, which locators were proven to work, and how screens connect. A later replay can then recover when a locator breaks, because it knows another way to find the same element that has worked before.

There is no database and nothing to host. The memory is a few small JSON files in your project.

What is remembered

For each system you automate (you give it a short name such as shop):

• Screens, as address patterns: {base}/orders/:id, not a real address. Query strings are dropped and ids become :id.
• Elements on each screen, named by what a person would call them ("Email", "Log in"), with their best locators and each locator's record: how often it passed, how often it failed, and when it was last verified.
• Routes: which element on which screen led to which screen, and how often.
• Systems automated so far: the scenario names, how many replays, and the date and result of the last one.

What is never stored

• Typed values, passwords, cookies, storage, headers, response bodies or screenshots.
• Real host names or full addresses. The base address is supplied when you run, so one memory serves test, staging and production and none of them appears in a file.
• Element names, titles or locators that look personal or that change with the user: email addresses, phone or card-like numbers, IP addresses, tokens, and text containing long digit strings (for example "Welcome, Raj" or "Order 8841"). Such an element is remembered by its other locators.
• A memory that fails the privacy check is never written.

Use it in a replay

Add --memory and a system name:

node bin/replay.js steptrail-recording.json --memory shop

This does two things:

1. Heals. If a step's own locators all fail, replay tries locators the memory has already proven for that element before reporting "element not found". The report says so (used a locator from the screen memory).
2. Learns. After the replay it adds the recording's screens and elements, updates each locator's pass and fail record, and notes the run. The first replay with a new name creates the memory.

The files go in .steptrail/ in the folder you run from; use --memory-dir to put them elsewhere. Commit them to share the memory with your team.

The memory command

node bin/memory.js learn steptrail-recording.json --system shop
node bin/memory.js show --system shop
node bin/memory.js route --system shop /login /orders
node bin/memory.js systems
node bin/memory.js check --host shop.example.com
node bin/memory.js forget --system shop --yes

Command	What it does
learn <recording> --system <name>	Adds what a recording shows. Add --report report.json (from a replay run with --json) to record which locators worked
show --system <name>	Lists the screens, elements, best locators with their record, and routes
route --system <name> <from> <to>	Prints the shortest known route between two screens, for example /login to /orders
systems	Lists the systems automated so far
check	Scans every memory file for personal data, addresses and any host names you list with --host; exits with an error if it finds one, so you can run it in a build
forget --system <name> --yes	Removes one system's memory. Without --yes nothing happens

A system name is lowercase letters, numbers and dashes.

Limits

• It only knows screens it has visited and elements people used.
• A page can look different for different users; screens with the same address pattern are treated as one.
• Memory helps replay recover, but a step whose element no longer exists anywhere still fails, as it should.
• Writing tests from plain actions using the memory is planned, not built. See What's coming.