Skip to main content
skill CX Codex

langgraph-testing-evaluation — Claude Code skill for agent tests

langgraph-testing-evaluation — a skill for Claude Code tests and evaluates LangGraph and LangChain agents. It supports test scaffolds, trajectory scoring, dataset runs, and version comparisons.

MIT ★ 106 updated 2026-11-11

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add soba-labs/langchain-agent-skills --skill langgraph-testing-evaluation -a claude-code
Open on GitHub

What langgraph-testing-evaluation does

This skill helps build unit and integration tests for LangGraph and LangChain agents, generate starter test files, and mock LLM or tool behavior. Its package includes Python and JavaScript/TypeScript scripts, a pytest template, and a sample dataset.

Trajectory checks can compare an agent run with a reference or use an LLM judge. Other scripts run dataset evaluations through LangSmith and compare two agent versions on quality and latency. Dataset evaluation through LangSmith requires that service.

Tests can set regression thresholds in CI, while traces and experiment results help inspect failures. The workflow recommends keeping real-model checks to a smaller explicit suite and mocking LLM and tool input/output for repeatable tests.

What it helps with

  • generate starter tests for an agent graph
  • check routing between graph nodes
  • score an agent trajectory against a reference
  • evaluate a dataset with LangSmith
  • compare quality and latency across agent versions

Example prompts for the agent

  • Generate pytest starter tests for the graph my_agent:graph.
  • Evaluate the trajectory from my_agent:run_agent on my_dataset with an LLM judge.
  • Compare my_agent:v1 and my_agent:v2 on dataset.json and save comparison_report.json.

How to install langgraph-testing-evaluation

1Skills CLI (Vercel)

npx skills add soba-labs/langchain-agent-skills --skill langgraph-testing-evaluation -a claude-code

2Manually: put the files in place

~/.claude/skills/langgraph-testing-evaluation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/langgraph-testing-evaluation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about langgraph-testing-evaluation

How do I install langgraph-testing-evaluation in Claude Code?

Run npx skills add soba-labs/langchain-agent-skills --skill langgraph-testing-evaluation -a claude-code. The skill file is at ~/.claude/skills/langgraph-testing-evaluation/SKILL.md.

What does langgraph-testing-evaluation do?

It helps test LangGraph and LangChain agent nodes and interactions, score trajectories and datasets, and compare agent versions.

Which languages does langgraph-testing-evaluation support?

Its scripts and workflows cover Python and JavaScript/TypeScript.

Source text

SKILL.md · MIT
---
name: langgraph-testing-evaluation
description: "Use this skill when you need to test or evaluate LangGraph/LangChain agents: writing unit or integration tests, generating test scaffolds, mocking LLM/tool behavior, running trajectory evaluation (match or LLM-as-judge), running LangSmith dataset evaluations, and comparing two agent versions with A/B-style offline analysis. Use it for Python and JavaScript/TypeScript workflows, evaluator design, experiment setup, regression gates, and debugging flaky/incorrect evaluation results."
---

# LangGraph Testing & Evaluation

Practical workflows for validating agent quality with:
- Unit/integration tests
- Trajectory evaluation
- LangSmith dataset evaluations
- A/B-style comparisons between versions

Use this file for high-level flow. Load `references/*` for detailed implementation.

## Start Here

Choose the smallest approach that answers your question:

| Goal | Primary method | Load first |
| --- | --- | --- |
| Validate node logic quickly | Unit tests with mocks | `references/unit-testing-patterns.md` |
| Validate multi-step agent behavior | Trajectory evaluation | `references/trajectory-evaluation.md` |
| Track quality over datasets over time | LangSmith evaluation | `references/langsmith-evaluation.md` |
| Compare old vs new agent versions | A/B comparison | `references/ab-testing.md` |

Recommended order:
1. Unit tests
2. Integration/trajectory checks
3. Dataset evaluation in LangSmith
4. A/B comparison before deployment

## Quick Commands

Run from repo root.

### Generate test scaffolding

```bash
# Python (preferred)
uv run skills/langgraph-testing-evaluation/scripts/generate_test_cases.py my_agent:graph --output tests/ --framework pytest

# JavaScript/TypeScript
node skills/langgraph-testing-evaluation/scripts/generate_test_cases.js ./my-agent.ts:graph --output tests/ --framework vitest
```

### Run trajectory evaluation

