An XR test is a recording of someone using the app in AR or VR. Graspable replays it after each run and compares the result with what was recorded. This catches changes that break something you already had working.
What a recording holds
A recording is one file in the project's tests/xr/ folder, with a name ending in .xrrec.json. It holds:
- every movement and button press of the headset and controllers,
- whether the session was AR or VR, and which synthetic room it was in,
- the scene at the end: each object's type, name, position and colour,
- a picture of the final frame.
The files are part of the project, so they travel with it.
Make a recording
- Open the preview and click Enter AR or Enter VR.
- Choose Record in the bar above the preview.
- Use the app the way you want it to keep working.
- Choose Stop & save.
See Preview and headset for the emulated headset.
The agent can also add recordings. It has a tool that opens the app in a browser, performs scripted actions and saves them as a recording. These show up as file edits in the run. The agent's tool never overwrites a recording you made, and re-recording one of its own asks you first.
How the completion check uses them
After the build and smoke checks pass, Graspable replays every recording in tests/xr/, in a browser without a window. The app enters XR through its own Enter AR or Enter VR button, which is why that button must stay in the app.
There are three outcomes.
| Outcome | What you see | What happens |
|---|---|---|
| Scenes match | ✓ xr check — … replayed, scenes match |
The run can complete |
| An error during replay | ✗ xr check — … failed |
The agent gets a repair turn, like a failed build |
| The scene is different | ✗ xr check — … differ from the recording |
Nothing is repaired. You decide |
The check compares objects by type, name, position and colour. Invisible objects are ignored. Text drawn into a texture is not seen by the check. If an object's state matters, ask the agent to give the object a meaningful name.
If the project has no recordings, there is no xr check.
Accept a new baseline
A different scene is often what you asked for. If you said "make the cube teal", the cube is no longer the recorded colour.
Graspable does not guess. Under the failed check it asks Intended change? with an Accept new baseline button.
- If the change is what you wanted, choose Accept new baseline. The replayed scene becomes what later runs compare against.
- If it is not, tell the agent what went wrong, or undo the run.
Replay by hand
Choose replay fixture… in the bar above the preview and pick a recording. Afterwards the bar shows a scene verdict and an image verdict.
The image verdict can differ even when nothing is wrong, for example when something in the scene animates over time. The completion check uses the scene, not the image.
When the recording is empty
A check may say:
the recording is empty (no frames), so it cannot be replayed — record it again or delete the file
This means the file has no movement in it. It usually happens when the app crashed in XR while it was being recorded. An empty recording is flagged and never repaired, because no code change can fix it.
To fix it, record it again, or delete the file from tests/xr/.
Good to know
- The agent is not allowed to edit files in
tests/xr/by hand. That would let it change the test instead of fixing the app. - The xr check needs Chrome, Edge or Chromium on your computer. Without one it is skipped and says so.
- Replays use the emulated headset, not a real one.