WebXR Test API

1. Introduction

2. Conformance

Interfaces and functionality exposed by this specification SHOULD NOT be exposed to typical browsing experiences, and instead SHOULD only be used when running Web Platform Tests.

3. Simulated devices

3.1. Simulated XR Device

Every simulated XR device may have an native bounds geometry which is an array of DOMPointReadOnlys, used to initialize the native bounds geometry of any XRBoundedReferenceSpaces created for the device. If null, the device is treated as if it is not currently tracking a bounded reference space.

Every simulated XR device may have a floor origin which is an XRRigidTransform used to note the position of the physical floor. If null, the device is treated as if it is unable to identify the physical floor.

Every simulated XR device may have an viewer origin which is an XRRigidTransform used to set the position and orientation of the viewer. If null, the device is treated as if it has lost tracking.

Every simulated XR device has an emulated position boolean which is a boolean used to set the emulatedPosition of any XRPoses produced involving the viewer. This is initially false.

Every simulated XR device has an visibility state which is an XRVisibilityState used to set the visibilityState of any XRSessions associated with the simulated XR device . This is initially "visible". When it is changed, the associated changes must be reflected on the XRSession, including triggering onvisibilitychange events if necessary.

Every simulated XR device has a list of primary views which is a list of views that must be rendered to for an immersive experience. There must be at least one primary view.

Every simulated XR device may have a list of secondary views which is a list of views that may or may not be rendered to. There may be any number of secondary views.

Every view for a simulated XR device has an associated device resolution, which is an instance of FakeXRDeviceResolution. This resolution must be used when constructing XRViewport values for the view, based on the canvas size.

Every view for a simulated XR device may have an associated field of view, which is an instance of FakeXRFieldOfViewInit used to calculate projection matrices using depth values. If the field of view is set, projection matrix values are calculated using the field of view and depthNear and depthFar values.

3.2. Simulated Input Device

This API gives tests the ability to spin up a simulated XR input source which is an XR input source which from the point of view of the WebXR API behaves like a normal XR input source. These simulated XR input sources can be controlled by the associated FakeXRInputController object.

Every simulated XR input source has a handedness which is an XRHandedness value that MUST be returned for the corresponding XR input source’s handedness attribute.

Every simulated XR input source has a targetRayMode which is an XRTargetRayMode value that MUST be returned for the corresponding XR input source’s targetRayMode attribute.

Every simulated XR input source has a pointerOrigin which is an XRRigidTransform used to note the origin of the targetRaySpace.

A simulated XR input source may have a gripOrigin which is an XRRigidTransform used to note the origin of the gripSpace. If this is null the simulated XR input source is not tracked.

Every simulated XR input source has a profiles array which is an array of DOMStrings which MUST be returned for the corresponding XR input source’s profiles attribute.

Every simulated XR input source has a buttonState array which is an array of FakeXRButtonStateInits. If a "grip" button is specified, it SHOULD drive the primary squeeze action. If a UA implements the WebXR Gamepads Module buttonState SHOULD be used to set the state for the corresponding XR input source’s gamepad object, which SHOULD be of type "xr-standard" if enough buttons are specified to support it.

Every simulated XR input source has a connectionState which is a boolean that is initially true and indicates whether the associated XR input source should appear in inputSources. When it is changed the associated changes must be reflected on the XRSession, including triggering the inputsourceschange event if necessary by the next animation frame.

Every simulated XR input source has a primaryActionStarted which is a boolean, initially set to false, that indicates whether or not the primary action of the XR input source has been started.

4. Initialization

4.1. navigator.xr.test

partial interface XRSystem {
    [SameObject] readonly attribute XRTest test;
};

The test attribute’s getter MUST return the XRTest object that is associated with it. This object MAY be lazily created.

4.2. XRTest

The XRTest object is the entry point for all testing.

interface XRTest {
  Promise<FakeXRDevice> simulateDeviceConnection(FakeXRDeviceInit init);
  undefined simulateUserActivation(Function f);
  Promise<undefined> disconnectAllDevices();
};

When simulateUserActivation(f) is called, invoke f as if it had transient activation.

When disconnectAllDevices() is called, remove all simulated XR devices from the xr's list of immersive XR devices as if they were disconnected. If the inline XR device is a simulated XR device, reset it to the default inline XR device.

4.3. FakeXRDeviceInit

dictionary FakeXRDeviceInit {
    required boolean supportsImmersive;
    sequence<XRSessionMode> supportedModes;
    required sequence<FakeXRViewInit> views;
    sequence<FakeXRViewInit> secondaryViews;

    sequence<any> supportedFeatures;
    sequence<FakeXRBoundsPoint> boundsCoordinates;
    FakeXRRigidTransformInit floorOrigin;
    FakeXRRigidTransformInit viewerOrigin;

    // Hit test extensions:
    FakeXRWorldInit world;

    // Depth sensing extensions:
    FakeXRDepthSensingDataInit depthSensingData;
};

