pytest-webots
pytest plugin for running Webots simulations with tests. Declare the worlds and controllers a test needs with markers. The plugin handles process lifecycle, world reuse, fast state reset, controller builds, and crash recovery.
The full guide lives in docs/GUIDE.md.
Requirements
Features
- Declare a world with
@pytest.mark.webots_world. Stack markers to parameterise the test over several worlds. - Webots worlds are process-isolated and reset between tests.
- Supervisor API is available through the
webotsfixture. - Declare extern controllers with
@pytest.mark.webots_controller. Stack markers to run several robots in one test. - C/C++ controllers are auto-built and cached.
- Other build systems can be attached with a hook.
Installation
pip install pytest-webots
Quick start
import pytest
@pytest.mark.webots_world("worlds/arena.wbt")
@pytest.mark.webots_controller("my_bot", "controllers/my_bot")
def test_drive(webots):
robot = webots.supervisor.getFromDef("ROBOT")
robot.getField("translation").setSFVec3f([0, 0, 1])
webots.step(64)
assert webots.controllers["my_bot"].alive
Reference
Options
| option | ini | default | description |
|---|---|---|---|
--webots-home DIR |
webots_home |
auto-discovered | Webots installation directory. Falls back to WEBOTS_HOME, then platform defaults such as /Applications/Webots.app and /usr/local/webots. |
webots_worlds_dir |
none | Directory world names resolve against, relative to root directory. | |
--webots-mode MODE |
webots_mode |
fast |
Simulation mode: realtime or fast. |
--webots-gui |
webots_headless |
true |
Run Webots without rendering. --webots-gui shows the window instead. |
--webots-startup-timeout SECONDS |
webots_startup_timeout |
60 |
Seconds to wait for a world to boot. |
--webots-port-base PORT |
webots_port_base |
1234 |
Lowest TCP port to try. Ports are assigned upward on demand and not reused. |
--webots-no-build |
webots_build |
true |
Build controllers before launching them. --webots-no-build skips every build. |
--webots-rebuild |
false |
Force controller rebuilds, ignoring the source-hash cache. | |
--webots-keep-alive |
false |
Leave Webots instances and injected worlds in place after the session, for debugging. | |
--webots-no-inject |
webots_inject_supervisor |
true |
Inject the supervisor robot that serves the Supervisor API. Without it there is no webots.supervisor. |
webots_supervisor_name |
pytest-supervisor |
Name of the injected supervisor robot. | |
webots_args |
none | Extra command line arguments for every Webots instance. | |
webots_max_restarts |
3 |
Consecutive failed boots of a world before giving up on it. | |
webots_make |
make |
Path to the make executable. On Windows, the Webots-packaged MSYS make. | |
webots_agent_plugins |
none | Python files loaded into the supervisor agent inside Webots; each defines register(agent). |
Markers
| marker | description |
|---|---|
@pytest.mark.webots_world(path, *, scope, mode, args, timeout) |
Boot a world for this test. Stack to parameterise test with several worlds. |
@pytest.mark.webots_controller(robot, path, *, build, args, env, cwd, autostart, protocol, ip_address) |
Attach an extern controller to a named robot. Stack for several robots. |
Markers also work at module and class level with pytestmark.
Fixtures
| fixture | description |
|---|---|
webots |
Per-test handle on the simulation: the Supervisor API, stepping and resetting, and this test's controllers. |
Hooks
Implement in conftest.py like any pytest hook:
| hook | description |
|---|---|
pytest_webots_resolve_world(name, config) |
Map a marker name to a world path (firstresult). |
pytest_webots_world_args(world, config) |
Extra Webots arguments per world. |
pytest_webots_world_started/_stopping(instance) |
World lifecycle. |
pytest_webots_world_crashed(instance, error) |
Fires on crash detection, before any restart. |
pytest_webots_before_reset/_after_reset(instance) |
Around the between-test reset. |
pytest_webots_controllers(item, instance) |
Additional ControllerSpecs for a test, with no marker involved. |
pytest_webots_build_controller(spec, config) |
Integrate a build system by dispatching on spec.build (firstresult). |
Todo
- Support simulation pause.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
pytest_webots-0.1.0.tar.gz
(24.3 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pytest_webots-0.1.0.tar.gz.
File metadata
- Download URL: pytest_webots-0.1.0.tar.gz
- Upload date:
- Size: 24.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8d29858c43f053e5980e5323b10cd5202c5feebca1d9ffa7053878af7236c0f0
|
|
| MD5 |
5ed6c2581ef1f40d2ab70c16c277b806
|
|
| BLAKE2b-256 |
7854c9c0fe8cfc2b8b73c271abd6b043f7959dc04776e82953ab375bec457448
|
Provenance
The following attestation bundles were made for pytest_webots-0.1.0.tar.gz:
Publisher:
release.yml on tuppl/pytest-webots
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pytest_webots-0.1.0.tar.gz -
Subject digest:
8d29858c43f053e5980e5323b10cd5202c5feebca1d9ffa7053878af7236c0f0 - Sigstore transparency entry: 2521226821
- Sigstore integration time:
-
Permalink:
tuppl/pytest-webots@14f7f5f3fee1efa9f3894311bfbf503da3c69bba -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/tuppl
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@14f7f5f3fee1efa9f3894311bfbf503da3c69bba -
Trigger Event:
push
-
Statement type:
File details
Details for the file pytest_webots-0.1.0-py3-none-any.whl.
File metadata
- Download URL: pytest_webots-0.1.0-py3-none-any.whl
- Upload date:
- Size: 34.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c2301f73a58b750287bbba5afae8d70305778b36f7f4ba385a860b55ead15992
|
|
| MD5 |
429c8a7460e26c7c18b096ba03a3e0b9
|
|
| BLAKE2b-256 |
6ef64c724e6e9d6c05189819ca945ecc621c5333814fe5003dad21d4283803ac
|
Provenance
The following attestation bundles were made for pytest_webots-0.1.0-py3-none-any.whl:
Publisher:
release.yml on tuppl/pytest-webots
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pytest_webots-0.1.0-py3-none-any.whl -
Subject digest:
c2301f73a58b750287bbba5afae8d70305778b36f7f4ba385a860b55ead15992 - Sigstore transparency entry: 2521226855
- Sigstore integration time:
-
Permalink:
tuppl/pytest-webots@14f7f5f3fee1efa9f3894311bfbf503da3c69bba -
Branch / Tag:
refs/tags/v0.1.0 - Owner: https://github.com/tuppl
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@14f7f5f3fee1efa9f3894311bfbf503da3c69bba -
Trigger Event:
push
-
Statement type:
