Skip to main content
Complete reference for all test decorators available in the Elementary Python SDK.

​
Import Statement

from elementary_python_sdk.core.tests import (
    boolean_test,
    expected_range,
    expected_values,
    row_count,
)

​
@boolean_test

Tests that return a boolean (True/False) result.

​
Signature

@boolean_test(
    name: str,
    severity: str | TestSeverity = "ERROR",
    description: str | None = None,
    tags: list[str] | None = None,
    owners: list[str] | None = None,
    metadata: dict | None = None,
    column_name: str | None = None,
    quality_dimension: QualityDimension | None = None,
    skip: bool = False,
)
def test_function(df: pd.DataFrame) -> bool:
    # Your test logic
    return True  # or False

​
Parameters

ParameterTypeRequiredDefaultDescription
namestrYes-Test name
severitystrNo"ERROR"Test severity: "ERROR" or "WARNING"
descriptionstrNoNoneTest description
column_namestrNoNoneColumn being tested (for column-level tests)
tagslist[str]NoNoneList of tags
ownerslist[str]NoNoneList of owners
metadatadictNoNoneAdditional metadata
quality_dimensionQualityDimensionNoNoneQuality dimension (defaults to VALIDITY if column_name is set)
skipboolNoFalseWhether to skip this test

​
Example

@boolean_test(
    name="unique_ids",
    description="All user IDs must be unique",
    column_name="id",
    severity="ERROR",
)
def test_unique_ids(df: pd.DataFrame) -> bool:
    ids = df["id"].dropna().tolist()
    return len(ids) == len(set(ids))

​
@expected_range

Tests that return a numeric value that should fall within a range.

​
Signature

@expected_range(
    name: str,
    min: float | None = None,
    max: float | None = None,
    severity: str | TestSeverity = "ERROR",
    description: str | None = None,
    tags: list[str] | None = None,
    owners: list[str] | None = None,
    metadata: dict | None = None,
    column_name: str | None = None,
    quality_dimension: QualityDimension | None = None,
    skip: bool = False,
)
def test_function(df: pd.DataFrame) -> float:
    # Your test logic
    return 25.5  # Numeric value

​
Parameters

ParameterTypeRequiredDefaultDescription
namestrYes-Test name
minfloatNoNoneMinimum expected value (inclusive)
maxfloatNoNoneMaximum expected value (inclusive)
severitystrNo"ERROR"Test severity
descriptionstrNoNoneTest description
column_namestrNoNoneColumn being tested
tags, owners, metadata, quality_dimension, skip-No-Same as @boolean_test

​
Example

@expected_range(
    name="average_age",
    min=18,
    max=50,
    description="Average age should be between 18 and 50",
    column_name="age",
    severity="ERROR",
)
def test_average_age(df: pd.DataFrame) -> float:
    return df["age"].mean()

​
@expected_values

Tests that return a value that should match one of a list of expected values.

​
Signature

@expected_values(
    name: str,
    expected: Any | list[Any],
    allow_none: bool = False,
    severity: str | TestSeverity = "ERROR",
    description: str | None = None,
    tags: list[str] | None = None,
    owners: list[str] | None = None,
    metadata: dict | None = None,
    column_name: str | None = None,
    quality_dimension: QualityDimension | None = None,
    skip: bool = False,
)
def test_function(df: pd.DataFrame) -> Any:
    # Your test logic
    return value  # Should match one of expected values

​
Parameters

ParameterTypeRequiredDefaultDescription
namestrYes-Test name
expectedAny | list[Any]Yes-Expected value(s) - can be single value or list
allow_noneboolNoFalseWhether to allow None values
severitystrNo"ERROR"Test severity
descriptionstrNoNoneTest description
column_namestrNoNoneColumn being tested
tags, owners, metadata, quality_dimension, skip-No-Same as @boolean_test

​
Example

@expected_values(
    name="country_count",
    expected=2,
    severity="ERROR",
    description="Should have exactly 2 countries",
    column_name="country",
)
def count_unique_countries(df: pd.DataFrame) -> int:
    return df["country"].nunique()

​
@row_count

Tests that return a Sized object (DataFrame, list, etc.) to check row count.

​
Signature

@row_count(
    name: str,
    min: int | None = None,
    max: int | None = None,
    severity: str | TestSeverity = "ERROR",
    description: str | None = None,
    tags: list[str] | None = None,
    owners: list[str] | None = None,
    metadata: dict | None = None,
    skip: bool = False,
)
def test_function(df: pd.DataFrame) -> Sized:
    # Your test logic - return DataFrame, list, etc.
    return df  # or any object with __len__

​
Parameters

ParameterTypeRequiredDefaultDescription
namestrYes-Test name
minintNoNoneMinimum expected row count (inclusive)
maxintNoNoneMaximum expected row count (inclusive)
severitystrNo"ERROR"Test severity
descriptionstrNoNoneTest description
tags, owners, metadata, skip-No-Same as @boolean_test

​
Example

@row_count(
    name="user_count_range",
    min=1,
    max=1000000,
    severity="WARNING",
    description="Validate user count is within expected range",
)
def get_users_df(df: pd.DataFrame) -> pd.DataFrame:
    """Return the dataframe - decorator calls len() on it."""
    return df

​
Common Parameters

All decorators support these common parameters:
  • name (required): Unique test name
  • severity: "ERROR" or "WARNING" (default: "ERROR")
  • description: Human-readable test description
  • tags: List of tags for categorization
  • owners: List of owner emails/usernames
  • metadata: Dictionary of additional metadata
  • skip: Boolean to skip the test

​
Return Types

  • @boolean_test: Must return bool
  • @expected_range: Must return numeric value (int or float)
  • @expected_values: Can return any type that can be compared
  • @row_count: Must return a Sized object (has __len__ method)