Picking and recording

The program builder opens a live browser on the page you are automating, and a copy of any page your jobs stored. Pick an element on either to get ranked locators and list fields, or use the live page normally and let Kaabist record what you do as steps.

#When to use it

Pick when you know which values you want and need reliable locators for them, especially lists. Record when the program has to do something first: sign in, fill a form, open a menu. For a page that only needs reading, picking on a stored page is the fastest: nothing runs and it costs nothing.

#The browser pane

Browser, in the builder's right column, shows the live page with a toolbar above it: a Navigate / Pick switch, back, reload, the address bar, and Open browser (which becomes Close once it is open). Before you open it you can name a stored session to start signed in; the pane says which network the browser goes out through, the same as a run of the program. Presets set the viewport (desktop 1280×800, small laptop, tablet, mobile), and Use for program copies the current one into the program's options. Tabs appear when the page opens more than one; "Something covers the page" warns about an overlay.

It has two modes:

• Navigate: you use the page as usual, and Kaabist records what you do as steps.
• Pick: clicks no longer reach the page; they select elements instead.

#Picking

Press Pick next to a target or a field in the step list: a banner says "Pick mode: click the element in the page". Hover to see what is under the pointer, outlined on the page; click to select it, and the target or field is filled in. A label beside the selection names the element, its best locator and how many similar elements the page has.

Every selection comes with up to six locators, best first, each checked to match exactly that element: a test id or an accessible role and name when the page has one, an id, the element's text, a CSS selector built only from classes that look stable, and finally a structural path. Elements inside shadow roots get a >>> selector that names the host chain; elements inside iframes carry their frame path.

In the step's form, the target's locators are listed best first, each marked stable, fair or fragile and unique or with its number of matches; reorder, remove or add one by hand.

Lists. Press s on one price in a grid and the selection becomes a list: the item selector, how many items there are, and the path from an item to the price. Pick anything else inside an item afterwards and it is added as a field of that list, with a suggested name and a few sample values. When a list renders fewer rows than it claims to have, the selection says so (virtualized): that list needs a scroll step to extract fully.

Hover-only UI. Open the menu in navigate mode, then switch to pick mode: the pointer no longer reaches the page, so the menu stays open. Freeze additionally pauses animations. Ctrl+click in navigate mode picks without switching modes.

Ground truth. When you confirm a field on a page, Kaabist stores a snapshot of the page and the element's fingerprint as the field's ground truth: the reference self-healing uses when the page changes (see self-healing).

#Picking on a stored page

You do not need a live browser to write an extract schema. Stored page opens any page your jobs have already fetched: type a reference such as job_…:steps[2] and Open, choose the version's ground truth, or press Use this page in the picker on a step of a test run. You pick on the copy Kaabist stored, the same way as live: the same locators, the same keys, the same lists and fields, because it is the same picker running over the same page. It is instant, since nothing goes back to a browser, and it costs nothing.

What you see is a safe copy: scripts and anything else that could run are removed, and the copy is shown in a sandbox where nothing can run anyway, so links do not navigate and forms do not submit. Images and styles are loaded as the page had them. Frames the page had on its own site are shown too; frames from other sites stay empty.

Text ranges. Select characters with the mouse and press r: the selection becomes a regex field. Press r with nothing selected to see the element's whole text instead.

Testing a schema. While you edit, every field is extracted from the page in your browser as you type; Run here shows the result under "In the browser". Test on the server runs the schema against the stored page on Kaabist, under "On the server": the answer a job would give for that page, including fields that read embedded JSON or a captured API response, which only the server has.

#Recording

Press Record in the browser pane; it counts the steps it has recorded and Pause recording stops it. In navigate mode every click, every field you type into, every selection in a dropdown and every checkbox becomes a step, with locators for the element. Typing into a field is one fill, however many keys it took.

The recorder makes suggestions on the steps it adds:

• A password is never recorded. The step says "The value typed here is a secret; it is not recorded." and offers to declare a secret input; the step then uses {{inputs.password}}.
• A one-time code is recognised ("This looks like a one-time code.") and Ask for it when the program runs adds an await_input step; the fill then uses {{vars.otp}}.
• After an action that navigates, "Add expect:" offers conditions (the new URL, headings or forms that appeared) that you attach with one click.

The recorder's steps are ordinary program steps (marked x_kaab: { "source": "recorder" }), so everything else in the builder (editing, linting, testing) works on them unchanged.

#Worked example

Record a customer portal's sign-in with a one-time code and pick its report:

1. In a new program's builder, open Browser on https://portal.example.com/login, press Open browser, then Record.
2. Sign in with a test account and accept the suggestion to declare the password as a secret input.
3. Type the one-time code the site sent and accept Ask for it when the program runs. Open the report, and attach the suggested expect on its URL.
4. Pause recording. Add an Extract step, press Pick on a new field, and click one amount in the report table; press s to select every row. Pick the other columns of a row to add them as fields of the list.
5. In Test, Run all: the run stops to ask for the one-time code, then returns the report's 40 rows.

#Pitfalls

• Picking in navigate mode. Clicks reach the page and get recorded. Switch to Pick first, or use Ctrl+click.
• Accepting a fragile locator. If the best candidate is marked fragile, add a better one by hand (a test id or a role and name) before you publish.
• Typing a real password while recording. It is not recorded, but it does reach the site. Use a test account.
• A virtualized list without a scroll step. The extract returns only the rows the page had in the DOM.

#Reference

• Targets and locators
• Extract fields, regex, many
• await_input