DeepEval

Overview

DeepEval is an open-source framework for testing the outputs of applications built on large language models. It treats an LLM response the way a normal test suite treats a function result. You write a test case with an input, the actual output and sometimes the expected output or retrieved context. You attach one or more metrics, and each metric returns a score between zero and one. If the score falls below a threshold, the test fails. This lets teams catch regressions in prompts, retrieval pipelines and agents before they reach users.

The key idea is that "does the answer look right" becomes a repeatable, automated check. Many DeepEval metrics use a second model as a judge, which is the pattern described under LLM-as-judge. Others use plain code or statistics. DeepEval fits naturally beside pytest, and it sits in the same family as Ragas, TruLens and Promptfoo. For teams that use language models around tabular data, such as explaining a prediction or answering questions over a table, it gives a disciplined way to check that those answers stay faithful to the data.

What it is

A test framework for model outputs

Ordinary software has a long tradition of unit tests. A function returns a value, and you assert that the value equals what you expect. LLM outputs break this habit because the text varies from run to run, and two different sentences can both be correct. DeepEval replaces the exact-match assertion with a metric. A metric measures a quality such as relevance, faithfulness to a source, or absence of harmful content. The assertion becomes "this quality score must be at least this threshold".

An everyday analogy is a teacher marking essays with a rubric. The teacher does not compare each essay to one perfect answer. The teacher scores clarity, accuracy and structure on a scale and decides whether the work passes. DeepEval is a rubric that runs automatically on every change.

The main building blocks

• A test case holds the data for one check: the user input, the model output, and optional fields such as expected output and retrieval context.
• A metric computes a score for a test case and explains it in text.
• A threshold turns the score into pass or fail.
• A dataset is a collection of test cases, often called a golden set.
• A test run executes many test cases and reports results.
• A synthesizer can generate test cases from documents so you do not write all of them by hand.

Where it runs

DeepEval is a Python library. You can run it from the command line through a pytest-style runner, or call its evaluation functions inside a script or notebook. It also integrates with continuous integration, so every pull request can run the suite. Optional hosted dashboards exist for viewing runs over time, but the core library works locally without them.

What it is not

DeepEval does not train models and does not serve them. It does not replace human review for high-stakes decisions. It also is not a tracing or observability tool, although it can work alongside one. See tracing for that role. Finally, it is not a benchmark of general model quality. It checks your application on your data.

Where it came from

The testing gap in LLM work

When language model applications spread, teams found that changing a prompt could quietly make some answers worse. Manual checking did not scale. Classic metrics from natural language processing, such as n-gram overlap scores, correlate poorly with human judgement for open-ended text. At the same time, research showed that a strong language model can grade outputs with reasonable agreement with people, as discussed in work on judging models with models. These two trends set the stage for tools that package model-graded and code-graded metrics into a testing workflow.

Research ideas behind the metrics

DeepEval's metrics draw on public ideas rather than a single invention:

• Model-graded evaluation, where a capable model scores another model's output against criteria.
• Question-and-answer style checks for factual consistency, where claims are extracted from an answer and verified against a source.
• Retrieval metrics, which look at whether the retrieved context was relevant and whether the answer used it.
• Rubric-based scoring with step-by-step reasoning before the score, often called G-Eval style.
• Safety checks such as toxicity and bias detection.

For the wider field of evaluation, see the pages on evals and regression boards.

Open source and community growth

The project is released as open source and grew through community use in retrieval-augmented generation and agent work. It follows the pytest convention on purpose, because developers already know how to write and run such tests. Exact version history and feature dates change often, so check the project documentation for the current list of metrics.

How it works

Step 1: describe the thing you are testing

Pick one behaviour. For example, "the assistant answers questions about a table without inventing numbers". Write down what good looks like. This becomes the metric choice and the threshold.

An analogy: before a driving test the examiner decides what counts as passing. Staying in lane, signalling, stopping at lights. DeepEval needs the same kind of decision from you.

Step 2: build test cases

Each test case captures one interaction. A minimal case has an input and an actual output. For retrieval systems you also pass the retrieved text, usually called context. For tasks with a known answer you pass an expected output.

