tests.bs

<pre class='metadata'>
Title: Testing Web Bluetooth
Group: web-bluetooth-cg
Status: CG-DRAFT
ED: https://webbluetoothcg.github.io/web-bluetooth/tests
Shortname: testing-web-bluetooth
Level: 1
Editor: See contributors on GitHub, , https://github.com/WebBluetoothCG/web-bluetooth/graphs/contributors
Abstract: This document describes functions used in testing the Web Bluetooth API.
Status Text:
  <strong class="advisement">
    This specification does not yet reflect the consensus of the Web Bluetooth
    CG. It is presented by the Chromium developers in the hope that other
    implementers will find it useful. It may be withdrawn if they don't.
  </strong>
  <div class="issue">
    This document is out of date.  It is a snapshot of the testing API as of
    late 2015.  A
    <a href="https://docs.google.com/document/d/1Nhv_oVDCodd1pEH_jj9k8gF4rPGb_84VYaZ9IG8M_WY">
    test API redesign</a>
    is under active design and development as of August 2017.
    Chromium developers are interested
    in updating and collaborating on this document when the next tested
    implementation begins development.
  </div>
Markup Shorthands: css no, markdown yes
Link Defaults: html (dfn) trusted event/the body element
Link Defaults: web-bluetooth (dfn) valid uuid
</pre>
<pre class="biblio">
{
  "BLUETOOTH42": {
    "href": "https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=286439",
    "title": "BLUETOOTH SPECIFICATION Version 4.2",
    "publisher": "Bluetooth SIG",
    "date": "2 December 2014"
  }
}
</pre>
<pre class="anchors">
spec: BLUETOOTH-ASSIGNED
    type: enum; urlPrefix: https://developer.bluetooth.org/gatt/
        urlPrefix: characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.
            text: org.bluetooth.characteristic.gap.device_name; url: gap.device_name.xml#
        urlPrefix: descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.
            text: org.bluetooth.descriptor.gatt.characteristic_user_description; url: gatt.characteristic_user_description.xml#
            text: org.bluetooth.descriptor.gatt.characteristic_extended_properties; url: gatt.characteristic_extended_properties.xml#
        urlPrefix: services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.
            text: org.bluetooth.service.battery_service; url: battery_service.xml#
            text: org.bluetooth.service.glucose; url: glucose.xml#
            text: org.bluetooth.service.generic_access; url: generic_access.xml#
            text: org.bluetooth.service.heart_rate; url: heart_rate.xml#
spec: ui-events; urlPrefix: https://www.w3.org/TR/uievents/#
    type: event
        text: keypress; url: event-type-keypress
    type: attribute
        for: KeyboardEvent; text: key; url: widl-KeyboardEvent-key
</pre>

<style>
.atrisk::before {
  content: '\25C0    May depend on implementation details';
}
</style>

<h2 id="introduction">Introduction</h2>

<em>This section is non-normative.</em>

Writing cross-browser tests for the
<a href="https://webbluetoothcg.github.io/web-bluetooth/">Web Bluetooth API</a> is
difficult because it interacts with devices that live outside the browser. This
document describes APIs that aid in this testing, and can be implemented by each
browser to either mock out the external interaction, or to configure an external
test device to behave as the test needs.

Tests using these functions are currently in <a
href="https://github.com/web-platform-tests/wpt/tree/master/bluetooth">web-platform-tests</a>
and in <a
href="https://code.google.com/p/chromium/codesearch/#chromium/src/third_party/WebKit/LayoutTests/bluetooth/">Chromium's
repository</a>.


<h2 id="security-and-privacy">Security considerations</h2>

Issue(575): See <a href="#privacy"></a> section.

<h2 id="privacy">Privacy considerations</h2>

These functions MUST NOT be exposed to web content. Only trusted testing
code may access them.


<h2 id="test-interfaces">Testing interfaces</h2>
<pre class="idl">
  partial interface Window {
    readonly attribute TestRunner testRunner;
    readonly attribute EventSender eventSender;
  };
</pre>


<h2 id="test-runner">testRunner</h2>

<pre class="idl">
  callback BluetoothManualChooserEventsCallback = undefined(sequence&lt;DOMString> events);

  [Exposed=Window, SecureContext]
  interface TestRunner {
    undefined setBluetoothMockDataSet(DOMString dataSetName);
    undefined setBluetoothManualChooser();
    undefined getBluetoothManualChooserEvents(BluetoothManualChooserEventsCallback callback);
    undefined sendBluetoothManualChooserEvent(DOMString event, DOMString argument);
  };
