Test Decorators Reference

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

Parameter	Type	Required	Default	Description
name	str	Yes	-	Test name
severity	str	No	"ERROR"	Test severity: "ERROR" or "WARNING"
description	str	No	None	Test description
column_name	str	No	None	Column being tested (for column-level tests)
tags	list[str]	No	None	List of tags
owners	list[str]	No	None	List of owners
metadata	dict	No	None	Additional metadata
quality_dimension	QualityDimension	No	None	Quality dimension (defaults to VALIDITY)
skip	bool	No	False	Whether 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

Parameter	Type	Required	Default	Description
name	str	Yes	-	Test name
min	float	No	None	Minimum expected value (inclusive)
max	float	No	None	Maximum 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

Parameter	Type	Required	Default	Description
name	str	Yes	-	Test name
expected	Any | list[Any]	Yes	-	Expected value(s) - can be single value or list
allow_none	bool	No	False	Whether 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

Parameter	Type	Required	Default	Description
name	str	Yes	-	Test name
min	int	No	None	Minimum expected row count (inclusive)
max	int	No	None	Maximum 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)

Related Documentation

• Quickstart - Get started with test decorators
• API Reference - Overview of the SDK API
• Table Assets - Register tables and views in your data warehouse