You can collect cases from real logs, write them by hand, or generate them from source documents. Real logs give the best realism. Hand-written cases cover edge conditions. Generated cases give breadth quickly.

Step 3: choose metrics

DeepEval ships many ready-made metrics. They fall into groups:

• Answer quality: relevance, correctness against an expected output, and custom criteria written in plain language.
• Retrieval quality: contextual precision, recall and relevance, which check whether the retriever found the right passages in a useful order.
• Grounding: faithfulness or hallucination checks, which ask whether every claim in the answer is supported by the context.
• Safety: toxicity, bias and similar checks.
• Agent and tool use: whether the right tool was chosen, with the right arguments, and whether the task finished.
• Conversation: whether a multi-turn chat stays on topic and keeps its facts straight.

You can also write a custom metric when none fits.

Step 4: run the judge

For model-graded metrics, DeepEval sends the test case and a scoring prompt to a judge model. The judge reasons about the output and returns a score and a reason. Some metrics first break the answer into small statements, then check each statement. The final score is the share of statements that pass. This is like a proofreader who underlines every claim and checks each against the source.

You choose which model acts as judge. It can be a hosted model or a local one. Using a local judge keeps data in-house, at the cost of judge quality.

Step 5: compare to a threshold

Every metric has a threshold. If the score is at or above it, the metric passes. A test case passes only if all attached metrics pass. The run then reports totals, and a failing run returns a non-zero exit code so a CI system can block a merge.

Step 6: read the reasons and fix

The score alone is not enough. DeepEval stores a short explanation for each result. Read the failures, find the pattern, fix the prompt or the retriever, and rerun. Save fixed failures as permanent cases so they cannot silently return.

Step 7: repeat on every change

The value comes from repetition. Run the suite when prompts change, when models are swapped, when retrieval settings change and on a schedule. Track scores over time to spot slow drift.

A note on cost and speed

Model-graded metrics make extra model calls, sometimes several per test case. That adds cost and latency. Teams usually keep a small, fast suite for every commit and a larger suite for nightly runs. See cost and latency budgets for planning.

Key concepts and terms

A worked example

Scenario

Suppose a small assistant answers questions about a table of monthly sales, using retrieved rows as context. We want to test two things: the answer must address the question, and every number in it must be supported by the retrieved rows.

Code

The sketch below shows the typical shape. Class and argument names follow the library's conventions, but check the current documentation because signatures can change between versions.

# test_sales_assistant.py
from deepeval import assert_test
from deepeval.test_case import LLMTestCase
from deepeval.metrics import AnswerRelevancyMetric, FaithfulnessMetric


def test_monthly_total():
    context = [
        "region=north; month=2025-01; sales=1200",
        "region=north; month=2025-02; sales=1500",
    ]
    case = LLMTestCase(
        input="What were total north sales for January and February?",
        actual_output="North sales were 2700 across the two months.",
        retrieval_context=context,
    )
    relevancy = AnswerRelevancyMetric(threshold=0.7)
    faithful = FaithfulnessMetric(threshold=0.8)
    assert_test(case, [relevancy, faithful])

You would run this file with the DeepEval command-line runner, or with plain pytest. In the real application, actual_output comes from calling your assistant rather than a hard-coded string.

What happens inside

1. The relevancy metric asks the judge to split the answer into statements and decide whether each addresses the question. "North sales were 2700 across the two months" addresses it, so the score is high.
2. The faithfulness metric extracts claims from the answer. The claim "total is 2700" is checked against the context. Because 1200 plus 1500 equals 2700, the judge marks it supported.
3. Both scores clear their thresholds, so the test passes.

A failing variant

Change the output to "North sales were 3100". Faithfulness extracts the claim "total is 3100", finds no support in the context, and the score drops. The test fails with a reason such as "the claim about 3100 is not supported by the context". That is the signal you want: the app invented a number.

Running a batch

For many cases you build a dataset and loop over it.

import pytest
from deepeval import assert_test
from deepeval.dataset import EvaluationDataset
from deepeval.test_case import LLMTestCase
from deepeval.metrics import FaithfulnessMetric

