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, no-data, 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, tracks result statuses, and provides isolation between different policy checks on "no-data" outcomes.

Constructor

Check(name, description=None, component_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
policy_context (PolicyContext, optional): An alternate PolicyContext 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:

On enter: Sets up the check context and automatically loads component data if not provided
On exit: Records the check result with its status and all accessed data paths
Exception handling:
- Catches NoDataError and sets the check status to "no-data"
- Records other exceptions as "error" status with the exception message
- NoDataError will be suppressed, while other exceptions will still propagate

This means you can have multiple checks in sequence, and if one fails with a NoDataError, the others will still execute:

# Both checks will execute even if the first raises NoDataError
with Check("check-1") as check:
    raise NoDataError()
with Check("check-2") as check:
    check.assert_contains(Path(".tags"), "api")  # Will still execute

Note, however that other exceptions will still propagate, so you should still handle those appropriately.

with Check("check-1") as check:
    raise Exception("This is a test exception")
with Check("check-2") as check:
    check.assert_contains(Path(".tags"), "api") # This will not execute

Data Access Methods

get

get(path)

Retrieves data from the component JSON using a JSONPath expression.

path (str): JSONPath expression to query the component data
Returns: The value at the specified path, or raises NoDataError if not found, or ValueError if the path is invalid.

Example:

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

get_or_default

get_or_default(path, default_value)

Retrieves data from the component JSON using a JSONPath expression, or returns a default value if the path is not found.

path (str): JSONPath expression to query the component data
default_value: The value to return if the path is not found
Returns: The value at the specified path, or the default value if not found, or raises ValueError if the path is invalid.

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.

path (str): JSONPath expression to query the component data
Returns: A list of values matching the path across all metadata instances, or raises NoDataError if not found, or ValueError if the path is invalid.

Example:

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

get_all_or_default

get_all_or_default(path, default_value)

Retrieves data from all metadata instances using a JSONPath expression, or return the default value if the path is not found.

path (str): JSONPath expression to query the component data
default_value: The value to return if the path is not found
Returns: The value at the specified path, or the default value if not found, or raises ValueError if the path is invalid.

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_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

PreviousPolicy NextCheckStatus

Last updated 1 month ago