Your First Test

Write and run your first Giskard Checks test in under ten minutes — no API key or LLM required.

What you’ll build

By the end of this tutorial you will have a ScenarioResult that shows a passing check against a pure-Python function. This gives you the full test-writing loop — define a scenario, run it, inspect the result — before introducing any external services.

Prerequisites

If you haven’t installed Giskard Checks yet, see the Installation guide first.

Write a function to test

You need something to test. Create a simple greeting function:

No LLM, no API calls — just a Python function that returns a predictable string. Starting with a pure function removes all external dependencies so you can focus entirely on the testing mechanics.

def greet(name: str) -> str:
    return f"Hello, {name}!"

Create a scenario

A Scenario chains together one or more interactions and checks. Each .interact() call provides an input and the callable that produces the output. Each .check() call asserts something about the result.

Equals compares the value at the trace path trace.last.outputs against expected_value. If they match the check passes; otherwise it fails. Notice that trace.last.outputs is a dot-separated path — this is how all built-in checks address values stored in the trace, so you’ll see this pattern throughout the documentation.

from giskard.checks import Scenario, Equals

scenario = (
    Scenario("greet_alice")
    .interact(
        inputs="Alice",
        outputs=lambda inputs: greet(inputs),
    )
    .check(
        Equals(
            name="correct_greeting",
            expected_value="Hello, Alice!",
            target_key="trace.last.outputs",
        )
    )
)

Output

Thank you for using Giskard open-source! 🐢 🙏 Giskard Enterprise adds deeper agent scans, audit reports with remediation guidance, test review interfaces for root-cause analysis & human feedback integration, and team collaboration — with flexible pricing. Learn more: https://giskard.ai

Run it

In a Jupyter notebook

Scenarios are async, so in a notebook you can await them directly.

result = await scenario.run()
result.print_report()

Output

──────────────────────────────────────────────────── ✅ PASSED ────────────────────────────────────────────────────
correct_greeting        PASS    
────────────────────────────────────────────────────── Trace ──────────────────────────────────────────────────────
────────────────────────────────────────────────── Interaction 1 ──────────────────────────────────────────────────
Inputs: 'Alice'
Outputs: 'Hello, Alice!'
─────────────────────────────────────────── 1 step in 18ms | runs: 1/1 ────────────────────────────────────────────

In a Python script

Outside a notebook there is no running event loop, so you wrap the call with asyncio.run.

import asyncio
from giskard.checks import Scenario, Equals


def greet(name: str) -> str:
    return f"Hello, {name}!"


scenario = (
    Scenario("greet_alice")
    .interact(
        inputs="Alice",
        outputs=lambda inputs: greet(inputs),
    )
    .check(
        Equals(
            name="correct_greeting",
            expected_value="Hello, Alice!",
            target_key="trace.last.outputs",
        )
    )
)

result = asyncio.run(scenario.run())
result.print_report()

Output

──────────────────────────────────────────────────── ✅ PASSED ────────────────────────────────────────────────────
correct_greeting        PASS    
────────────────────────────────────────────────────── Trace ──────────────────────────────────────────────────────
────────────────────────────────────────────────── Interaction 1 ──────────────────────────────────────────────────
Inputs: 'Alice'
Outputs: 'Hello, Alice!'
──────────────────────────────────────────── 1 step in 5ms | runs: 1/1 ────────────────────────────────────────────

What a failing test looks like

Your function always returns the expected string, so the test always passes. To see what a failure looks like, change expected_value to something that won’t match:

scenario = (
    Scenario("greet_alice")
    .interact(
        inputs="Alice",
        outputs=lambda inputs: greet(inputs),
    )
    .check(
        Equals(
            name="correct_greeting",
            expected_value="Hi, Alice!",  # wrong — greet() returns "Hello, Alice!"
            target_key="trace.last.outputs",
        )
    )
)

result = await scenario.run()
result.print_report()

Output

──────────────────────────────────────────────────── ❌ FAILED ────────────────────────────────────────────────────
correct_greeting        FAIL    Expected value equal to 'Hi, Alice!' but got 'Hello, Alice!'
────────────────────────────────────────────────────── Trace ──────────────────────────────────────────────────────
────────────────────────────────────────────────── Interaction 1 ──────────────────────────────────────────────────
Inputs: 'Alice'
Outputs: 'Hello, Alice!'
─────────────────────────────────────────── 1 step in 96ms | runs: 1/1 ────────────────────────────────────────────

Failures are descriptive — the message tells you the expected vs. actual value.

Reset expected_value back to "Hello, Alice!" before continuing.

Next step

A real AI system is less predictable than a pure Python function — the next tutorial shows you how to configure a generator and test an actual LLM call:

Your First LLM Call