```bash
# Python: LLM-as-judge
uv run skills/langgraph-testing-evaluation/scripts/run_trajectory_eval.py my_agent:run_agent my_dataset --method llm-judge --model openai:o3-mini

# Python: trajectory match
uv run skills/langgraph-testing-evaluation/scripts/run_trajectory_eval.py my_agent:run_agent dataset.json --method match --trajectory-match-mode strict --reference-trajectory reference.json

# JavaScript/TypeScript
node skills/langgraph-testing-evaluation/scripts/run_trajectory_eval.js ./agent.ts:runAgent my_dataset --method llm-judge --model openai:o3-mini --max-concurrency 4
```

### Run LangSmith dataset evaluation

```bash
# Python
uv run skills/langgraph-testing-evaluation/scripts/evaluate_with_langsmith.py my_agent:run_agent my_dataset --evaluators accuracy,latency --max-concurrency 4

# Python (do not upload experiment results)
uv run skills/langgraph-testing-evaluation/scripts/evaluate_with_langsmith.py my_agent:run_agent my_dataset --evaluators accuracy --no-upload

# JavaScript/TypeScript
node skills/langgraph-testing-evaluation/scripts/evaluate_with_langsmith.js ./agent.ts:runAgent my_dataset --evaluators accuracy,latency --max-concurrency 4
```

### Compare two agent versions

```bash
# Python
uv run skills/langgraph-testing-evaluation/scripts/compare_agents.py my_agent:v1 my_agent:v2 dataset.json --output comparison_report.json

# JavaScript/TypeScript
node skills/langgraph-testing-evaluation/scripts/compare_agents.js ./v1.ts:run ./v2.ts:run dataset.json --output comparison_report.json

# JavaScript/TypeScript (force local dataset file only)
node skills/langgraph-testing-evaluation/scripts/compare_agents.js ./v1.ts:run ./v2.ts:run dataset.json --no-langsmith
```

### Create mock response configs

```bash
# Python
uv run skills/langgraph-testing-evaluation/scripts/mock_llm_responses.py create --type sequence --output mock_config.json

# JavaScript/TypeScript
node skills/langgraph-testing-evaluation/scripts/mock_llm_responses.js create --type sequence --output mock_config.json
```

## Core Workflow

1. Define test scope.
- Unit: deterministic logic in one node/function.
- Integration: node interactions and routing.
- End-to-end: complete response quality on realistic inputs.

2. Start from deterministic checks.
- Mock LLM/tool IO for speed and repeatability.
- Keep real-model tests as a smaller, explicit suite.

3. Build/curate dataset examples.
- Use stable inputs and expected outputs.
- Keep schema simple: `inputs` and `outputs` objects (optional `metadata`).
- Compatibility note: scripts also accept singular keys (`input`, `output`) for legacy datasets.

4. Run evaluation with explicit gates.
- Use evaluator keys that map to deployment decisions.
- Set thresholds in CI for regression prevention.

5. Compare versions before rollout.
- Run same dataset on both versions.
- Check both quality and latency.

6. Diagnose failures from traces/experiments.
- Inspect low-scoring examples.
- Split failures by pattern (routing, tool usage, hallucination, latency spikes).

## Current References (Load On Demand)

### `references/unit-testing-patterns.md`
Load when:
- You need node-level and routing test patterns.
- You need pytest/vitest/Jest integration patterns.
- You need robust mocking and flaky-test reduction.

### `references/trajectory-evaluation.md`
Load when:
- You need trajectory match evaluation (`strict`, `unordered`, `subset`, `superset`).
- You need LLM-as-judge trajectory scoring.
- You need LangSmith experiment comparison for trajectory results.

### `references/langsmith-evaluation.md`
Load when:
- You need dataset creation/management in LangSmith.
- You need evaluator signatures and experiment runs in Python/TS.
- You need CI-friendly workflows with quality thresholds.

### `references/ab-testing.md`
Load when:
- You need offline A/B comparison methodology.
- You need significance testing and interpretation.
- You need production traffic split strategy and guardrails.

## Assets

### `assets/templates/test_template.py`
- Runnable Python pytest template aligned with current LangGraph testing patterns.
- Includes:
  - Compiled-graph invocation with `thread_id`
  - Single-node testing via `compiled_graph.nodes[...]`
  - Integration-test placeholder

### `assets/datasets/sample_dataset.json`
- Deterministic seed dataset for LangSmith ingestion.
- Uses `examples: [{ inputs, outputs, metadata }]` format.

### `assets/examples/README.md`
- Documentation-only index for current asset usage.
- Notes where runnable assets live today.

## Script Interface Summary

### `scripts/generate_test_cases.py` / `.js`
Use for fast test scaffolding.

Inputs:
- Graph module path
  - Python: `my_module:graph` or `my_module.graph`
  - JS/TS: `./file.ts:graph`

