Fixing a Locator

8 min read

When a script cannot find an element, fix the object it uses. The fix makes a new version of the object, and every test case that uses the object prints the new locator the next time its script is downloaded.

There are three ways to fix a locator. Each shows a preview before you can save.

Way	Use it when	The new version is marked
Pick again in the browser	The page changed, and you can open it in Chrome.	Checked
Use a recorded step’s locator	A step linked to the object was recorded after the page changed.	Checked
Edit by hand	You know the locator you need.	Hand-edited

Fixing is for workspace owners, workspace managers and project managers. Open the object from the Object Repository, or from its chip on a recording’s Locators tab, then select Actions and Fix locator. The dialog Fix the locator of OBJ-n opens, with the three ways as buttons across its top.

Pick again in the browser

This needs desktop Chrome with Hawzu Recorder 1.2.0 or later.

If Hawzu Recorder isn’t installed, Pick again in the browser shows Install Hawzu Recorder. Select Get the extension, install it, then select I’ve installed it.
If yours is older than 1.2.0, it shows Update Hawzu Recorder. Select Open the store page, or Copy chrome://extensions and paste it into a new tab, to update the extension, then select I’ve updated it.

Hawzu also checks for the extension again when you come back to its tab.

Open the object, select Actions, then Fix locator. The dialog opens on Pick again in the browser.
Check the address in Open the browser at. It starts with an address the object was recorded on, when Hawzu has one.
Select Pick the element. Hawzu Recorder opens a new Chrome window at that address, and Hawzu shows Waiting for the pick in the recording window…. While it waits, the address cannot be changed and the button reads Pick again.

The first time, the extension asks for permission. Allow it in the tab it opens, then select Pick the element again.
In the new window, sign in and go to the element if you need to. Nothing you do there is recorded.
In the Hawzu Recorder side panel, select Pick the element, then click the element on the page. Press Esc to stop picking.
The panel shows Element picked. Return to Hawzu, and the window closes after 10 seconds.
Back in Hawzu, the dialog says which address and Hawzu Recorder version the element was picked with. Read the preview, then select Save as vN.

You can pick an element inside a frame. The pick belongs to the page open in the window’s tab.

To pick a different element, select Pick again. Hawzu Recorder opens a new window, and Hawzu waits for that pick instead.

To give up, select Cancel in the side panel or close the window, then select Stop waiting in Hawzu. Hawzu keeps waiting until you do. Only one window runs at a time: if a recording is in progress, finish it before picking again.

Use a recorded step’s locator

The list holds the steps linked to this object. To use a step from a newer recording, for example after recording the test again on the changed page, first confirm that step as this object.

Open the object, select Actions, then Fix locator.
Select Use a recorded step’s locator.
Choose a step. Each one shows its test case code, its step, the page it was recorded on and its state.
Select Preview this step’s locator.
Read the preview, then select Save as vN.

The step must be in the same frame or shadow root as the object.

Edit by hand

Open the object, select Actions, then Fix locator.
Select Edit by hand. It lists the object’s current locators, numbered in order. Each shows its selector type and what it matches, with badges such as Playwright uses it, Selenium uses it, picks by position or hand-edited, not checked.
Reorder them with the up and down arrows, or remove one with its delete icon. Each script uses the first locator in the list it can print, so the order matters. The last locator left cannot be removed.
To add a locator, choose its type in Add a locator, fill in its value, then select Add. The types are Test id, Role and name, Label, Placeholder, Alt text, Title, Text, CSS selector and XPath. Test id asks for the Attribute, which starts as data-testid, and the test id. Role and name asks for the Role, such as button, and the Name. A locator you add is marked new · hand-edited, not checked.
Select Preview the edit. It stays disabled until you change the list, with the hint Change the list to preview it.
Read the preview, then select Save as vN.

