> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autoblocks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Quick Start

> Get started with the Autoblocks Testing SDK for Python.

## Overview

Autoblocks Testing enables you to declaratively define tests for your LLM application and execute them either locally
or in a CI/CD pipeline. Your tests can exist in a standalone script or be executed as part of a larger test framework.

```python
run_test_suite(
  id="my-test-suite",
  test_cases=gen_test_cases(),
  evaluators=[HasAllSubstrings(), IsFriendly()],
  fn=test_fn,
)
```

## Getting Started

### Install the SDK

```bash
poetry add autoblocksai
# or
pip install autoblocksai
```

### Define your test case schema

Your test case schema should contain all of the properties
necessary to run your test function and to then make assertions
on the output via your evaluators.
This schema can be anything you want in order to facilitate testing your application.

```python
import dataclasses

from autoblocks.testing.models import BaseTestCase
from autoblocks.testing.util import md5

@dataclasses.dataclass
class MyTestCase(BaseTestCase):
    """
    A test case can be any class that subclasses BaseTestCase.

    This example is a dataclass, but it could also be a pydantic model,
    plain Python class, etc.
    """
    input: str
    expected_substrings: list[str]

    def hash(self) -> str:
        """
        This hash serves as a unique identifier for a test case throughout its lifetime.

        Required to be implemented by subclasses of BaseTestCase.
        """
        return md5(self.input)
```

### Implement a function to test

This function should take an instance of a test case and return an output.
The function can be synchronous or asynchronous and the output can be anything: a string, a number, a complex object, etc.

For this example, we are splitting the test case's `input` property on its hyphens and randomly discarding some of the substrings
to simulate failures on the `has-all-substrings` evaluator.

```python
import random
import asyncio

async def test_fn(test_case: MyTestCase) -> str:
    """ This could also be a synchronous function. """
    # Simulate doing work
    await asyncio.sleep(random.random())

    substrings = test_case.input.split("-")
    if random.random() < 0.2:
        # Remove a substring randomly. This will cause about 20% of the test cases to fail
        # the "has-all-substrings" evaluator.
        substrings.pop()

    return "-".join(substrings)
```

### Create an evaluator

Evaluators allow you to attach an [`Evaluation`](#reference-evaluation) to a test case's output,
where the output is the result of running the test case through the function you are testing.
Your test suite can have multiple evaluators.
The evaluation method that you implement on the evaluator will have access to both the test case
instance and the output of the test function over the given test case. Your evaluation method
can be synchronous or asynchronous, but it must return an instance of `Evaluation`.

The evaluation must have a score between 0 and 1, and you can optionally attach a
[`Threshold`](#reference-threshold) that describes the range the score must be in in order
to be considered passing. If no threshold is attached, the score is reported and the pass / fail
status is undefined. Evaluations can also have metadata attached to them, which can be useful
for providing additional context when an evaluation fails.

For this example we'll define two evaluators:

```python
import random
import asyncio

from autoblocks.testing.models import BaseTestEvaluator
from autoblocks.testing.models import Evaluation
from autoblocks.testing.models import Threshold

class HasAllSubstrings(BaseTestEvaluator):
    """
    An evaluator is a class that subclasses BaseTestEvaluator.

    It must specify an ID, which is a unique identifier for the evaluator.
    """
    id = "has-all-substrings"

    def evaluate_test_case(self, test_case: MyTestCase, output: str) -> Evaluation:
        """
        Evaluates the output of a test case.

        Required to be implemented by subclasses of BaseTestEvaluator.
        This method can be synchronous or asynchronous.
        """
        missing_substrings = [s for s in test_case.expected_substrings if s not in output]
        score = 0 if missing_substrings else 1
        return Evaluation(
            score=score,
            # If the score is not greater than or equal to 1,
            # this evaluation will be marked as a failure.
            threshold=Threshold(gte=1),
            metadata=dict(
                # Include the missing substrings as metadata
                # so that we can easily see which strings were
                # missing when viewing a failed evaluation
                # in the Autoblocks UI.
                missing_substrings=missing_substrings,
            ),
        )

class IsFriendly(BaseTestEvaluator):
    id = "is-friendly"

    # The maximum number of concurrent calls to `evaluate_test_case` allowed for this evaluator.
    # Useful to avoid rate limiting from external services, such as an LLM provider.
    max_concurrency = 5  

    async def get_score(self, output: str) -> float:
        # Simulate doing work
        await asyncio.sleep(random.random())

        # Simulate a friendliness score, e.g. as determined by an LLM.
        return random.random()

    async def evaluate_test_case(self, test_case: BaseTestCase, output: str) -> Evaluation:
        """
        This can also be an async function. This is useful if you are interacting
        with an external service that requires async calls, such as OpenAI,
        or if the evaluation you are performing could benefit from concurrency.
        """
        score = await self.get_score(output)
        return Evaluation(
            score=score,
            # Evaluations don't need thresholds attached to them.
            # In this case, the evaluation will just consist of the score.
        )
```

<Hint>
  An evaluator can be used across many test suites!
  The recommended approach for this is to create your own abstract class that subclasses `BaseTestEvaluator`
  and implements any shared logic, then subclass that abstract class for each test suite.

  See the [example](https://github.com/autoblocksai/autoblocks-examples/blob/main/Python/testing-sdk/my_project/evaluators/has_substrings.py)
  and the [Python documentation](https://docs.python.org/3/library/abc.html) on abstract classes.
</Hint>

### Create a test suite

We now have all of the pieces necessary to run a test suite.
Below we'll generate some toy test cases in the schema
we defined above, where the input is a random UUID and its
expected substrings are the substrings of the UUID when split
by "-":

```python
import uuid

from autoblocks.testing.v2.run import run_test_suite

def gen_test_cases(n: int) -> list[MyTestCase]:
    test_cases = []
    for _ in range(n):
        random_id = str(uuid.uuid4())
        test_cases.append(
            MyTestCase(
                input=random_id,
                expected_substrings=random_id.split("-"),
            ),
        )
    return test_cases

run_test_suite(
    id="my-test-suite",
    fn=test_fn,
    test_cases=gen_test_cases(400),
    evaluators=[
        HasAllSubstrings(),
        IsFriendly(),
    ],
    # The maximum number of test cases that can be running
    # concurrently through `fn`. Useful to avoid rate limiting
    # from external services, such as an LLM provider.
    max_test_case_concurrency=10,
)
```

### Run the test suite locally

To execute this test suite, first get your **local testing API key** from the [settings page](https://app.autoblocks.ai/settings/api-keys)
and set it as an environment variable:

```bash
export AUTOBLOCKS_V2_API_KEY=...
```

Make sure you've followed our [CLI setup instructions](/cli/setup) and then run the following:

```bash
# Assumes you've saved the above code in a file called run.py
npx autoblocks testing exec -m "my first run" -- python3 run.py
```

The [`autoblocks testing exec`](/cli/commands#testing-exec) command will show the progress of all test suites in your terminal
and also send the results to Autoblocks:

<AutoblocksImage src="/images/testing/quick-start/cli-dots.png" alt="Testing CLI" />

You can view details of the results by clicking on the link displayed in the terminal or by visiting
the [test suites page](https://app.autoblocks.ai/testing/local) in the Autoblocks platform.

## Examples

To see a more complete example, check out our [Python example repository](https://github.com/autoblocksai/autoblocks-examples/tree/main/Python/testing-sdk).