hypothesis_utils.py

Overview

hypothesis_utils.py is a utility file that defines custom data generation strategies for use with the Hypothesis property-based testing framework. Specifically, it provides a strategy to generate valid names that conform to certain constraints, ensuring that generated test inputs meet expected naming conventions.

This file helps improve test coverage and robustness by allowing tests within the InfiniFlow project to use syntactically valid names automatically generated within specified limits. The primary focus is on generating string names suitable for identifiers, likely for variable names, keys, or other textual labels in the system.

Function: `valid_names`

@st.composite
def valid_names(draw):
    ...

Description

valid_names is a Hypothesis composite strategy that generates string values representing valid names. These names:

Consist only of lowercase ASCII letters (a-z) and underscores (_).
Always start with a letter or underscore.
Have a maximum length of 128 characters.
Are returned as UTF-8 decoded strings (ensuring valid Unicode string output).

This function leverages Hypothesis's internal draw mechanism to sample components for the string, combining them to form a valid name.

Parameters

draw: A special callable provided by Hypothesis composite strategies used to draw values from other strategies.

Returns

str: A string representing a valid name, compliant with the constraints above.

Implementation Details

The first character is drawn from the subset of base_chars that are either alphabetic characters or an underscore.
The remaining characters (0 to 126 characters) are drawn from the complete base_chars set, which includes lowercase letters and underscores.
The name is truncated to 128 characters to enforce the maximum length.
The encoded-then-decoded step (name.encode("utf-8").decode("utf-8")) ensures the returned value is a UTF-8 string, which may be redundant here but could help normalize the string or ensure compatibility.

Example Usage

from hypothesis import given
from hypothesis_utils import valid_names

@given(name=valid_names())
def test_name_property(name):
    assert len(name) <= 128
    assert name[0].isalpha() or name[0] == '_'
    assert all(c.islower() or c == '_' for c in name)

This example test function uses the valid_names strategy to verify that generated names meet the expected constraints.

Interaction with Other Parts of the System

The strategy defined here is intended to be imported and used in test modules across the InfiniFlow project, especially where valid name strings are needed as test inputs.
It depends on the external hypothesis.strategies module, which is part of the Hypothesis testing framework.
It does not interact directly with runtime components but serves as a utility for enhancing test coverage and input validity.
This modular design keeps name generation consistent across tests, preventing duplication of naming logic.

Summary

Aspect	Description
Purpose	Generate valid name strings for testing
Input	None (Hypothesis `draw` internally used)
Output	Valid UTF-8 strings with specific constraints
Dependencies	`hypothesis.strategies`
Use Case	Property-based tests requiring valid names

Mermaid Diagram

flowchart TD
    A[valid_names()] --> B[Draw first_char from letters or '_']
    A --> C[Draw remaining chars from letters or '_']
    B --> D[Concatenate first_char + remaining]
    C --> D
    D --> E[Truncate to max length 128]
    E --> F[Encode to UTF-8 and decode back]
    F --> G[Return final valid name string]

This flowchart describes the step-by-step process in the valid_names function, illustrating how components are drawn, combined, truncated, and normalized before returning the final valid name string.

License

This file is licensed under the Apache License, Version 2.0, as stated in the header comments.