dictionary FakeXRViewInit {
  required XREye eye;
  required sequence<float> projectionMatrix;
  required FakeXRDeviceResolution resolution;
  required FakeXRRigidTransformInit viewOffset;
  FakeXRFieldOfViewInit fieldOfView;

  // Raw camera access extensions:
  FakeXRCameraImage cameraImageInit;
};

dictionary FakeXRFieldOfViewInit {
  required float upDegrees;
  required float downDegrees;
  required float leftDegrees;
  required float rightDegrees;
};

dictionary FakeXRDeviceResolution {
    required long width;
    required long height;
};

dictionary FakeXRBoundsPoint {
  double x; double z;
};

dictionary FakeXRRigidTransformInit {
  required sequence<float> position;
  required sequence<float> orientation;
};

The supportsImmersive is deprecated in favor of supportedModes and will be removed in future revisions of the specification.

4.4. FakeXRRigidTransformInit

5. Mocking

5.1. FakeXRDevice

interface FakeXRDevice : EventTarget {
  undefined setViews(sequence<FakeXRViewInit> views, optional sequence<FakeXRViewInit> secondaryViews);

  Promise<undefined> disconnect();

  undefined setViewerOrigin(FakeXRRigidTransformInit origin, optional boolean emulatedPosition = false);
  undefined clearViewerOrigin();
  undefined setFloorOrigin(FakeXRRigidTransformInit origin);
  undefined clearFloorOrigin();
  undefined setBoundsGeometry(sequence<FakeXRBoundsPoint> boundsCoordinates);
  undefined simulateResetPose();

  undefined simulateVisibilityChange(XRVisibilityState state);

  FakeXRInputController simulateInputSourceConnection(FakeXRInputSourceInit init);

  // Hit test extensions:
  undefined setWorld(FakeXRWorldInit world);
  undefined clearWorld();

  // Depth sensing extensions:
  undefined setDepthSensingData(FakeXRDepthSensingDataInit depthSensingData);
  undefined clearDepthSensingData();
};

Each FakeXRDevice object has an associated device, which is a simulated XR device that it is able to control.

The clearViewerOrigin() method will, on the next animation frame, set device's viewer origin to null.

The simulateVisibilityChange(state) method will, as soon as possible, set device's visibility state to state.

The clearFloorOrigin() method will, on the next animation frame, set device's floor origin to null.

The simulateResetPose() method will, as soon as possible, behave as if the device's viewer's native origin had a discontinuity, triggering appropriate reset events.

5.2. FakeXRInputController

dictionary FakeXRInputSourceInit {
  required XRHandedness handedness;
  required XRTargetRayMode targetRayMode;
  required FakeXRRigidTransformInit pointerOrigin;
  required sequence<DOMString> profiles;
  boolean selectionStarted = false;
  boolean selectionClicked = false;
  sequence<FakeXRButtonStateInit> supportedButtons;
  FakeXRRigidTransformInit gripOrigin;
};

interface FakeXRInputController {
  undefined setHandedness(XRHandedness handedness);
  undefined setTargetRayMode(XRTargetRayMode targetRayMode);
  undefined setProfiles(sequence<DOMString> profiles);
  undefined setGripOrigin(FakeXRRigidTransformInit gripOrigin, optional boolean emulatedPosition = false);
  undefined clearGripOrigin();
  undefined setPointerOrigin(FakeXRRigidTransformInit pointerOrigin, optional boolean emulatedPosition = false);

  undefined disconnect();
  undefined reconnect();

  undefined startSelection();
  undefined endSelection();
  undefined simulateSelect();

  undefined setSupportedButtons(sequence<FakeXRButtonStateInit> supportedButtons);
  undefined updateButtonState(FakeXRButtonStateInit buttonState);
};

enum FakeXRButtonType {
  "grip",
  "touchpad",
  "thumbstick",
  "optional-button",
  "optional-thumbstick"
};

dictionary FakeXRButtonStateInit {
  required FakeXRButtonType buttonType;
  required boolean pressed;
  required boolean touched;
  required float pressedValue;
  float xValue = 0.0;
  float yValue = 0.0;
};

Each FakeXRInputController object has an associated inputSource, which is a simulated XR input source that it is able to control.

Since user agents may opt to send input events on a per-frame basis, the results of all FakeXRInputController methods and simulateInputSourceConnection() are not guaranteed to be visible (via, e.g. inputSources or oninputsourceschange events) until the next animation frame.

