Object Repository

17 min read

An object is an element your recordings act on, such as a Sign in button, kept with its locators. Each project has one Object Repository, holding the objects of every recorded test case in it.

Scripts use each object’s current locator. Fixing an object once therefore changes the script of every test case that uses it. Nothing is changed for you: when a new step looks like an element Hawzu already has, Hawzu suggests it, and a person confirms or keeps it separate.

Where to find it

In a project, select Object Repository in the project navigation. It carries the β beta badge, and appears wherever Record a Test is available and you can view the project’s test cases.

The page header shows the total number of objects, How it works (hover it for a short explanation), Refresh and Columns.

Selecting an object opens it in a drawer beside the list. The address in your browser then opens that object, so you can share a link to it.

How objects are created

When a recording is saved to a test case, each step that acts on an element gets its own object. Steps that act on no element, such as going to an address or a URL is check, get none.
A recording made while creating a test case is a draft, and gets its objects once you select Create.
Each new object gets a code such as OBJ-12, a name from the way the step describes the element, and version 1. It is marked Checked, because it was recorded while someone did the test.

Objects are made shortly after the recording is saved. Until then, the recording’s scripts use the locators it was recorded with.

Until a project has objects, the list says Objects appear here after you record a test case.

When a step is removed from its recording, or the recording is deleted, the step stops using its object. The object stays, with its history, and shows as unused if no other step uses it. A deleted test case no longer counts as using any object.

The summary tiles

Above the list, six tiles each show a count. Selecting a tile filters the list to what it counts, and selecting it again removes that filter. Hover a tile for a short hint, such as may break a script.

Tile	What it counts	Selecting it
Objects	Every object in the project. Its hint says how many pages they were recorded on.	Clears the filters the other tiles set.
Fragile	Objects with a red or orange fragility flag. Its hint says how many can’t run as recorded, when any can’t.	Shows only fragile objects.
Hand-edited	Objects whose locator was edited by hand and not checked on the page.	Sets the Checked filter to Hand-edited, not checked.
Unused	Objects no test case uses.	Shows only unused objects.
Failed in CI	Objects named by a CI build’s failure in the last 30 days.	Shows only those objects.
Waiting	Steps waiting for someone to confirm a suggestion.	Opens Suggestions.

A tile shows — until its count has loaded.

The Objects list

Pages

The Pages panel on the left shows how many pages objects were recorded on. It starts with All pages, then lists each host with its pages below it, each with its path and how many objects were recorded there. Hover a page to see an address it was recorded at.

Select a page to see only its objects. If Suggestions is open, the list switches back to Objects. An object recorded on two pages is counted on both.

Each step recorded with Hawzu Recorder 1.2.0 or later stores the page it happened on, so a route a single-page app changes without loading a page counts as its own page. A recording made before 1.2.0 stores no page per step. Hawzu works its pages out from the recording’s start address, its navigation steps and the navigations the recording saw. Only a route change in a single-page app that loads no new page stays under the page before it, until you record the test again.

A page is a host plus a path. Parts of a path that look like ids, such as numbers, UUIDs, long hexadecimal strings and dates, are read as :id, so /projects/42/settings and /projects/97/settings are one page. The query string is ignored, and a hash route such as #/users counts as part of the path.

Columns

Column	What it shows
Code	The object’s code, such as `OBJ-12`. Always shown, and pinned to the left.
Name	The object’s name.
Identity	Its test id, or its role and name, such as `button "sign in"`, with +N when it has more. no test id or role when it has neither.
Page	The path of the first page it was recorded on, with +N when there are more. Hover to see every page with its host.
Host	The hosts it was recorded on. Hidden unless you add it.
Fragility	Its worst flag, with +N when it has more, or none. Hover to see every flag and why. See Fragility.
Checked	Checked, Hand-edited or Not known. Hover to see what it means. See Verification.
Used by	How many test cases use it, such as 3 test cases, or unused. N waiting when steps are waiting for someone to confirm them as this object.
CI fails	How many CI builds in the last 30 days failed with an error naming this object’s locator, such as 2 builds, or — for none. See CI failures.
Version	Its current version, such as `v3`.
Last changed	When it last changed. Hover to see who, or by Hawzu.

