User’s Guide

This section is about configuration, integration and usage considerations.

Usage

The examples give a first (very limited) overview how to use hypothesis-ros. For further information about how to use the data generators of this package refer to the API documentation and the tests directory of the package source code repository.

Minimal Example

❯ pip install ipython
❯ ipython
In [1]: from hypothesis_ros.message_fields import int16
In [2]: int16().example()
Out[2]:-32183
In [3]: int16(min_value=5, max_value=5).example()
Out[3]: 5

Jupyter Notebook Examples

❯ pip install jupyter
❯ cd docs/source/notebooks/
❯ jupyter lab

Compatibility

The ROS1 test infrastructure is limited w.r.t. integration of test tools into the build tooling. The recommended way to integrate hypothesis-ros with ROS1 is by implementing a container level test framework. pytest and nose2 (no “prove in use”) are suitable test runner choices. docker, the official ROS1 docker images and docker-py may be used to provide the ROS1 node “runtime environment”.

Python interpreters

hypothesis-ros uses hypothesis which implies the compatibility with Python interpreters. Hypothesis is supported and tested on CPython 2.7 and CPython 3.4+ (hypothesis docs python versions). However hypothesis-ros is only tested against the main ROS1 Python version v2.7.

Python test frameworks (test runners)

hypothesis-ros uses hypothesis which implies the compatibility with Python test frameworks. Hypothesis is compatible with

  • unittest (supported, tested, no limitations),
  • pytest (supported, tested, limitations: function based fixtures do not behave like expected),
  • nose (supported, tested, yield based tests do not work)

(hypothesis docs testing frameworks).

Configuration

hypothesis settings

hypothesis was initially designed for Python source code level testing. Therefore the configuration of settings needs special care.

deadline: A deadline has either set to a very high value or should be disabled.

perform_health_checks: In case perform_health_checks is enabled some health checks need to be selectively disabled with suppress_health_check.

suppress_health_check: Refer to hypothesis health checks.

use_coverage: hypothesis supports coverage based data generation when the tests are executed on the Python source code level. hypothesis-ros does not support coverage based data generation. Enabling it has no effect/could raise errors.

A typical configuration of timeout and deadline in @settings looks like follows:

...
from hypothesis import settings, unlimited

...
@settings(timeout=unlimited,
          deadline=None,
          ...)
def test_node_does_not_crash(...):
    ...

The settings database_file, database, buffer_size, derandomize, max_examples, max_iterations, max_shrinks, min_satisfying_examples, phases, stateful_step_count, strict, `` usually don’t need special consideration and may be used as usual.

hypothesis health checks

hypothesis was initially designed for Python source code level testing. Therefore the configuration of health checks (hypothesis docs health checks) needs special care. In case health checks are performed (perform_health_checks) the health ckeck too_slow and hung_test need to be disabled via suppress_healthcheck usually.

A typical configuration of suppress_health_check in @settings looks like follows:

...
from hypothesis import settings, HealthCheck

...
@settings(...,
          suppress_health_check=[HealthCheck.too_slow,
                                 HealthCheck.hung_test]
         )
def test_node_does_not_crash(...):
    ...

The health checks data_too_large, filter_too_much, return_value and large_base_example don’t need special consideration and may be used as usual.

hypothesis example database

If a test fails hypothesis saves the test input in a atabase. The next time hypothesis runs this conditions will be used first. The configuration of the example database may be adjusted as usual (hypothesis docs example database).