Source code
Revision control
Copy as Markdown
Other Tools
Product Plugins
===============
External packages can register custom browser products with wptrunner using
entry points. Products registered this way are automatically
available to both the wptrunner test harness and the ``./wpt run`` CLI command.
Creating a Product Plugin
-------------------------
A product plugin consists of three components:
* A Python package containing your product implementation
* A ``get_product()`` function that returns a :py:class:`~products.Product` instance
* An entry point registration in ``setup.py`` or ``pyproject.toml``
Entry Point Registration
~~~~~~~~~~~~~~~~~~~~~~~~~
Register via the ``wptrunner.products`` entry point group. Example ``setup.py``::
setup(
name='wptrunner-mybrowser',
install_requires=['wptrunner'],
entry_points={
'wptrunner.products': ['mybrowser = wptrunner_mybrowser:get_product']
}
)
Or ``pyproject.toml``::
[project.entry-points."wptrunner.products"]
mybrowser = "wptrunner_mybrowser:get_product"
Product Module Implementation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Implement a Browser class and helper functions::
from wptrunner.products import Product
from wptrunner.browsers.base import Browser
from wptrunner.executors.executorwebdriver import (
WebDriverTestharnessExecutor,
WebDriverRefTestExecutor,
)
class MyBrowser(Browser):
def start(self, **kwargs):
# Launch browser process
# ...
def stop(self, force=False):
# ...
def is_alive(self):
# ...
def executor_browser(self):
from wptrunner.executors.executorwebdriver import WebDriverBrowser
return WebDriverBrowser, {"webdriver_url": self.webdriver_url}
def check_args(**kwargs):
pass # Validate required arguments
def browser_kwargs(logger, test_type, run_info_data, config, subsuite, **kwargs):
return {"binary": kwargs.get("binary")}
def executor_kwargs(logger, test_type, test_environment, run_info_data,
subsuite, **kwargs):
return {"capabilities": {"browserName": "mybrowser"}}
def get_product():
return Product(
name="mybrowser",
browser_classes={None: MyBrowser},
check_args=check_args,
get_browser_kwargs=browser_kwargs,
get_executor_kwargs=executor_kwargs,
env_options={"host": "web-platform.test", "bind_address": True},
get_env_extras=lambda **kw: [],
get_timeout_multiplier=lambda *a, **kw: 1.0,
executor_classes={
"testharness": WebDriverTestharnessExecutor,
"reftest": WebDriverRefTestExecutor,
},
)
Advanced Features
-----------------
Multi-Browser Support
~~~~~~~~~~~~~~~~~~~~~
Specify different browser classes per test type::
browser_classes={
None: MyBrowser, # Default
"wdspec": MyWdSpecBrowser, # WebDriver spec tests
}
Run Info Extras
~~~~~~~~~~~~~~~
Add custom metadata to test run information::
def run_info_extras(logger, **kwargs):
return {"mybrowser_version": "1.0.0"}
# Include in Product(..., run_info_extras=run_info_extras)
Custom Command-Line Arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Products can register their own command-line arguments that appear when users
run ``./wpt run --help``. Use the ``add_arguments`` attribute to add a function
that receives an ``argparse.ArgumentParser`` and adds product-specific options::
def add_arguments(parser):
group = parser.add_argument_group("MyBrowser-specific")
group.add_argument(
"--mybrowser-profile",
help="Path to browser profile directory"
)
group.add_argument(
"--mybrowser-debug",
action="store_true",
help="Enable debug mode"
)
# Include in Product(..., add_arguments=add_arguments)
These arguments will be available in your ``check_args``, ``browser_kwargs``,
and other functions via ``**kwargs``. The ``add_arguments`` function is called
for all available products during argument parser setup, so arguments are
always visible regardless of which product is selected.
API Reference
-------------
See the :py:class:`~products.Product` dataclass documentation for complete
field descriptions. All fields are documented in the Product class docstring,
including required and optional attributes, function signatures, and usage
examples.
Troubleshooting
---------------
Product Not Found
~~~~~~~~~~~~~~~~~
If your product doesn't appear in ``./wpt run --help``:
* Verify entry point is registered correctly
* Reinstall: ``pip uninstall wptrunner-mybrowser && pip install -e .``
Import Errors
~~~~~~~~~~~~~
Ensure all imports are available::
from wptrunner.products import Product
from wptrunner.browsers.base import Browser
Product Name Mismatch
~~~~~~~~~~~~~~~~~~~~~
Entry point name must match Product name::
'mybrowser = ...' # Entry point
Product(name="mybrowser", ...) # Product
For usage with ``./wpt run``, see the running-tests documentation.