</pre>

<h3 id="setBluetoothMockDataSet">setBluetoothMockDataSet</h3>

When invoked, <dfn method
for="TestRunner">setBluetoothMockDataSet(dataSetName)</dfn> MUST replace the
user prompt used in {{Bluetooth/requestDevice()}} with one that resolves the
promise with the first discovered device, or rejects the promise if discovery
can't start or times out. Then it must configure the UA's Bluetooth system to
respond depending on the {{dataSetName}}:

: <code>"NotPresentAdapter"</code>
:: The UA has no Bluetooth implementation at all.
: <code>"NotPoweredAdapter"</code>
:: The UA's Bluetooth radio is disabled.
: <code class="atrisk">"ScanFilterCheckingAdapter"</code>
:: The UA may fail the test unless the test asks the adapter to start a
    Bluetooth scan filtered to the {{org.bluetooth.service.glucose}},
    {{org.bluetooth.service.heart_rate}}, and
    {{org.bluetooth.service.battery_service}} Service UUIDs. The adapter
    discovers a <a>BatteryDevice</a>.
: <code>"EmptyAdapter"</code>
:: No devices are nearby.
: <code>"FailStartDiscoveryAdapter"</code>
:: The UA fails to start a scan for devices.
: <code>"FailStopDiscoveryAdapter"</code>
:: Behaves like a GenericAccessAdapter, but the UA fails to stop the scan for
    devices.
: <code>"GlucoseHeartRateAdapter"</code>
:: The UA discovers a <a>HeartRateDevice</a> and a <a>GlucoseDevice</a>.
: <code>"SecondDiscoveryFindsHeartRateAdapter"</code>
:: In the first discovery session, the UA finds no devices. In the second, it
    discovers a <a>HeartRateDevice</a>.
: <code>"MissingServiceGenericAccessAdapter"</code>
:: The UA discovers a <a>MissingServiceGenericAccessDevice</a>.
: <code>"MissingCharacteristicGenericAccessAdapter"</code>
:: The UA discovers a <a>MissingCharacteristicGenericAccessDevice</a>.
: <code>"MissingDescriptorGenericAccessAdapter"</code>
:: The UA discovers a <a>MissingDescriptorGenericAccessDevice</a>.
: <code>"GenericAccessAdapter"</code>
:: The UA discovers a <a>GenericAccessDevice</a>.
: <code>"FailingGATTOperationsAdapter"</code>
:: The UA discovers a <a>FailingGATTOperationsDevice</a>.

<h4 dfn-type="dfn">BatteryDevice</h4>

Has a MAC address of
<code>00:00:00:00:00:01</code>, the name <code>"Battery Device"</code>, and
advertises {{org.bluetooth.service.battery_service}}.

<h4 dfn-type="dfn">GlucoseDevice</h4>

Has a MAC address of
<code>00:00:00:00:00:02</code>, the name <code>"Glucose Device"</code>, and
advertises {{org.bluetooth.service.glucose}}.

<h4 dfn-type="dfn">HeartRateDevice</h4>

Has a MAC address of
<code>00:00:00:00:00:03</code>, the name <code>"Heart Rate Device"</code>, and
advertises {{org.bluetooth.service.heart_rate}}.

<h4 dfn-type="dfn">MissingServiceGenericAccessDevice</h4>

Has a MAC address of
<code>00:00:00:00:00:00</code>, the name <code>"Generic Access
Device"</code>, and accepts GATT connections. Its GATT Server is empty.

<h4 dfn-type="dfn">MissingCharacteristicGenericAccessDevice</h4>

In addition to the properties of a <a>MissingServiceGenericAccessDevice</a>, its
GATT Server contains a primary {{org.bluetooth.service.generic_access}} service.
This service contains no characteristics.

<h4 dfn-type="dfn">MissingDescriptorGenericAccessDevice</h4>

In addition to the properties of a
<a>MissingCharacteristicGenericAccessDevice</a>, its
{{org.bluetooth.service.generic_access}} service contains the
{{org.bluetooth.characteristic.gap.device_name}} characteristic. This
characteristic returns <code>"GenericAccessDevice"</code> when read, and
responds that writes have succeeded (without changing the value read).

<h4 dfn-type="dfn">GenericAccessDevice</h4>

In addition to the properties of a
<a>MissingDescriptorGenericAccessDevice</a>, its
{{org.bluetooth.characteristic.gap.device_name}} characteristic contains the following descriptors:

: {{org.bluetooth.descriptor.gatt.characteristic_extended_properties}}
:: Has the Writable Auxiliaries bit set.
: {{org.bluetooth.descriptor.gatt.characteristic_user_description}}
:: Returns <code>"Device Name"</code> when read, and responds that writes
    have succeeded (without changing the value read).

<h4 dfn-type="dfn">FailingGATTOperationsDevice</h4>

Let <code><dfn abstract-op>errorUUID</dfn>(unsigned long id)</code> be the
<a>valid UUID</a> consisting of <code>id.toString(16)</code> left-padded with
<code>"0"</code>s to 8 characters, and then concatenated with
<code>"-97e5-4cd7-b9f1-f5a427670c59"</code>. (These lower 96 bits were generated
as a type 4 (random) UUID.)

The
<a>FailingGATTOperationsDevice</a> has a MAC address of
<code>00:00:00:00:00:00</code>, the name <code>"Errors Device"</code>, and
accepts GATT connections. Its GATT Server contains one service with UUID
<code>[$errorUUID$](0x100)</code>. This service contains 255 characteristics
with UUIDs <code>[$errorUUID$](0x101)</code> through
<code>[$errorUUID$](0x1ff)</code>. When read or written, the characteristic with
UUID <code>[$errorUUID$](which)</code> returns an Error Response
([[!BLUETOOTH42]] 3.F.3.4.1.1) with an error code of <code>which - 0x100</code>.


<h3 dfn-type="method" for="TestRunner">setBluetoothManualChooser()</h3>

When invoked, {{TestRunner/setBluetoothManualChooser()}} MUST replace the user
prompt used in {{Bluetooth/requestDevice()}} with a "<dfn>manual chooser</dfn>"
that records events that would otherwise be shown to the user (see
{{TestRunner/getBluetoothManualChooserEvents()}}), and which can simulate user
interaction with the prompt (see
{{TestRunner/sendBluetoothManualChooserEvent()}}).

<h3 dfn-type="method" for="TestRunner">getBluetoothManualChooserEvents(callback)</h3>

When invoked, {{TestRunner/getBluetoothManualChooserEvents(callback)}} MUST call `callback` with the
list of events that have been recorded by the <a>manual chooser</a> since
{{TestRunner/getBluetoothManualChooserEvents()}} was last called. Each event is
encoded as string, as follows:

: The chooser is opened following a request by origin <var>O</var>.
:: <code>"chooser-opened(<var>O</var>)"</code>
: The Bluetooth adapter is removed from the UA.
:: <code>"adapter-removed"</code>
: The Bluetooth adapter becomes present but disabled.
:: <code>"adapter-disabled"</code>
: The Bluetooth adapter becomes present and enabled.
:: <code>"adapter-enabled"</code>
: The Bluetooth adapter begins scanning for nearby devices.
:: <code>"discovering"</code>
: The Bluetooth adapter stops scanning for nearby devices.
:: <code>"discovery-idle"</code>
: The Bluetooth adapter attempts to begin scanning for nearby devices, but fails.
:: <code>"discovery-failed-to-start"</code>
: A device is added to the user prompt with {{BluetoothDevice/id}}
    <var>device-id</var> and {{BluetoothDevice/name}} <var>device-name</var>.
:: <code>"add-device(<var>device-name</var>)=<var>device-id</var>"</code>

    Note: The <var>device-id</var> might not be the device's MAC address. For
    example, MacOS and iOS generate a random ID when testing against physical
    devices.

: The UA discovers that a device with {{BluetoothDevice/id}}
    <var>device-id</var> is no longer nearby.
:: <code>"remove-device(<var>device-id</var>)"</code>


<h3 dfn-type="method" for="TestRunner">sendBluetoothManualChooserEvent(event, argument)</h3>

When invoked, {{TestRunner/sendBluetoothManualChooserEvent(event, argument)}}
MUST cause the <a>manual chooser</a> to inform the UA that the user has taken an
action corresponding to the {{event}}:

: <code>"cancelled"</code>
:: The user cancelled the prompt.
: <code>"selected"</code>
:: The user selected the device with an {{BluetoothDevice/id}} of {{argument}}.
: <code>"rescan"</code>
:: The user requested another bluetooth scan.


<h2 id="event-sender">eventSender</h2>

<pre class="idl">
  [Exposed=Window, SecureContext]
  interface EventSender {
    undefined keyDown(DOMString code);
  };
</pre>

<dfn method for="EventSender">keyDown(code)</dfn> must <a>fire an event</a>
named {{keypress}} to <a>the body element</a>, with its
{{KeyboardEvent/key}} attribute initialized to {{code}}.