A test case uses an object when one of its recordings has a step linked to that object. Deleted test cases are not counted.

To change the columns:

Columns in the page header chooses which columns show. Code cannot be hidden.
A column header’s menu offers Hide column, Pin column or Unpin column, Reset width and Reset all widths, and, on columns that sort, Ascending, Descending and Clear sort.
The + beside a header, shown when you hover it and a column is hidden, adds a hidden column right after it.
Drag a header to move its column, or drag its edge to change its width.

The columns you show and their order are saved for you.

The search box finds objects by code, name, test id or the element’s text.
Filters adds Fragility, to show objects with one fragility flag, or Checked, to show Checked on the page: recorded, Checked on the page: picked again or Hand-edited, not checked.
Sort by selecting the Code, Name, Version or Last changed header. The list starts with the most recently changed first, and clearing the sort returns to that order.

A page chosen in Pages, and the Fragile, Unused and Failed in CI tiles, show as chips above the list: On app.example.com/login, Fragile, Unused and Failed in CI, last 30 days. Remove one with its ×, or select Clear all. The Hand-edited tile shows as the Checked filter instead.

When nothing matches, the list says No objects match these filters. Select Clear filters to see every object.

The list shows 50 objects at a time. Its footer says which ones are showing, such as 1–50 of 312 objects, and Previous and Next move between them.

Verification

Each object’s locator is marked with a short word. Hover it to see the whole sentence.

Mark	Hover text
Checked	Recorded while someone did the test, so it was checked on the page.
Checked	Picked again in the browser with Hawzu Recorder, so it was checked on the page.
Hand-edited	Someone edited this locator by hand. Hawzu has not checked it on the page.
Not known	Hawzu has no record of how this locator was checked.

The full phrases checked on the page and hand-edited, not checked appear on a recording’s Locators tab, in the list of objects to merge into, in the message after a fix is saved, and in script headers.

Fragility

Each flag is about the locator a script actually uses, not about fallbacks it never reaches. Hover a flag to see which script it concerns and why.

Flag	Colour	What it means
no Selenium locator	Red	No locator Selenium can use, so the pytest + Selenium (Python) script marks the step `HAWZU_TODO`.
no Playwright locator	Red	No locator Playwright can use, so the Playwright (TypeScript) script marks the step `HAWZU_TODO`.
frame not located	Red	A frame or shadow host on the way to the element cannot be located, so the scripts mark it `HAWZU_TODO`.
picks by position	Orange	The locator picks the element by its position, so it can reach a different element if the page’s order changes.
absolute XPath	Orange	The locator is a path from the top of the page, so a change anywhere above the element breaks it.
text that changes	Orange	The locator matches text that looks like it changes between runs, such as three or more digits, dates, times, amounts or ids, or matches by a pattern or a container’s text.
generated value	Orange	The locator relies on a test id, id or class that looks generated, which can change with the next build.
hand-edited, not checked	Orange	The locator was edited by hand and not checked on the page.
may pick by position	Gray	The locator may pick by position. Recordings made with locator engines 1 and 2 did not record whether it does.

Red flags stop a script from running the step as recorded. Orange ones let it run, but it may break. Gray ones are worth knowing. The Fragility column shows the worst flag first.

An object’s details

Select a row to open the object in a drawer. Its title shows the object’s code and name, with a merged or deleted badge when it is no longer active.

At the top are its verification, its worst fragility flag, and Actions for an active object. Below them, tiles show its Version and how many Test cases, Recordings and Linked steps use it.

Choose what to see with the buttons below the tiles:

View	What it shows
Locator	This version: where the locator came from and when. Identity: its test id or role and name, and the pages it was recorded on. Fragility: every flag, with why. Locators: choose a script in Used by and a locator in Selector type to see it exactly as that script prints it, then Tried N expressions, Refused N and What the element looked like.
Usage	Each test case, recording and step that uses the object, with the step’s state: its own object, waiting for confirmation, confirmed or kept separate. The number beside Usage is how many test cases use it.
History	Everything that happened to the object, newest first. See Fixing a Locator.
CI failures	CI builds whose failure named this object’s locator. See CI failures.