dataset = EvaluationDataset(test_cases=[
    LLMTestCase(
        input="Which region had the highest sales in March?",
        actual_output=ask_assistant("Which region had the highest sales in March?"),
        retrieval_context=retrieve("highest sales March"),
    ),
])

@pytest.mark.parametrize("case", dataset)
def test_faithfulness(case):
    assert_test(case, [FaithfulnessMetric(threshold=0.8)])

Here ask_assistant and retrieve are your own functions. A tiny golden set of fifty to a few hundred cases is usually enough to start.

Custom criteria

When none of the built-in metrics matches, you can write a rubric.

from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCaseParams

units_metric = GEval(
    name="Units stated",
    criteria="The answer must state the unit or currency for every number it reports.",
    evaluation_params=[LLMTestCaseParams.ACTUAL_OUTPUT],
    threshold=0.7,
)

This is useful for house rules such as "never give a number without its unit".

Reading results

A good habit is to print the score and the reason for each failure. Group failures by cause: wrong retrieval, ignored context, formatting, unsafe content. Fix the largest group first.

Strengths and limitations

Strengths

• It brings familiar testing habits to LLM work. Developers already know how to read a failing test.
• It integrates with pytest and continuous integration.
• It offers many ready-made metrics for retrieval, grounding, safety, agents and conversations.
• It lets you write custom rubrics in plain language.
• It can generate test data from documents.
• It supports component-level checks, so you can test a retriever apart from a generator.
• It works with different judge models, including local ones.
• Reasons attached to scores make debugging faster.

Limitations

• Judge models are imperfect. They can be biased toward longer answers, toward their own style, or toward the first option presented. Scores are estimates, not truth.
• Scores can vary between runs. Setting low temperature and caching help but do not remove all noise.
• Model-graded metrics cost money and time.
• Thresholds are arbitrary until you calibrate them against human labels.
• A passing suite does not prove safety. It proves only that the covered cases behave.
• Metrics designed for text do not check numeric correctness unless the numbers appear in the text and the judge does the arithmetic. For exact numeric checks, write ordinary code assertions.
• Version changes can alter metric prompts and therefore scores, which complicates long-term trend lines.

When the limits bite

Take a team that sets a faithfulness threshold of 0.8 and sees a gradual slide from 0.86 to 0.82 over a month. The change may be real, or it may come from a judge model update. To tell, keep a frozen set of human-labelled cases and check judge agreement on it regularly.

How it compares with alternatives

A simple decision path

• If you want tests that live in the repository and block merges, DeepEval fits well.
• If your system is mainly retrieval-augmented generation and you want a focused metric set, consider Ragas, or use both.
• If you need to compare many prompts across many models in a table, Promptfoo is convenient.
• If you need production tracing as the first priority, start with a tracing platform and add DeepEval for tests.
• For anything with a single right answer, use plain assertions. Do not use a judge where code will do.

These tools overlap and can be combined. The best choice is often the one your team will actually run on every change.

Role in tabular foundation models

Where evaluation fits

Tabular foundation models learn from raw tables. They read rows and columns, handle mixed types such as numbers, categories, dates and text, cope with missing values, and often work without column names. Many are pre-trained on large collections of synthetic tables, sometimes with real tables as well, and then predict for a new table through in-context learning, which means the labelled rows are given as context at inference time and no gradient update is needed. See /model/architecture for how such systems are built and TabPFN for one well-known example.

DeepEval does not sit inside that model. It sits around it. Its role is to test the language model layer that often surrounds a tabular model: the part that explains predictions, answers questions about a dataset, writes a summary of a column, or acts as an agent that calls tabular tools.

Testing explanations of predictions

A tabular model returns numbers: a class probability, a regression value, an imputed cell. A language model may turn that into a sentence for a person. DeepEval can check that the sentence is faithful to the numbers. The context is the model output and the feature values. The metric asks whether every claim in the explanation is supported. This catches a common failure: a fluent paragraph that invents a reason.

Testing agents that call tabular tools

An agent may call a tabular model as a tool: "predict churn for this customer", "impute the missing cells", "flag anomalous rows". DeepEval's agent metrics can check that the agent picked the right tool, passed well-formed arguments and used the result correctly. A test might assert that when a user asks about unusual transactions, the agent calls the anomaly detection tool rather than the classifier.

