ploosh.

Documentation

Python API — execute_cases()

The execute_cases() function is the main entry point for running Ploosh programmatically from Python, typically in notebooks (Microsoft Fabric, Databricks) or custom scripts.

Import

from ploosh import execute_cases

Signature

execute_cases(
    cases=None,
    connections=None,
    spark=None,
    spark_session=None,
    filter=None,
    path_output=None,
    variables=None,
    workers=1,
)

Parameters

ParameterTypeDefaultDescription
casesstringPath to the folder containing test case YAML files
connectionsstringPath to the connections YAML file
sparkstringSet to "true" to enable Spark mode
sparksessionSparkSessionExisting PySpark SparkSession to use
filterstringGlob pattern to filter test case files (e.g. "*.yaml")
pathoutputstringPath to the output folder for results
variablesdictDictionary of custom parameter values
workersint1Number of parallel workers used to process test cases (1 = sequential)

Examples

Basic usage

from ploosh import execute_cases
execute_cases(
    cases="test_cases",
    connections="connections.yml"
)

Microsoft Fabric

from ploosh import execute_cases
execute_cases(
    cases="/lakehouse/default/Files/ploosh_cases",
    connections="/lakehouse/default/Files/ploosh_connections.yaml",
    spark_session=spark,
    pathoutput="/lakehouse/default/Files/plooshoutputs"
)

Databricks

from ploosh import execute_cases
execute_cases(
    cases="/Workspace/Shared/cases",
    connections="/Workspace/Shared/connections.yaml",
    spark_session=spark,
    path_output="/Workspace/Shared/output"
)

With variables

from ploosh import execute_cases
execute_cases(
    cases="test_cases",
    connections="connections.yml",
    variables={
        "dbpassword": "mysecret",
        "schema": "production"
    }
)

With filter

from ploosh import execute_cases
execute_cases(
    cases="test_cases",
    connections="connections.yml",
    filter="quality_*.yaml"
)

Parallel execution

from ploosh import execute_cases
execute_cases(
    cases="test_cases",
    connections="connections.yml",
    workers=4
)

Behavior

  • If spark_session is provided, Ploosh uses it for Spark connectors
  • If spark="true" and no spark_session is given, Ploosh creates a local SparkSession
  • With workers > 1, test cases are processed concurrently in a thread pool; workers=1 (default) runs them sequentially
  • Results are exported to {pathoutput}/{format}/ (e.g. output/json/testresults.json)
  • The function prints status to stdout in real-time
  • By default, raises SystemExit(1) if any test fails. Use --failure false from CLI or handle the exit in your code