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)
skipboolNoFalseWhether to skip this test. Useful if you want the test to appear in Elementary Cloud, but you don’t want to execute it in this run.

​
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. They can also return a list of numeric values or a pandas Series.

​
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 | list[float] | pd.Series:
    # Your test logic
    return df["age"].mean()  # Numeric value
    # return [1, 2, 3]  # Numeric values
    # return df["age"]  # pandas Series

​
Parameters

ParameterTypeRequiredDefaultDescription
namestrYes-Test name
minfloatNoNoneMinimum expected value (inclusive)
maxfloatNoNoneMaximum expected value (inclusive)
severity, description, column_name, 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 (or values) 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
severity, description, column_name, 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)
severity, 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; the 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)