An object with no test id, and no role with a name, says so in its Locator view. Hawzu never suggests that another step is that element.

CI failures

When you import results from a CI build, Hawzu reads the failure message of each failed or blocked test case that has recordings, and looks for the locators its scripts print. A failure is linked to an object when:

the message names the object’s locator, as Playwright’s error or Selenium’s “no such element” error does, for the current version or one of the three before it; or
the message is the sentence a script’s check prints when that check fails.

Select CI failures on an object to list the builds whose failures were linked to it, newest first, for the last 7 days, 30 days or 90 days. A line beside the window sums them up, such as Failed in 3 builds in the last 30 days (5 results), or says No CI failure has named this object’s locator in the last 30 days.

Each build shows its name, build N (a link to the build in your CI tool when Hawzu has its address) and when it ran. Each result shows the test case, its status, how it matched, and the failure message. It matched either Matched the locator (vN), naming the version whose locator the failure named, or Matched the check. Failures linked to an object that was later merged into this one are listed too, marked from merged OBJ-…. When there are more builds than fit, the list ends with Showing the newest N of M builds.

Hawzu cannot link a failure when:

the script was downloaded before its step was confirmed as a shared object, so the file still prints the step’s own recorded locator;
the failure is about a frame or shadow host on the way to the element, not the element itself; or
an older Playwright version names the frame with frameLocator(…) in its error.

Suggestions

When a recording is saved to a test case, Hawzu compares each of its steps with the project’s existing objects, including those made for earlier steps of the same recording, such as a click and a check on the same button. It suggests a step is an existing object only when all of these hold:

They share a test id, such as data-testid=login, or the same role and name, such as button "sign in". Names are compared ignoring case and extra spaces.
The step was recorded on the same page as the object.
The step is in the same frame or shadow root as the object.
Nobody already kept this step separate from that object.

A step whose locators are only CSS, XPath, or text such as a label, placeholder or alt text is never suggested anything. Text changes with the wording, and CSS and XPath describe the page’s structure, so neither is enough to say two steps are one element.

Each suggestion has a score:

Evidence	Score
The same test id	100
The same role and name	80
The same element type, such as `<button>`	+10
A different element type	−40
The same id	+5
A link to the same path	+5
A navigation before the step was recorded without its address, so the page is not certain	−10

Hawzu suggests objects that score 80 or more, up to three per step, best first. Each suggestion says why in words, such as Same test id data-testid=login on app.example.com/login, same element type <button>.

Confirm or keep separate

Decide in Suggestions in the Object Repository, or on the recording’s Locators tab, where a suggested step shows This may be an element Hawzu already has.

Open Object Repository and select Suggestions above the list, or the Waiting tile. The number beside Suggestions is how many steps are waiting.
For each step, read why each object is suggested. When a step has more than one suggestion, the first is marked Best match. The bar beside each suggestion shows its score.
Select Confirm beside the object the step is, or Keep separate if it is none of them.

Each step shows its test case, the step, the page it was recorded on, and its own object OBJ-n, which opens the object the step uses now. Select a suggested object’s code to open that object. The top of the list says how many steps there are to decide, such as 12 steps to decide.

A short notice confirms each decision, such as Step 3: Click Sign in now uses OBJ-12.

To confirm several at once, select the steps, or Select all on this page, then Confirm the best suggestion for N steps. Each selected step is confirmed as its first suggestion. A summary then says how many steps were confirmed, lists any step that could not be confirmed with the reason, and says how many test cases’ scripts changed.

Confirm makes the step use that object from then on. Its scripts print the object’s current locator, and a later fix to the object reaches this step’s scripts too. If the step’s own object was untouched (still version 1, never renamed, and used by no other step), it is merged into the object you confirmed and kept in its history.

Keep separate leaves the step on its own object, and those objects are not suggested for it again. A step someone confirmed cannot be kept separate. Split it instead.