Note: If a gamepad is attached to the simulated XR input source, then running start a primary action or stop a primary action should also ensure that the primary input’s corresponding gamepad button is updated accordingly.

Note: If both start a primary action and stop a primary action are run in the same frame, then by the next animation frame It is expected that onselect and onselectend events will fire.

The setHandedness(handedness) method will, by the next animation frame, set inputSource's handedness to handedness.

The setTargetRayMode(targetRayMode) method will, by the next animation frame, set inputSource's targetRayMode to targetRayMode.

The setProfiles(profiles) method will, by the next animation frame, set inputSource's profiles to profiles.

The setGripOrigin(gripOrigin) method will, by the next animation frame, set inputSource's gripOrigin to the result of running parse a rigid transform on gripOrigin.

The clearGripOrigin() method will, by the next animation frame, set inputSource's gripOrigin to null.

The setPointerOrigin(pointerOrigin) method will, by the next animation frame, set inputSource's pointerOrigin to the result of running parse a rigid transform on pointerOrigin.

The startSelection() method will run start a primary action on inputSource.

The endSelection() method will run stop a primary action on inputSource.

The simulateSelect() method will run simulate a full primary action on inputSource.

The setSupportedButtons(supportedButtons) will, by the next animation frame, set inputSource's buttonState to the result of running parse supported buttons on supportedButtons.

Note: As user agents may recreate the XRInputSource or gamepad objects on buttons being changed, this method SHOULD NOT be used to simulate changes to button state.

6. Hit test extensions

The hit test extensions for test API SHOULD be implemented by all user agents that implement WebXR Hit Test Module.

dictionary FakeXRWorldInit {
  required sequence<FakeXRRegionInit> hitTestRegions;
};

FakeXRWorldInit dictionary describes the state of the world that will be used when computing hit test results on a FakeXRDevice.

hitTestRegions contains a collection of FakeXRRegionInits that are used to describe specific regions of the fake world. The order of the regions does not matter.

dictionary FakeXRRegionInit {
  required sequence<FakeXRTriangleInit> faces;
  required FakeXRRegionType type;
};

FakeXRRegionInit dictionary describes the contents of a specific region of the world.

faces contains a collection of FakeXRTriangleInits that enumerate all the faces contained by the region. The order of the faces does not matter.

type contains a type of the region that will be used during computation of hit test results.

dictionary FakeXRTriangleInit {
  required sequence<DOMPointInit> vertices;  // size = 3
};

FakeXRTriangleInit dictionary describes a single face of a region.

vertices contains a collection of DOMPointInits that comprise the face. The face will be considered as solid when computing hit test results and as such, the winding order of the vertices does not matter.

enum FakeXRRegionType {
  "point",
  "plane",
  "mesh"
};

FakeXRRegionType enum is used to describe a type of the world region.

7. DOM overlay extensions

The DOM Overlay extensions for test API SHOULD be implemented by all user agents that implement WebXR DOM Overlay Module.

partial interface FakeXRInputController {
  undefined setOverlayPointerPosition(float x, float y);
};

When setOverlayPointerPosition(x, y) is called, it sets a position within the DOM overlay in DOM coordinates for the next XR animation frame, and is cleared after that frame. It is intended to be used along with a primary action for that frame, simulating that the user is interacting with the DOM overlay. The UA will emit a beforexrselect event at this location before generating XR select events.

8. Anchors extensions

The anchors extensions for test API SHOULD be implemented by all user agents that implement WebXR Anchors.

dictionary FakeXRAnchorCreationParameters {
  FakeXRRigidTransformInit requestedAnchorOrigin;
  boolean isAttachedToEntity;
};

callback FakeXRAnchorCreationCallback = Promise<boolean> (FakeXRAnchorCreationParameters parameters, FakeXRAnchorController anchorController);

partial interface FakeXRDevice {
  undefined setAnchorCreationCallback(FakeXRAnchorCreationCallback? callback);
};

The FakeXRAnchorCreationCallback callback can be used by the Web Platform Tests to control the result of a call to create an anchor, and to be able to subsequently control the newly created anchor.

The FakeXRDevice interface is extended with internal anchorCreationCallback, initially set to null. When the device receives a request to create an anchor, it MUST run the determine if the anchor creation succeeded algorithm.

The WPTs can set the anchor creation callback by calling setAnchorCreationCallback(callback).

The requestedAnchorOrigin attribute represents a transform expressed relative to base reference space used by the device.

The isAttachedToEntity attribute will be set to true if the created anchor should be treated as attached to some entity. If so, the tests could emulate entity changing location by appropriately controlling the anchor via anchorController.

The anchorController parameter passed in to FakeXRAnchorCreationCallback can be used to update the state of the anchor, assuming that the creation request was deemed successful. Tests SHOULD store it and issue commands to it for the entire duration of controlled anchor’s lifetime.