Testing question answering over tables

Natural-language questions over a table can be answered through retrieval of rows, through generated queries, or through a tabular model. In each case, you can build a golden set of questions with known answers, run the pipeline, and score correctness, grounding and relevance. For the numeric part, add exact assertions in code, because arithmetic is better checked by arithmetic than by a judge.

Testing semantic and sector classification

Some pipelines assign a semantic type or sector to a column or a record, for example deciding that a column holds postal codes or that a company belongs to a given industry. When a language model helps with this step, DeepEval can score its labels against a human-labelled set using a correctness metric or a custom rubric. For purely tabular classifiers, ordinary accuracy metrics on a hold-out set are more appropriate, as covered in /model/benchmarks.

Imputation and anomaly detection narratives

When a model fills missing cells or flags anomalies, a language layer may justify the choice in words. DeepEval can test that the narrative matches the actual numbers, that it does not claim certainty beyond what the model reported, and that it mentions the imputed fields. The imputation itself should be evaluated with error measures against masked ground truth, not with a judge.

Continual learning and drift

When a tabular model is updated with new data, the surrounding assistant should still behave well. A DeepEval suite acts as a guard: run it before and after each model update to confirm explanations, tool calls and answers stay within thresholds. This pairs with data-side drift checks, and with regression boards that track results across versions.

Retrieval of similar rows

Some tabular systems retrieve similar rows from a vector store to supply context for prediction. The contextual precision and recall ideas in DeepEval map onto this: are the retrieved rows the right neighbours, and are they ordered well? You can adapt those metrics, or write custom ones, to score row retrieval. Vector stores such as Milvus, Qdrant and pgvector are common back ends for this retrieval.

Honest limits of this role

DeepEval is a text-evaluation tool. It cannot tell you whether a tabular model's probabilities are calibrated, whether its predictions are accurate on a hold-out set, or whether a table was cleaned correctly. Use the standard methods in /model/benchmarks for that. Treat DeepEval as the guard for the language layer, not for the numeric core.

Practical guidance and best practices

Start small and real

Begin with twenty to fifty real examples drawn from logs or from experts. Add cases whenever a bug is found. A small trusted set beats a large noisy one.

Pick few metrics per case

Each added metric adds cost and noise. Use the two or three that map to real risks. For a table assistant, that may be faithfulness, relevancy and one custom rubric.

Calibrate the judge

Take a sample of cases, label them by hand, and compare to the judge's scores. If agreement is poor, change the judge model, change the rubric, or switch to a code check. Repeat the calibration when you change judge models.

Set thresholds from data

Do not pick 0.8 because it looks nice. Look at the score distribution for known good and known bad answers and place the threshold between them. Revisit it as the system improves.

Separate component tests from end-to-end tests

Test the retriever with retrieval metrics. Test the generator with fixed context. Then test the whole pipeline. When an end-to-end test fails, the component tests tell you where.

Keep deterministic checks deterministic

Use plain assertions for format, schema validity, required fields, numeric equality and tool names. Reserve judge metrics for fuzzy qualities.

Control randomness

Use low temperature for the system under test and for the judge where possible. Run flaky cases several times and use the average or majority.

Version everything

Record the prompt version, model version, judge version, metric version and dataset version with each run. Without this, score changes cannot be explained.

Run in layers

• On every commit: a small fast suite with a cheap judge.
• Nightly: a larger suite with a stronger judge.
• Before release: the full suite plus a human review of a sample.

Protect data

Test cases often contain real user text. Remove personal data before storing it, use local judges for sensitive material, and keep access controls on datasets. See guardrails for runtime protections that complement testing.

Connect to a bigger picture

Evaluation is one part of a loop that includes tracing, monitoring and human feedback. Use tracing to find failing production cases, add them to the dataset, and let the suite protect against repeats.

Designing a golden set step by step

A golden set is the heart of the suite, so it deserves care.