Suggestions shows 50 steps at a time, with Previous and Next. When nothing is waiting, it says Nothing waiting for confirmation.

Merge, split, rename and delete

Changing objects is for workspace owners, workspace managers and project managers. Everyone else sees Actions disabled, and does not see Use its recorded locator.

Fixing, reverting, merging, splitting and deleting each end with a dialog listing the affected test cases. Download their scripts again. See Download the affected scripts again. Renaming changes no script, so it only shows a short notice.

Merge two objects

Open the object whose steps should move, select Actions, then Merge into….
Find the object to merge into. The list starts on this object’s page. Choose another of its pages or Any page, or search, to find others. Only objects in the same frame or shadow root are listed.
Select the object, then Merge into OBJ-n (N test cases).
If the two were recorded on different pages, Hawzu shows Recorded on different pages, naming the pages of each. Select Merge anyway to go ahead.

Every step that used the merged object uses the other object’s locator from then on. The merged object is kept in history as merged. After the merge, Hawzu opens the object you merged into.

Split a step onto its own object

Open the object and select Usage.
Beside the step, select Use its recorded locator.
Select Split the step.

The step gets a new object of its own, made from the locator it was recorded with, and its scripts stop using the old object. Splitting takes one step back to its recorded locator. To take every step that uses an object back to its recorded locator, delete the object.

Rename an object

Open the object, select Actions, then Rename.
Enter a name of up to 120 characters and select Rename.

Scripts name objects by code, never by name, so renaming changes no script.

Delete an object

Open the object, select Actions, then Delete.
Read which test cases it affects, under What this changes.
Select Delete OBJ-n.

Each step that used the object gets its own object again, made from the locator it was recorded with, so those scripts go back to their recorded locators. The deleted object’s history is kept. A link to a merged or deleted object opens a notice that no active object has that code.

How scripts use objects

Each time Hawzu builds a script, which happens when you open or download it, the script uses each linked object’s current locator. The recording itself is not changed. Its Steps tab, and the manual steps written from it, still describe what was recorded.
The script’s header lists the objects by code and version, such as Object Repository: OBJ-3 v2, OBJ-9 v1 (hand-edited, not checked), wrapped over several lines when it is long. It lists up to 60 objects, then ends with and N more. It never prints an object’s name. The script tab shows the same as Uses N objects (M hand-edited).
A file you already downloaded does not change. After an object changes, download the scripts of the affected test cases again.

See Manual Steps and Scripts for the header and the note beside a hand-edited locator.

On the Locators tab

On a recording’s Locators tab, each step that uses an object shows a chip such as OBJ-12 v3 · Sign in button · checked on the page. Hover it to see how the locator was checked, and select it to open the object.

When the object’s locator is no longer the one the step was recorded with, a toggle switches between Script uses: OBJ-12 v3, the locator the scripts print, and Recorded, what was recorded for the step.

Each step’s Selector type lists the locators the chosen script could print. Each option names the selector type, adds the rule that produced it when two share a type, and adds alternative N when those match too. It also says positional or hand-edited, not checked when that applies, and (used) for the one the script prints. The locator itself is shown below the dropdowns.

A locator entered by hand carries a hand-edited, not checked badge.

People who can change objects also see This may be an element Hawzu already has on a suggested step, with Confirm and Keep separate. A notice confirms the decision, such as This step’s scripts now use OBJ-12.

Permissions

Action	Who can do it
View the Object Repository, its objects, suggestions and history	Anyone who can view test cases in the project
Confirm or keep separate a suggestion	Workspace owners, workspace managers and project managers
Merge, split, rename or delete an object	Workspace owners, workspace managers and project managers
Fix a locator or revert to an earlier version	Workspace owners, workspace managers and project managers

For everyone else, Actions is disabled, and Use its recorded locator, Revert to this version and the suggestion prompt on the Locators tab are not shown. In Suggestions, Confirm and Keep separate are disabled, and the top of the list says Only workspace owners, workspace managers and project managers can change objects.

Changing an object changes the scripts of every test case that uses it, so changes are limited to these roles. There is no separate permission to grant a custom role.