What the scripts say. The script header marks the object (hand-edited, not checked). Where a script uses a locator you added, it prints a note above it: Note: this locator was hand-edited in the Object Repository and not checked on the page, so it may not find the element.
Up to 12 locators. Add is disabled once the list holds 12. Remove one to add another.
Position-based locators go last. A CSS selector or XPath that picks by position is tried after every locator that does not. Hawzu warns you when one you are adding picks by position.
Frames and shadow hosts stay as recorded. A hand edit cannot change the way to the element.

The preview

Save stays disabled until the preview has loaded, and changing anything clears it. The preview shows:

The new version, such as Saving makes OBJ-12 v4, marked Checked, or Hand-edited for a hand edit. Hover the mark to see the whole sentence.
Check before saving, when there is something to look at: the new locator shares neither the object’s test id nor its role and name, it was taken on a page the object was not recorded on, or it reaches the element through different frames or shadow hosts. These are warnings. You can still save.
What each script prints, as Now and After saving for Playwright and Selenium, exactly as each script writes the locator. unchanged means that script prints the same locator. none: the script leaves a HAWZU_TODO here means it has no locator it can print.
Fragility now and After saving.
Affected test cases, such as This changes the scripts of 3 test cases (3 recordings, 4 steps)., with each test case, recording and step.

If the fix would change nothing, the preview says the locator is already the object’s, and there is nothing to save. If neither script prints a different locator, the change only affects fallback locators.

Download the affected scripts again

Scripts are built when they are downloaded, so a file already in your repository keeps the old locator.

After saving, a dialog such as OBJ-12 is now v4 says how the new locator was checked, such as Its new locator is checked on the page., and lists every test case whose scripts changed.

In that dialog, select a test case code. It opens that test case’s Recordings tab in a new tab.
Open the recording, then the Playwright (TypeScript) or pytest + Selenium (Python) tab.
Select Download or Copy, and replace the file in your repository.
Repeat for each test case in the list, then select Done.

The same list appears after a revert, a merge, a split or a delete.

Version history and Revert

Select History on an object to list everything that happened to it, newest first. For each entry it shows who made the change (Hawzu for changes it made itself), when, what each script printed before and after, and how many test cases’ scripts it changed. Select Show older to see further back.

Each entry’s bullet shows its kind:

Bullet	Entry
Teal	A version whose locator was checked on the page.
Yellow	A version whose locator was edited by hand.
Gray	A change that made no new locator, such as a rename, a merge or a confirmed step.

An entry that made a version also shows its version, such as v3, and its Checked or Hand-edited mark.

Open the object and select History.
Beside an earlier version, select Revert to this version.
Read the preview, then select Save as vN.

Revert to this version appears only beside earlier versions whose locator was kept, once per version, and only for workspace owners, workspace managers and project managers on an active object.

Reverting makes a new version carrying the earlier version’s locator, marked the way it was checked then. The history is not rewound: the versions in between stay in it.

When someone else changed the object

If someone saves a change to the object after you opened it, your save is refused with Someone changed this object — reload. Reload the object, check its new version, and make your fix again. If a new version appears while the fix is open, the preview is cleared, so nothing you previewed against the old version can be saved.

Troubleshooting

“Hawzu Recorder isn’t installed in this browser.” Install the extension from Get the extension, then select I’ve installed it.
“Update Hawzu Recorder to 1.2.0 or newer, then try again.” Update the extension, then select I’ve updated it.
“Hawzu Recorder did not answer.” A window may have opened anyway. Pick the element there; Hawzu keeps waiting for it.
“A recording is in progress.” Finish or stop the recording in its own window, then pick again.
“Allow Hawzu Recorder in the tab it just opened.” Allow the permission there, then select Pick the element again.
“Enter an http or https address to start from.” Fix the address in Open the browser at, then pick again.
“Hawzu Recorder refused the request. Reload this page and try again.” Reload the page in Hawzu, then pick again.
“Hawzu Recorder couldn’t open the window. Try again.” Select Pick the element again.
Save is disabled. Preview the change first, or the fix would change nothing.
Preview the edit is disabled. Change the list first: reorder, remove or add a locator.