1. List the user intents your application must handle, such as lookups, comparisons, summaries and refusals.
2. For each intent, collect real examples from logs, support tickets or expert interviews.
3. Add edge cases: empty tables, very long values, mixed units, missing cells, ambiguous questions.
4. Add adversarial cases: attempts to make the assistant reveal hidden instructions or ignore its context.
5. Record the expected behaviour in a sentence, even when you do not have one exact answer.
6. Have two people label a sample, and resolve their disagreements. Disagreement shows where the rubric is vague.
7. Freeze a version of the set and give it an identifier.

An analogy: a golden set is like the answer key and question bank a school uses year after year. If the bank is thin, students can pass without learning. If the key is wrong, good students are marked down.

A simple release gate

Many teams turn the suite into a release gate with a short table of rules.

Use averages over the set and also a minimum per important category, so a strong average cannot hide a broken intent.

Continuous integration sketch

A CI job usually installs the package, sets the judge credentials from a secret store, and runs the suite. The YAML below is a generic sketch with placeholder names.

name: llm-tests
on: [pull_request]
jobs:
  evaluate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install -r requirements.txt
      - run: deepeval test run tests/test_sales_assistant.py
        env:
          JUDGE_API_KEY: ${{ secrets.JUDGE_API_KEY }}
          APP_BASE_URL: https://app.example.internal

Keep the job fast. Cache the dependencies, run a small suite, and move the heavy suite to a nightly schedule.

Mixing judge checks with exact checks

A good test often uses both kinds of check in one function. First assert the exact things, then call the judge.

import json
from deepeval import assert_test
from deepeval.test_case import LLMTestCase
from deepeval.metrics import FaithfulnessMetric


def test_structured_answer():
    raw = ask_assistant_json("Total north sales for Q1?")
    data = json.loads(raw)                      # exact: valid JSON
    assert set(data) == {"total", "unit", "note"}  # exact: required keys
    assert data["total"] == 4300                # exact: arithmetic from the table

    case = LLMTestCase(
        input="Total north sales for Q1?",
        actual_output=data["note"],
        retrieval_context=retrieve("north Q1 sales"),
    )
    assert_test(case, [FaithfulnessMetric(threshold=0.8)])  # fuzzy: the prose

The exact lines never flake. The judge only looks at the free-text part, which keeps cost and noise low.

Handling flaky scores

Even with careful settings a judge can wobble by a few hundredths. Three habits help.

• Run each borderline case three times and use the median.
• Leave a small margin between the typical score and the threshold, so noise does not flip results.
• Keep a log of scores per case. A case that flips often is a bad case or a vague rubric, and should be rewritten.

Reading a failing run

Imagine a run where faithfulness fails on a subset of cases. A useful triage looks like this.

This kind of table turns a red build into a clear to-do list.

Evaluating over time

Keep results in a simple table that includes the date, the prompt version, the model version, the dataset version and each metric average. Plot the averages. A step change lines up with a change you made. A slow slope often points to data drift or a judge update. Without these records, you can only argue about whether things got worse.

Common mistakes

• Using a judge for everything, including checks that plain code could do exactly.
• Trusting scores without calibrating them against human labels.
• Testing only happy-path examples and missing edge cases.
• Letting the system under test and the judge be the same model with the same biases and no cross-check.
• Changing the judge model or metric version and reading the score change as a quality change.
• Setting a single global threshold for every metric and every task.
• Putting secrets or raw personal data into stored test cases.
• Running the full expensive suite on every commit until the team stops running it.
• Ignoring the reasons and chasing the score.
• Never retiring or updating cases, so the suite no longer matches real traffic.
• Treating a green suite as proof of safety.
• Writing rubrics that are vague, such as "the answer is good", instead of concrete criteria.

Frequently asked questions

What is DeepEval used for?

DeepEval is used to test the outputs of applications built on language models, such as chatbots, retrieval-augmented generation systems and agents. You write test cases, attach metrics that score qualities like relevance and faithfulness, and fail the build when scores drop below thresholds. This catches regressions when prompts, models or retrieval settings change.

How is DeepEval different from pytest?

Pytest is a general test runner that checks exact assertions in code. DeepEval builds on the same style but adds metrics suited to language output, where exact matching does not work. Many DeepEval metrics call a judge model to score a quality between zero and one. You can use both together, with pytest assertions for deterministic parts and DeepEval metrics for fuzzy qualities.