Outputs:
- Framework-specific starter tests in target directory.

### `scripts/run_trajectory_eval.py` / `.js`
Use for trajectory scoring with either:
- `--method match`
- `--method llm-judge`

Supports:
- Local dataset files (`.json`)
- LangSmith dataset names
- Optional reference trajectory file with `--reference-trajectory`
- Match modes: `strict`, `unordered`, `subset`, `superset`

Local-only mode:
- `--no-langsmith` in both Python and JavaScript scripts (requires local JSON dataset file)

### `scripts/evaluate_with_langsmith.py` / `.js`
Use for dataset-based evaluation runs and experiment tracking.

Supports:
- Existing dataset by name
- Dataset creation from JSON examples file
- Multiple evaluators (`--evaluators accuracy,latency,...`)
- Concurrency control (`--max-concurrency`)

Python-only:
- `--no-upload` to run without uploading experiment results

### `scripts/compare_agents.py` / `.js`
Use for offline version comparisons:
- Shared dataset input
- Success/latency summaries
- JSON report output for CI artifacts
- Local JSON datasets or LangSmith datasets (JS supports `--no-langsmith` to disable remote loading)

### `scripts/mock_llm_responses.py` / `.js`
Use for deterministic test doubles:
- single
- sequence
- conditional

## Decision Rules

If behavior is deterministic and local:
- Use unit tests first.

If behavior depends on tool sequence/routing:
- Add trajectory evaluation.

If behavior depends on realistic distribution quality:
- Run LangSmith dataset evaluation.

If approving a replacement model/prompt/graph:
- Run A/B comparison and check both quality and latency.

## Common Failure Patterns

### Flaky tests
- Cause: real-model nondeterminism in unit scope.
- Fix: mock LLM/tool calls for unit tests; reserve real-model tests for separate integration marks.

### High trajectory variance
- Cause: overly strict matching for workflows with equivalent paths.
- Fix: switch match mode (`unordered`, `subset`, or `superset`) where appropriate.

### Regressions hidden by averages
- Cause: only aggregate score monitored.
- Fix: inspect per-example failures and segment by category metadata.

### Latency regressions with same quality
- Cause: no explicit latency gate.
- Fix: include latency evaluator and CI threshold.

## Minimal Best Practices

1. Keep fast deterministic tests as the largest share.
2. Version datasets and keep them stable.
3. Track both correctness and latency.
4. Add explicit go/no-go thresholds in CI.
5. Compare candidate vs baseline before production rollout.
6. Investigate failures with trace-level evidence, not only aggregate scores.

© soba-labs · MIT · soba-labs/langchain-agent-skills

Similar skills

All skills for Testing and QA →

From the same set9

langsmith-trace-analyzer The langsmith-trace-analyzer Claude Code skill downloads and analyzes LangSmith traces. It helps investigate agent runs and compare evaluation results. CX Codex +1 ★ 106repo stars langsmith-deployment This Claude Code skill manages agent server deployments in LangSmith Deployment. It comes into play when validating langgraph.json, changing revisions, or diagnosing runtime issues. CX Codex +1 ★ 106repo stars langgraph-state-management The langgraph-state-management Claude Code skill helps shape state schemas for LangGraph applications and diagnose update behavior. It applies to reducer design, persistence setup, and checkpoint debugging. CX Codex +1 ★ 106repo stars langgraph-project-setup The langgraph-project-setup Claude Code skill scaffolds and configures LangGraph projects. It activates for project structure, langgraph.json, provider variables, dependency setup, and configuration troubleshooting. CX Codex +1 ★ 106repo stars langgraph-error-handling The langgraph-error-handling Claude Code skill adds error-handling patterns to LangGraph. It applies to transient failures, model recovery, and workflows that need human approval. CX Codex +1 ★ 106repo stars langgraph-agent-patterns The langgraph-agent-patterns Claude Code skill helps build agent coordination patterns for LangGraph applications. It activates when choosing a pattern or debugging how agents work together. CX Codex +1 ★ 106repo stars deepagents-setup-configuration The deepagents-setup-configuration Claude Code skill scaffolds and checks Deep Agents projects in Python or JavaScript. It helps configure subagents, persistence, and human approval. CX Codex +1 ★ 106repo stars deepagents-planning-todos The deepagents-planning-todos Claude Code skill shows how to plan Deep Agents work with write_todos. It covers task breakdown, progress tracking, and diagnosing todos that remain unfinished. CX Codex +1 ★ 106repo stars

Project sponsors

Companies that keep this analytics open