[wdspec] add bluetooth module

docs/writing-tests/wdspec.md

@@ -1,7 +1,8 @@
 # wdspec tests
 
 The term "wdspec" describes a type of test in WPT which verifies some aspect of
-[the WebDriver protocol](https://w3c.github.io/webdriver/). These tests are
+[WebDriver Classic](https://w3c.github.io/webdriver/) or 
+[WebDriver BiDi](https://w3c.github.io/webdriver-bidi) protocols. These tests are
 written in [the Python programming language](https://www.python.org/) and
 structured with [the pytest testing
 framework](https://docs.pytest.org/en/latest/).
@@ -66,3 +67,93 @@ a WebDriver session) are defined in terms of Pytest "fixtures" and must be
 loaded accordingly. For more detail on how to define and use test fixtures,
 please refer to [the pytest project's documentation on the
 topic](https://docs.pytest.org/en/latest/fixture.html).
+
+## WebDriver BiDi
+
+The wdspec tests for [WebDriver BiDi](https://w3c.github.io/webdriver-bidi) are 
+located in the `tests/bidi/` and `tests/interop` directories. 
+The `webdriver.bidi.client.BidiSession` class provides an abstraction for the BiDi 
+client and contains properties corresponding to the 
+[WebDriver BiDi modules](https://w3c.github.io/webdriver-bidi/#protocol-modules). It 
+can be retrieved by fixture `bidi_session`.  
+
+### Extending WebDriver BiDi
+
+This section describes how to extend the WebDriver BiDi client with an example of 
+adding support for [Web Bluetooth](https://webbluetoothcg.github.io/web-bluetooth).
+
+#### Adding a New Module
+
+##### Create `BidiModule`
+
+BiDi modules are defined in the `tools/webdriver/webdriver/bidi/modules/` directory.
+To add a new module called `bluetooth`, declare a Python class 
+`webdriver.bidi.modules.bluetooth.Bluetooth` that inherits from `BidiModule` and 
+store it in `tools/webdriver/webdriver/bidi/modules/bluetooth.py`:
+
+```python
+class Bluetooth(BidiModule):
+    """
+    Represents the Bluetooth automation module specified in
+    https://webbluetoothcg.github.io/web-bluetooth/#automated-testing
+    """
+    pass
+```
+
+##### Import the Module in `bidi/modules/__init__.py`
+
+Import this class in `tools/webdriver/webdriver/bidi/modules/__init__.py`:
+
+```python
+from .bluetooth import Bluetooth
+```
+
+##### Create an Instance of the Module in `webdriver.bidi.client.BidiSession`
+
+Modify the `webdriver.bidi.client.BidiSession.__init__` method to create an instance 
+of `Bluetooth` and store it in a `bluetooth` property:
+
+```python
+self.bluetooth = modules.Bluetooth(self)
+```
+
+#### Adding a New Command
+
+[WebDriver BiDi commands](https://w3c.github.io/webdriver-bidi/#commands) are 
+represented as module methods decorated with 
+`@command` (`webdriver.bidi.modules._module.command`). To add a new command, add 
+a method with the corresponding name (translated from camel case to snake case) to 
+the module. The method should return a dictionary that represents the 
+[command parameters](https://w3c.github.io/webdriver-bidi/#command-command-parameters).
+
+For example, to add the 
+[`bluetooth.simulateAdapter`](https://w3c.github.io/webdriver-bidi/#command-command-parameters)
+command, add the following `simulate_adapter` method to the `Bluetooth` class:
+
+```python
+from ._module import command
+...
+class Bluetooth(BidiModule):
+    ...
+    @command
+    def simulate_adapter(self, context: str, state: str) -> Mapping[str, Any]:
+        return {
+            "context": context,
+            "state": state
+        }
+```
+
+### Adding Tests
+
+Generally, a single test file should contain tests for a single parameter or feature 
+and stored in `webdriver/tests/bidi/{MODULE}/{METHOD}/{FEATURE}.py`
+For example, tests for 
+[`bluetooth.simulateAdapter`](https://webbluetoothcg.github.io/web-bluetooth/#bluetooth-simulateAdapter-command) 
+could be split into:
+* Invalid parameters: `webdriver/tests/bidi/bluetooth/simulate_adapter/invalid.py`
+* State: `webdriver/tests/bidi/bluetooth/simulate_adapter/state.py`
+* Context: `webdriver/tests/bidi/bluetooth/simulate_adapter/context.py`
+
+In the example of [`bluetooth.simulateAdapter`](https://w3c.github.io/webdriver-bidi/#command-command-parameters), 
+tests can use `bidi_session.bluetooth.simulate_adapter` method to send the command 
+and verify its side effects.

tools/webdriver/webdriver/bidi/client.py

@@ -90,6 +90,7 @@ def __init__(self,
 
         # Modules.
         # For each module, have a property representing that module
+        self.bluetooth = modules.Bluetooth(self)
         self.browser = modules.Browser(self)
         self.browsing_context = modules.BrowsingContext(self)
         self.input = modules.Input(self)

tools/webdriver/webdriver/bidi/modules/__init__.py

@@ -1,5 +1,6 @@
 # flake8: noqa
 
+from .bluetooth import Bluetooth
 from .browser import Browser
 from .browsing_context import BrowsingContext
 from .input import Input

tools/webdriver/webdriver/bidi/modules/bluetooth.py

@@ -0,0 +1,21 @@
+from typing import Any, Mapping, MutableMapping
+
+from ._module import BidiModule, command
+
+
+class Bluetooth(BidiModule):
+    """
+    Represents bluetooth automation module specified in
+    https://webbluetoothcg.github.io/web-bluetooth/#automated-testing
+    """
+
+    @command
+    def simulate_adapter(self, context: str, state: str) -> Mapping[str, Any]:
+        """
+        Represents a command `bluetooth.simulateAdapter` specified in
+        https://webbluetoothcg.github.io/web-bluetooth/#bluetooth-simulateAdapter-command
+        """
+        return {
+            "context": context,
+            "state": state
+        }

webdriver/tests/bidi/bluetooth/simulate_adapter/__init__.py

@@ -0,0 +1,18 @@
+from webdriver.bidi.modules.script import ContextTarget
+
+
+async def get_bluetooth_availability(bidi_session, context):
+    result = await bidi_session.script.evaluate(
+        expression="navigator.bluetooth.getAvailability()",
+        target=ContextTarget(context["context"]), await_promise=True, )
+    return result['value']
+
+
+async def set_simulate_adapter(bidi_session, context, test_page, state):
+    # Navigate to a page, as bluetooth is not guaranteed to work on
+    # `about:blank`.
+    await bidi_session.browsing_context.navigate(context=context['context'],
+                                                 url=test_page, wait="complete")
+
+    await bidi_session.bluetooth.simulate_adapter(context=context["context"],
+                                                  state=state)

webdriver/tests/bidi/bluetooth/simulate_adapter/context.py

@@ -0,0 +1,19 @@
+import pytest
+
+from . import get_bluetooth_availability, set_simulate_adapter
+
+pytestmark = pytest.mark.asyncio
+
+
+async def test_contexts_are_isolated(bidi_session, top_context, test_page):
+    another_browsing_context = await bidi_session.browsing_context.create(
+        type_hint="tab")
+
+    await set_simulate_adapter(bidi_session, top_context, test_page,
+                               "powered-on")
+    await set_simulate_adapter(bidi_session, another_browsing_context,
+                               test_page, "absent")
+
+    assert await get_bluetooth_availability(bidi_session, top_context) == True
+    assert await get_bluetooth_availability(bidi_session,
+                                            another_browsing_context) == False

webdriver/tests/bidi/bluetooth/simulate_adapter/invalid.py

@@ -0,0 +1,31 @@
+import pytest
+import webdriver.bidi.error as error
+
+pytestmark = pytest.mark.asyncio
+
+
+@pytest.mark.parametrize("state", [None, False, 42, {}, []])
+async def test_state_invalid_type(bidi_session, top_context, state):
+    with pytest.raises(error.InvalidArgumentException):
+        await bidi_session.bluetooth.simulate_adapter(
+            context=top_context["context"], state=state)
+
+
+@pytest.mark.parametrize("state", ["", "invalid"])
+async def test_state_invalid_value(bidi_session, top_context, state):
+    with pytest.raises(error.InvalidArgumentException):
+        await bidi_session.bluetooth.simulate_adapter(
+            context=top_context["context"], state=state)
+
+
+@pytest.mark.parametrize("context", [None, False, 42, {}, []])
+async def test_context_invalid_type(bidi_session, context):
+    with pytest.raises(error.InvalidArgumentException):
+        await bidi_session.bluetooth.simulate_adapter(
+            context=context, state="powered-on")
+
+
+async def test_context_unknown_value(bidi_session):
+    with pytest.raises(error.NoSuchFrameException):
+        await bidi_session.bluetooth.simulate_adapter(
+            context="UNKNOWN_CONTEXT", state="powered-on")

webdriver/tests/bidi/bluetooth/simulate_adapter/state.py

@@ -0,0 +1,31 @@
+import pytest
+
+from . import get_bluetooth_availability, set_simulate_adapter
+
+pytestmark = pytest.mark.asyncio
+
+
+@pytest.mark.parametrize("state,availability",
+                         [("absent", False), ("powered-off", True),
+                          ("powered-on", True)])
+async def test_state(bidi_session, top_context, test_page, state, availability):
+    await set_simulate_adapter(bidi_session, top_context, test_page, state)
+    assert await get_bluetooth_availability(bidi_session,
+                                            top_context) == availability
+
+
+@pytest.mark.parametrize("state_1,availability_1",
+                         [("absent", False), ("powered-off", True),
+                          ("powered-on", True)])
+@pytest.mark.parametrize("state_2,availability_2",
+                         [("absent", False), ("powered-off", True),
+                          ("powered-on", True)])
+async def test_set_twice(bidi_session, top_context, test_page, state_1,
+      availability_1, state_2, availability_2):
+    await set_simulate_adapter(bidi_session, top_context, test_page, state_1)
+    assert await get_bluetooth_availability(bidi_session,
+                                            top_context) == availability_1
+
+    await set_simulate_adapter(bidi_session, top_context, test_page, state_2)
+    assert await get_bluetooth_availability(bidi_session,
+                                            top_context) == availability_2