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/.
Test on Quest
For tests on a physical Meta Quest, open your web project and choose Headset above the preview. Use Share on Wi-Fi, or connect by USB and choose Open next to the authorized headset. The headset guide covers connection requirements. In the headset's browser, choose your app's Enter AR or Enter VR button and use the experience while wearing the headset.
Check the interactions your app uses: selecting and grabbing with controllers or hands, reading nearby text, moving around placed objects, hearing sound and leaving the experience. Watch for pauses or missing objects while moving your head. Repeat after a change that affects those behaviors.
Recorded XR tests replay in the desktop emulator. A passing replay does not establish Quest frame rate, hand tracking, passthrough placement or comfort. Keep the replay to catch repeatable regressions, and check the affected behavior on the headset. Unity and Unreal projects use their own native build and device workflow.
Good to know
- Browser checks serve regular files from the built app. Linked files and folders are refused; copy assets into the project before building. Large files stream as the browser reads them, and stopping the check closes unfinished transfers.
- 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 runs in the browser listed in Settings → Components. While that browser is still being downloaded, the check waits for it.
- Replays use the emulated headset, not a real one.