From first test
to lasting confidence.

01 / Get started

Choose the right test environment.

Quak connects OpenXR input, independent application-state checks and reviewable evidence. Use Quest to test behavior on a real headset, and the integrated Simulator for faster local iteration. A Simulator pass does not establish device performance or visual correctness in the headset.

This guide covers the Unity project workflow. You need a supplied Quak release, Python 3.11+, Unity 6, Unity CLI with authentication, and OpenXR Plugin 1.17.1. Quest runs also need ADB; visual evidence needs FFmpeg and ffprobe.

The integrated Simulator lane additionally uses Meta XR Simulator, Unity Pipeline 0.4.0-exp.1, Meta XR Core SDK 205+ and its AI Tools. Direct Quest testing does not require Meta XR Operator. The standalone Simulator lane is experimental.

02 / Install & connect

Start with a pinned release.

Keep the supplied installer, wheel, Unity package, license and SHA256SUMS together. Replace the example paths below with your own. Install from the supplied release rather than the main branch.

python3 "/absolute/path/to/QUAK-INSTALL.py" --project "/absolute/path/to/MyUnityProject" --install-codex-skill

The installer verifies the artifacts, creates a project-local environment and launcher, adds the Unity package and runs static readiness checks. From the project root, use ./quak (or quak.cmd on Windows) to keep CLI and package versions aligned.

1. Let Unity finish compiling, then open QUAK → Control Panel and select Set up QUAK.
2. Select your runtime and enable its OpenXR controller interaction profile.
3. For Quest, build and launch an Android Development APK with the Quak OpenXR layer enabled. Authorize the selected headset over ADB.
4. For the integrated Simulator, activate Meta XR Simulator and Operator through the SDK AI Tools before entering Play mode.
5. Select your validation device and choose Verify connection. Resolve every readiness failure before testing.

To verify a running Quest app from the terminal, replace the serial and application ID:

./quak verify --target quest \
  --device-serial YOUR_ADB_SERIAL \
  --expected-application-id com.example.app

03 / Run a first test

See the whole loop work.

In Unity’s Package Manager, select Quak and import the MR Block Assembly Showcase sample. Open its BlockAssemblyLab scene. Start the integrated Simulator as described above, then run the sample from your Unity project root, replacing the installed version:

./quak doctor --target simulator --live
./quak run "Assets/Samples/QUAK/INSTALLED_VERSION/MR Block Assembly Showcase/Tests/block-assembly-lab.json"

The journey places pieces through OpenXR and checks the resulting app state. Run the adjacent block-assembly-wrong-socket.json test too: it should pass only when the application confirms that an invalid placement was attempted and rejected.

For a prepared Quest-target test and a Quak-enabled development APK, bind the run to the exact installed build:

./quak prove /absolute/path/to/app.apk \
  quak-tests/critical-quest.json \
  --device-serial YOUR_ADB_SERIAL

The Quest test must declare the intended application identity. Quak verifies the APK, installs or reuses the matching build, executes the test and saves evidence. Open .quak/evidence/RUN_ID/artifacts/run-report.html to inspect the result.

04 / Write your own tests

Make the expected outcome explicit.

Start with one important user journey. Give your coding agent access to the Unity project and describe the starting state, real interaction, expected result and invalid case.

Use $quak-test to add a Simulator test for checkout
confirmation. Exercise the real world-space control,
prove the confirmation state changed, and include a
passing negative control for an invalid selection.

The agent should inspect the actual interaction code, add the necessary app integration, and write a reviewed JSON test under quak-tests/. Coverage is defined by these tests; prompting alone does not establish correctness.

• Targets: use durable QuakTarget IDs for controls and objects that need stable references.
• State: expose real product facts through IQuakStateProvider. Generic scene readiness cannot prove a feature worked.
• Setup: use optional IQuakActionHandler fixtures for deterministic preparation, never to bypass the interaction being tested.
• Assertions: check the app’s response after input. An effect assertion must establish the expected state change; successful input injection alone is insufficient.

./quak validate quak-tests/checkout.json
./quak run quak-tests/checkout.json

Review the definition and demonstrate a failing case before trusting the passing result. Add the next journey when the next feature needs protection.

05 / Protect earlier work

Build a baseline that grows with you.

From a clean, known-good Git worktree, explicitly accept reviewed tests into the regression baseline:

./quak regression --accept

Then run the gate locally or in CI as development continues:

./quak regression

The gate flags protected tests that fail, become invalid, change without acceptance or disappear. It also rejects a dirty worktree. Review intentional test changes before accepting a new baseline; do not rebaseline simply to hide a failure.

Each added journey preserves a piece of the team’s knowledge. Quak reruns the protected coverage when you invoke the gate; your local workflow or CI determines when it runs. Device workers need their own runtime session and assigned headset.

06 / Review & request changes

Give every result its context.

Choose the Standard evidence preset in the Control Panel’s Tests tab when a journey needs video. It retains the source recording, a captioned journey and focused clips for marked interactions and failures. Open the run report first, then artifacts/visual-review.html for the recording and storyboard.

Results separate overall execution, product assertions and evidence. A recorded video is still pending review; mechanical checks for freezes or black frames do not establish visual correctness.

./quak review-bundle /absolute/path/to/receipt.json

Share the resulting review ZIP with a manager or QA reviewer. After extracting it, they can open review.html, inspect the recording and download an approval or timestamped change request describing observed and expected behavior. The offline page does not send feedback automatically.

Return human-review.json beside its receipt and give the review plus evidence to the engineer or their agent. After a fix, rerun with --supersedes /absolute/path/to/old/receipt.json and review the new recording. The original machine receipt remains unchanged.

07 / Troubleshooting

Start at the first failed check.

Run ./quak doctor for static checks. For a live Simulator session, run ./quak doctor --target simulator --live. For Quest, use the verification command above with the selected serial and intended application ID.

Installed, but not ready

Resolve Doctor’s reported prerequisites. An installer success followed by a readiness warning is not a passing connection test.

Quest bridge unavailable

Check ADB authorization, the Development Build, the Quak OpenXR layer, tracking and application focus. Rebuild after setup changes.

Input accepted, product failed

Inspect the first failed assertion and its before/after state in the run report. Do not weaken the expected result just because an input command succeeded.

Video recorded, review pending

This is expected. Inspect the timeline and save a human review; recording alone is not approval.