HomeBlogGet a Demo

Check

The Check class provides a fluent interface for making assertions about policy data. The object keeps track of accessed data within the component JSON and records that for traceability purposes. The final result of a check will have not just the status (pass, fail, pending, or error), but complete information about which JSON paths were used to reach this conclusion. Designed to be used as a context manager with Python's with statement, the Check class automatically handles NoDataError (turns it into pending status), and tracks result statuses.

Constructor

Check(name, description=None, data=None)

Creates a new check instance that can be used to make assertions about the component data. If the component data is not provided, it will be loaded automatically from the environment via LUNAR_BUNDLE_PATH.

  • name (str): A unique identifier for this check

  • description (str, optional): A human-readable description of what this check validates

  • data (ComponentData, optional): An alternate ComponentData instance to use for this check, instead of loading it from the environment. Useful for unit testing.

Context Manager

The Check class is designed to be used as a context manager with Python's with statement. This is the recommended way to use the class as it ensures proper setup, teardown, and error handling.

with Check("check-name", "Check description") as check:
    # Make assertions using check methods
    check.assert_true(Path(".path.to.data"))

When used as a context manager, the Check class:

  1. On enter: Sets up the check context and automatically loads component data if not provided

  2. On exit: Records the check result with its status and all accessed data paths

  3. Exception handling:

    • Catches and suppresses NoDataError, and sets the check status to no-data, if collectors are still running.

    • Otherwise, propagates NoDataError and records as error status since NoDataError is unexpected after collectors finished.

    • Propagates other exceptions and records them as error status with the exception message

Data Access Methods

get

get(path)

Retrieves data from the component JSON using a JSONPath expression. This method raises ValueError if the path is invalid.

Missing data behavior:

  • Raises NoDataError before collectors finished (results in NO_DATA status).

  • Raises ValueError after collectors finished (results in ERROR status).

This means that get is best used when you are assuming that the data will eventually be provided by a collector.

  • path (str): JSONPath expression to query the component data

  • Returns: The value at the specified path, or raises NoDataError or ValueError.

Example:

# Get the number of lines in the README
lines = check.get(".readme.lines")

get_all

get_all(path)

Retrieves data from all metadata instances using a JSONPath expression. This method is useful if there are path collisions in the component JSON. This method raises ValueError if the path is invalid.

Missing data behavior:

  • Raises NoDataError before collectors finished (results in NO_DATA status).

  • Raises ValueError after collectors finished (results in ERROR status).

This means that get_all is best used when you are assuming that the data will eventually be provided by a collector.

  • path (str): JSONPath expression to query the component data

  • Returns: A list of values matching the path across all metadata instances, or raises NoDataError or ValueError.

Example:

# Get all API endpoints across all instances
all_endpoints = check.get_all(".api.endpoints")

exists

exists(path)

Returns True if the path exists in the component data.

Missing path behavior:

  • Raises NoDataError before collectors finished (results in NO_DATA status).

  • Returns False after collectors finished.

Example:

if check.exists(".api"):
    # This assertion will be executed only if the .api field exists.
    check.assert_true(Path(".api.auth_required"), "API should require authentication")

Assertion Methods

All assertion methods have these common parameters:

  • value: Can be a direct value, or a Path object

  • failure_message (str, optional): Custom message to display if the assertion fails

  • all_instances (bool, optional): If True, checks all metadata instances, not just the merged blob

Additionally, all assertion methods raise NoDataError if the path doesn't exist in the component data.

assert_true

assert_true(value, failure_message=None, all_instances=False)

Asserts that a value is True.

Example:

# Assert that authentication is required
check.assert_true(Path(".api.auth_required"), "API should require authentication")

assert_false

assert_false(value, failure_message=None, all_instances=False)

Asserts that a value is False.

Example:

# Assert that the README.md file is not missing
check.assert_false(Path(".readme.missing"), "README.md file should exist")

assert_equals

assert_equals(value, expected, failure_message=None, all_instances=False)

Asserts that a value equals the expected value.

  • expected: The expected value to compare against

Example:

# Assert that the API endpoint uses GET method
check.assert_equals(Path(".api.endpoints[0].method"), "GET", "Endpoint should use GET method")

assert_exists

assert_exists(path, failure_message=None)

Asserts that a path exists in the component data. If the path was not found, this method raises NoDataError before collectors finished, and fails the check after collectors finished.

Missing path behavior:

  • Raises NoDataError before collectors finished (results in NO_DATA status).

  • Fails the check after collectors finished (results in FAIL status).

Example:

check.assert_exists(".api", "API data not found")

assert_contains

assert_contains(value, expected, failure_message=None, all_instances=False)

Asserts that a value contains the expected value (works for strings, lists, etc.).

  • expected: The value that should be contained

Example:

# Assert that the endpoint path contains a specific substring
check.assert_contains(Path(".api.endpoints[0].path"), "/users")

# Assert that the tags list contains a specific tag
check.assert_contains(Path(".tags"), "api")

assert_greater

assert_greater(value, expected, failure_message=None, all_instances=False)

Asserts that a numeric value is greater than the expected value.

  • expected: The threshold value to compare against

Example:

# Assert that the code coverage is greater than 80%
check.assert_greater(Path(".coverage.percentage"), 80, "Code coverage should be greater than 80%")

assert_greater_or_equal

assert_greater_or_equal(value, expected, failure_message=None, all_instances=False)

Asserts that a numeric value is greater than or equal to the expected value.

  • expected: The threshold value to compare against

Example:

# Assert that README has at least 50 lines
check.assert_greater_or_equal(Path(".readme.lines"), 50, "README should have at least 50 lines")

assert_less

assert_less(value, expected, failure_message=None, all_instances=False)

Asserts that a numeric value is less than the expected value.

  • expected: The threshold value to compare against

Example:

# Assert that cyclomatic complexity is less than 15
check.assert_less(Path(".complexity.cyclomatic"), 15, "Cyclomatic complexity should be less than 15")

assert_less_or_equal

assert_less_or_equal(value, expected, failure_message=None, all_instances=False)

Asserts that a numeric value is less than or equal to the expected value.

  • expected: The threshold value to compare against

Example:

# Assert that build time is at most 5 minutes
check.assert_less_or_equal(Path(".build.duration_minutes"), 5, "Build should take at most 5 minutes")

assert_match

assert_match(value, pattern, failure_message=None, all_instances=False)

Asserts that a string value matches a regular expression pattern.

  • pattern (str): A regular expression pattern to match against

Example:

# Assert that version follows semantic versioning
check.assert_match(Path(".version"), r"^\d+\.\d+\.\d+$", "Version should follow semantic versioning")

fail

fail(message)

Unconditionally fails the check with a given message.

  • message (str): The message to display when the check fails

Example:

check.fail("This is a policy failure")

Instance Properties

After a check has been executed (typically after exiting the with context), the following properties are available:

status

status: CheckStatus

The final status of the check after execution.

  • Type: CheckStatus

  • Values: PASS, FAIL, NO_DATA, or ERROR

failure_reasons

failure_reasons: List[str]

The reasons for failure when the check status is FAIL. This property contains an array of detailed error messages from any failed assertions within the check.

  • Type: List[str]

  • Available when: status is CheckStatus.FAIL

name

name: str

The name of the check as specified in the constructor.

  • Type: str

PreviousPolicyNextCheckStatus

Last updated