interface FakeXRAnchorController {
  readonly attribute boolean deleted;

  // Controlling anchor state:
  undefined pauseTracking();
  undefined resumeTracking();
  undefined stopTracking();

  // Controlling anchor location:
  undefined setAnchorOrigin(FakeXRRigidTransformInit anchorOrigin);
};

Successfully created anchors can be controlled by the test through the use of FakeXRAnchorController interface.

The FakeXRAnchorController has an associated internal anchor origin, which is a FakeXRRigidTransformInit describing the current state of the anchor’s native origin.

The deleted attribute will be set to true when the application has invoked an delete() method on the anchor - in that case, the changes to the fake anchor controller will be ignored.

The pauseTracking() method can be used by the tests to signal that the controlled anchor is temporarily untracked (i.e. its location will be unknown). Calling this method does not modify anchor origin of the controller.

The resumeTracking() method can be used by the tests to signal that the controlled anchor should have its tracking resumed, if it was temporarily untracked. Calling this method does not modify anchor origin of the controller.

The stopTracking() method can be used by the tests to signal that the controlled anchor is no longer tracked and that anchor tracking will not be resumed. After calling this method, the other calls on anchor controller will be ignored.

The setAnchorOrigin(anchorOrigin) method can be used to set the controller’s anchor origin. Tests can use this method to simulate updates in anchor pose.

9. Lighting estimation extensions

The lighting estimation extensions for test API SHOULD be implemented by all user agents that implement WebXR Lighting Estimation.

dictionary FakeXRLightEstimateInit {
  required sequence<float> sphericalHarmonicsCoefficients;
  DOMPointInit primaryLightDirection;
  DOMPointInit primaryLightIntensity;
};

partial interface FakeXRDevice {
  undefined setLightEstimate(FakeXRLightEstimateInit init);
};

The FakeXRDevice is extended with internal light estimate which is a FakeXRLightEstimateInit, used to supply data for any requested XRLightEstimate.

10. Depth sensing extensions

The depth sensing extensions for test API SHOULD be implemented by all user agents that implement WebXR Depth Sensing Module.

The FakeXRDevice is extended with internal depth sensing data which is a FakeXRDepthSensingDataInit, used to supply data for requests to native depth sensing.

dictionary FakeXRDepthSensingDataInit {
  required ArrayBuffer depthData;
  required FakeXRRigidTransformInit normDepthBufferFromNormView;
  required float rawValueToMeters;
  required unsigned long width;
  required unsigned long height;
};

FakeXRDepthSensingDataInit dictionary describes the state of the depth sensing data that should be used when returning latest depth information in creating a CPU depth information instance and creating a GPU depth information instance algorithms. All keys present in FakeXRDepthSensingDataInit correspond to the data required to be returned by native depth sensing capabilities of the device.

depthData corresponds to the desired depth buffer that is to be set on native depth information returned from querying the native device. Not setting depthData key in the dictionary signals that the returned native depth information should be null.

normDepthBufferFromNormView corresponds to the desired depth coordinates transformation matrix that is to be set on native depth information returned from querying the native device.

rawValueToMeters corresponds to the desired conversion factor that is to be set on native depth information returned from querying the native device.

width and height correspond to the desired dimensions of the depth buffer that are to be set on native depth information returned from querying the native device.

11. Raw camera access extensions

The raw camera access extensions for test API SHOULD be implemented by all user agents that implement WebXR Raw Camera Access Module.

The FakeXRViewInit dictionary is extended with cameraImageInit dictionary of type FakeXRDeviceResolution. This dictionary carries information about the camera image, and is intended to affect the camera image variable in obtain camera algorithm. If the cameraImageInit key is not present in the FakeXRViewInit dictionary, the obtain camera algorithm should treat this as null camera image (and thus the algorithm will return null).

dictionary FakeXRCameraImage {
  required long width;
  required long height;

  Uint32Array pixels;
};

The width controls the width of the camera image buffer in obtain camera algorithm.

The height controls the height of the camera image buffer in obtain camera algorithm.

The pixels control the camera image contents in obtain camera algorithm. The pixels will be used to initialize the camera image texture.

The camera image will be initialized as if by a call to gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, pixels), where width, height, and pixels are, respectively, width, height, and pixels. In case pixels key is not present in the dictionary, the behavior would be as if a call to gl.texImage2D() variant that omits the pixels parameter was made.

Any time a simulated XR device's list of primary views and list of secondary views is set, the user agent MUST verify that the camera images associated with the views present across both of those lists are all equal to each other. Camera images are considered equal when their widths and heights are equal, and their pixels are the same instance (if present). If they are not equal, the user agent MUST throw an error from within the algorithm that attempted to set them.