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)

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

​Import Statement

​@boolean_test

​Signature

​Parameters

​Example

​@expected_range

​Signature

​Parameters

​Example

​@expected_values

​Signature

​Parameters

​Example

​@row_count

​Signature

​Parameters

​Example

​Common Parameters

​Return Types

​Related Documentation

Import Statement

@boolean_test

Signature

Parameters

Example

@expected_range

Signature

Parameters

Example

@expected_values

Signature

Parameters

Example

@row_count

Signature

Parameters

Example

Common Parameters

Return Types

Related Documentation