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 webots fixture.
  • 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.

Project links

Data verified by PyPI on Aug 20, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for tuppl from gravatar.com tuppl

Credits

Author: Dan Nguyen

GitHub Statistics

Data verified by PyPI on Aug 20, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Tags

pytest robot simulation webots

Report project as malware

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.1.tar.gz (24.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pytest_webots-0.1.1-py3-none-any.whl (35.0 kB view details)

Uploaded Python 3

File details

Details for the file pytest_webots-0.1.1.tar.gz.

File metadata

  • Download URL: pytest_webots-0.1.1.tar.gz
  • Upload date:
  • Size: 24.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pytest_webots-0.1.1.tar.gz
Algorithm Hash digest
SHA256 ac54c39f31d18cb1f80dff57c831be7d548ec25b2e05f284c1c5cd9bcf91ceb0
MD5 aa8faeda8bf02d2353407c17ba9a952c
BLAKE2b-256 bf8f321d852374f77c50ecefd29e8b78b684178fcfb027a6b23965c2c8dbf33e

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytest_webots-0.1.1.tar.gz:

Publisher: release.yml on tuppl/pytest-webots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pytest_webots-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: pytest_webots-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 35.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pytest_webots-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 8d0f838bba97dd1c6cbd5194eef7e0090be556b628932a400fe9e170f194e161
MD5 8c7cc427151861e4a8fb993ccb10ca86
BLAKE2b-256 cae743f6074a02fce130e3fac3386d71784aa3b0ecbc532edb61706c4afd64a0

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytest_webots-0.1.1-py3-none-any.whl:

Publisher: release.yml on tuppl/pytest-webots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page