Hypothesis strategies

Craft Platforms provides several Hypothesis strategies to assist with testing.

Distributions and series

The primary strategy here is to generate DistroBase objects based on real Linux distributions:

craft_platforms.test.strategies.real_distro_base()[source]

Generate DistroBase objects of real (possibly future) Linux distributions.

This is the default strategy when generating DistroBase objects.

Return type:

SearchStrategy[DistroBase]

However, if you need to check that you can handle any realistic value, you can use:

craft_platforms.test.strategies.any_distro_base()[source]

Generate any DistroBase that vaguely looks as expected.

Return type:

SearchStrategy[DistroBase]

Specific distributions

If you need to test against a specific distribution, the following strategies are available:

craft_platforms.test.strategies.debian_series()[source]

Generate Debian releases as DistroBase objects.

This includes all stable Debian releases by version number (up to Debian 14) as well as the special values "sid" and "unstable". Because "testing", "stable" and "oldstable" refer to different releases given the current time, they are not included.

Return type:

SearchStrategy[DistroBase]

craft_platforms.test.strategies.ubuntu_series()[source]

Generate Ubuntu series as DistroBase objects.

This strategy includes both LTS and interim releases, as well as the special series “devel” that defines the currently under development Ubuntu release.

Return type:

SearchStrategy[DistroBase]

craft_platforms.test.strategies.ubuntu_lts()[source]

Generate LTS Ubuntu series as DistroBase objects.

This includes Ubuntu LTS releases all the way back to Ubuntu 6.06 (Dapper Drake) and may include future Ubuntu LTS releases as well.

Return type:

SearchStrategy[DistroBase]

[<distro>@<series>:]<arch> strings

craft_platforms.test.strategies.distro_series_arch_str(distro_base, arch=None)[source]

Generate distro@series:arch strings.

Parameters:
Return type:

SearchStrategy[str]

Platforms

There are several way to generate dictionaries of platforms. platforms() is the most comprehensive, but the complexity of what it creates can cause it to be quite slow. A faster way to do this is to generate a dictionary containing only a single platform, which platform() does.

craft_platforms.test.strategies.platforms(distro_base, shorthand_keys=None, values=None, min_size=1, max_size=8)[source]

Generate platforms dictionaries.

Generates platforms dictionaries with a size in the given range.

Warning

This function can be slow, especially when generating large dictionaries.

Parameters:

  • distro_base (SearchStrategy[DistroBase]) – A strategy that generates DistroBase` objects.

  • shorthand_keys (Optional[SearchStrategy[str]], default: None) – A strategy that generates valid shorthand keys. These could be architecture names or [<distro>@<base>:]<arch> strings (the default).

  • values (Optional[SearchStrategy[PlatformDict]], default: None) – A search strategy that generates PlatformDict objects. If not set, uses platform_dicts() with default arguments.

  • min_size (int, default: 1) – The minimum size of the dictionary. Must be >= 1.

  • max_size (Optional[int], default: 8) – The maximum size of the dictionary, or None for unbounded.

Return type:

SearchStrategy[Dict[str, Optional[PlatformDict]]]

craft_platforms.test.strategies.platform(distro_base, shorthand_keys=None, values=None)[source]

Generate a single platform in a dictionary.

The generated platform dictionary could either be of the shorthand form ({"[<distro>@<series>:]<arch>": None}) or of the longhand form.

Caution

The default values used here generate platform dictionaries that are not valid for most applications.

Parameters:

  • distro_base (SearchStrategy[DistroBase]) – A strategy that generates DistroBase` objects.

  • shorthand_keys (Optional[SearchStrategy[str]], default: None) – A strategy that generates valid shorthand keys. These could be architecture names or [<distro>@<base>:]<arch> strings (the default).

  • values (Optional[SearchStrategy[PlatformDict]], default: None) – A search strategy that generates PlatformDict objects. If not set, uses platform_dicts() with default arguments.

Return type:

SearchStrategy[Union[Dict[str, None], Dict[str, PlatformDict]]]

If you only need to test the dictionaries created without handling shorthand, PlatformDict objects can be created with platform_dict().

craft_platforms.test.strategies.platform_dict(build_ons=None, build_fors=None, max_build_ons=8)[source]

Generate platform dictionaries.

Caution

The platform dictionaries generated here only limited by the rules of what Craft Platforms considers a valid platform dictionary. Most applications have far stricter rules for their platform dictionaries, meaning this strategy is almost guaranteed to generate invalid dictionaries for an application. If you need PlatformDict objects that are valid for a particular application, it is better to build an app-specific strategy.

Parameters:
Return type:

SearchStrategy[PlatformDict]

Architectures

The strategy for getting DebianArchitecture objects is the normal strategy for getting any Enum values:

from craft_platforms import DebianArchitecture
from hypothesis import given, strategies

@given(arch=strategies.sampled_from(DebianArchitecture))
def test_architecture(arch: DebianArchitecture):
    assert isinstance(arch, DebianArchitecture)

However, this doesn’t cover all the valid values that can be placed in build-on and build-for fields of a platform. For these, we provide these strategies:

craft_platforms.test.strategies.build_on_str(distro_base)[source]

Generate valid build-on strings for platforms.

This strategy includes both architecture values and the values used for multi-base platform definitions.

Parameters:

distro_base (SearchStrategy[DistroBase]) – A strategy for generating DistroBase objects.

Return type:

SearchStrategy[str]

craft_platforms.test.strategies.build_for_str(distro_base)[source]

Generate valid build-for strings for platforms.

This strategy includes both architecture values (and "all") as well as valid values for multi-base platform definitions. Use build_for_arch_str() if you only want architecture strings or "all".

Parameters:

distro_base (SearchStrategy[DistroBase]) – A strategy for generating DistroBase objects.

Return type:

SearchStrategy[str]

craft_platforms.test.strategies.build_for_arch_str()[source]

Generate valid build-for architecture strings.

These are the string forms of any DebianArchitecture plus the special value "all". This should be used if you want only architecture strings without the multi-base format.

Return type:

SearchStrategy[str]