Does DeepEval need an internet connection or a paid model?

Not necessarily. Many metrics use a judge model, and that judge can be a hosted service or a model you run locally. A local judge keeps data on your own machines but may score less reliably than a stronger hosted model. The framework itself runs as a Python library on your machine, so the need for network access depends on the judge you choose.

How reliable are LLM-as-judge scores?

They are useful but imperfect. Judges can prefer longer answers, favour their own style and vary between runs. Reliability improves when rubrics are concrete, when the judge reasons step by step, and when you calibrate scores against a set of human-labelled examples. Treat scores as estimates and watch trends rather than single numbers.

Can DeepEval evaluate tabular models directly?

No. DeepEval evaluates text and tool-use behaviour, not the numeric accuracy of tabular predictors. For a tabular model you should use hold-out metrics, calibration checks and benchmark comparisons. DeepEval is helpful for the language layer around such a model, for example the explanations, the question answering and the agent that calls it.

How many test cases do I need?

Start with a few dozen well-chosen cases and grow the set as you find failures. A few hundred cases often give stable signals for one application. More important than count is coverage: include common questions, rare edge cases, adversarial inputs and every past bug that has been fixed.

How do I choose a threshold?

Score a set of answers that you know are good and a set that you know are bad. Pick a threshold that separates them well, then adjust based on how costly false alarms and missed failures are for you. Recheck the threshold when you change the judge model, the metric version or the system under test.

Can I test agents with DeepEval?

Yes. It includes metrics for tool selection, argument quality and task completion, and it supports tracing components so you can test steps inside an agent run. You can also write custom metrics for your own tools. For agents that call tabular models, check that the right tool was chosen and that its result was reported faithfully.

What should I do when a metric fails?

Read the stored reason first, then look at the retrieved context and the full output. Decide whether the cause is retrieval, generation, formatting or an overly strict metric. Fix the cause, add the case to your golden set if it is new, and rerun the whole suite to check that nothing else broke.

Is DeepEval a replacement for human review?

No. Automated metrics scale well and catch many regressions, but they miss subtle issues and share the biases of the judge model. Use DeepEval for continuous screening and use human review for calibration, for new features and for high-stakes outputs.

Glossary

• Answer relevancy: A metric for how directly an answer addresses the question.
• Assertion: A check that must hold for a test to pass.
• Calibration: Comparing automated scores with human labels to learn how far to trust them.
• Context: Source passages supplied to a model so that its answer can be grounded.
• Contextual precision: A retrieval metric for how well relevant passages are ranked first.
• Contextual recall: A retrieval metric for how much of the needed information was retrieved.
• Continuous integration: Automatic running of tests on every code change.
• Faithfulness: The share of an answer's claims that the context supports.
• G-Eval style metric: A rubric-based metric where a judge reasons through criteria before scoring.
• Golden set: A trusted collection of test cases used as a baseline.
• Hallucination: Output that is not supported by the source or by facts.
• Judge model: A model used to grade another model's output.
• Metric: A function that returns a score for a quality of an output.
• Regression: A drop in quality caused by a change.
• Synthetic test data: Test cases generated automatically from documents.
• Test case: One recorded interaction used for checking.
• Threshold: The minimum score that counts as a pass.
• Tracing: Recording each step of an application run for inspection.

Summary

DeepEval is an open-source, pytest-style framework that tests language model applications with metrics instead of exact matches. You create test cases, attach metrics for relevance, grounding, safety or tool use, set thresholds, and run the suite on every change so regressions are caught early. Its model-graded metrics are powerful but imperfect, so calibrate them against human labels and keep exact checks in plain code.

For tabular foundation models, DeepEval guards the language layer around the numeric core: explanations of predictions, question answering over tables, and agents that call tabular tools. It does not measure prediction accuracy, calibration or imputation error, which belong to standard benchmarks described at /model/benchmarks. Used together with Ragas, Promptfoo and tracing, it forms a practical safety net as models and data keep changing. For the research context, see /model/research.

Related

It belongs to RAG in my stack, under LLMs, retrieval, and evaluation. Others in the same group: