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, orValueError
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, orValueError
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
objectfailure_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
, orERROR
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
isCheckStatus.FAIL
name
name: str
The name of the check as specified in the constructor.
Type:
str
Last updated