# Promptfoo - Deep Dive

> **TL;DR**: Promptfoo is an open-source LLM testing and evaluation framework (9,700+ stars) that runs 100% locally. It lets you test prompts across 50+ LLM providers, includes red teaming for security testing, and has 51 built-in assertion types. Supports OWASP Top 10 for LLM security testing. MIT licensed, used in production serving 10M+ users.

---

## What Is Promptfoo?

**Promptfoo** is a developer-focused testing framework for LLM applications. It helps you:

- Test prompts across different models
- Evaluate output quality with assertions
- Red team for security vulnerabilities
- Compare LLM providers side-by-side
- Integrate testing into CI/CD pipelines

### The Core Philosophy

```
"Stop the trial-and-error approach -
start shipping secure, reliable AI apps"
```

### Key Differentiator

**Everything runs locally** - your prompts never leave your machine.

---

## Quick Stats

| Metric | Value |
|--------|-------|
| **GitHub Stars** | 9,700+ |
| **Forks** | 841 |
| **Contributors** | 247+ |
| **Releases** | 377 |
| **License** | MIT |
| **Language** | TypeScript (96.6%) |

---

## Key Features

### 1. Prompt Testing & Evaluation

```yaml
# promptfooconfig.yaml
prompts:
  - "Write a {{style}} poem about {{topic}}"

providers:
  - openai:gpt-4
  - anthropic:claude-3-sonnet

tests:
  - vars:
      style: haiku
      topic: autumn
    assert:
      - type: contains
        value: "leaves"
      - type: llm-rubric
        value: "Is this a valid haiku with 5-7-5 syllables?"
```

### 2. Red Teaming & Security

Test against security vulnerabilities:

| Attack Type | Detection |
|-------------|-----------|
| **Prompt Injection** | ✅ |
| **Jailbreak Attempts** | ✅ |
| **Data Leakage** | ✅ |
| **Harmful Output** | ✅ |
| **Compliance Violations** | ✅ |

### 3. 51 Assertion Types

```
┌─────────────────────────────────────────────────────────────────────┐
│                    ASSERTION CATEGORIES                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   TEXT MATCHING                                                     │
│   ├── contains, equals, startsWith                                  │
│   ├── regex matching                                                │
│   └── levenshtein distance, similarity                             │
│                                                                     │
│   QUALITY METRICS                                                   │
│   ├── BLEU, ROUGE, METEOR scores                                   │
│   └── Perplexity                                                   │
│                                                                     │
│   LLM-BASED EVALUATION                                              │
│   ├── llmRubric (custom grading)                                   │
│   ├── factuality, answerRelevance                                  │
│   └── geval (G-Eval framework)                                     │
│                                                                     │
│   RAG-SPECIFIC                                                      │
│   ├── contextFaithfulness                                          │
│   ├── contextRecall                                                │
│   └── contextRelevance                                             │
│                                                                     │
│   CODE & FORMAT                                                     │
│   ├── JSON, XML, HTML validation                                   │
│   └── JavaScript, Python, SQL validation                           │
│                                                                     │
│   SAFETY & SECURITY                                                 │
│   ├── redteam, guardrails                                          │
│   ├── moderation, refusal                                          │
│   └── OWASP Top 10 testing                                         │
│                                                                     │
│   PERFORMANCE                                                       │
│   ├── cost tracking                                                │
│   ├── latency measurement                                          │
│   └── toolCallF1                                                   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Supported LLM Providers (50+)

### Major Providers

| Provider | Models |
|----------|--------|
| **OpenAI** | GPT-4, GPT-3.5 |
| **Anthropic** | Claude family |
| **Google** | Gemini, Vertex AI |
| **Microsoft** | Azure OpenAI |
| **AWS** | Bedrock, SageMaker |
| **Meta** | Llama (via providers) |

### Additional Providers

| Provider | Notes |
|----------|-------|
| xAI | Grok |
| Mistral AI | Mistral models |
| Groq | Fast inference |
| DeepSeek | DeepSeek models |
| Cohere | Command models |
| Together AI | Open models |
| Hugging Face | Any HF model |
| Replicate | Model hosting |

---

## OWASP Top 10 Support

Promptfoo includes built-in testing for OWASP LLM Top 10:

| Vulnerability | Testing |
|---------------|---------|
| **LLM01: Prompt Injection** | ✅ |
| **LLM02: Sensitive Data** | ✅ |
| **LLM03: Supply Chain** | ✅ |
| **LLM06: Excessive Agency** | ✅ |
| **LLM09: Misinformation** | ✅ |

---

## Installation & Usage

### Quick Start

```bash
# Initialize
npx promptfoo@latest init

# Run evaluation
npx promptfoo eval

# View results
npx promptfoo view
```

### Red Teaming

```bash
npx promptfoo redteam
```

### CI/CD Integration

```yaml
# GitHub Actions
- name: Run Promptfoo Tests
  run: npx promptfoo eval --ci
```

---

## Configuration

### Basic Config

```yaml
# promptfooconfig.yaml
description: My LLM Tests

prompts:
  - "Summarize: {{text}}"

providers:
  - openai:gpt-4
  - anthropic:claude-3-sonnet

tests:
  - vars:
      text: "Long article content..."
    assert:
      - type: contains
        value: "key point"
      - type: llm-rubric
        value: "Summary captures main ideas"
```

### Red Team Config

```yaml
redteam:
  strategies:
    - jailbreak
    - prompt-injection
    - data-leakage

  targets:
    - openai:gpt-4
```

---

## How It Works

```
┌─────────────────────────────────────────────────────────────────────┐
│                    PROMPTFOO ARCHITECTURE                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   Configuration (YAML)                                              │
│        ↓                                                            │
│   Test Runner (Local)                                               │
│        ↓                                                            │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │  For each test case:                                        │   │
│   │  1. Render prompt with variables                            │   │
│   │  2. Call LLM provider(s)                                    │   │
│   │  3. Run assertions on output                                │   │
│   │  4. Collect metrics (cost, latency)                        │   │
│   └─────────────────────────────────────────────────────────────┘   │
│        ↓                                                            │
│   Results (Web UI / JSON / CI output)                              │
│                                                                     │
│   KEY: Everything runs 100% locally                                │
│        Your prompts never leave your machine                       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Comparison with Alternatives

| Feature | Promptfoo | Manual Testing | Other Tools |
|---------|-----------|----------------|-------------|
| **Local Execution** | ✅ 100% | ✅ | Often cloud |
| **Privacy** | ✅ Prompts stay local | ✅ | Varies |
| **Red Teaming** | ✅ Built-in | ❌ | Limited |
| **50+ Providers** | ✅ | Manual | Varies |
| **CI/CD** | ✅ Native | ❌ | Some |
| **Free** | ✅ MIT | ✅ | Often paid |

---

## Use Cases

### 1. Prompt Development

```
Before deploying:
├── Test prompt variations
├── Compare model outputs
├── Measure quality metrics
└── Validate edge cases
```

### 2. Security Testing

```
Red team your app:
├── Jailbreak attempts
├── Prompt injection
├── Data leakage
└── OWASP Top 10
```

### 3. Model Comparison

```
Compare providers:
├── Quality (assertions)
├── Cost (per request)
├── Latency (response time)
└── Capability (task-specific)
```

### 4. CI/CD Integration

```
Automated testing:
├── Run on every PR
├── Block unsafe changes
├── Track regressions
└── Generate reports
```

---

## How This Connects to Our Other Deep Dives

| Deep Dive | Connection |
|-----------|------------|
| **LLM Guard** | Promptfoo tests, LLM Guard enforces |
| **NeMo Guardrails** | Complementary - testing vs runtime |
| **OWASP LLM Top 10** | Promptfoo tests for OWASP vulnerabilities |
| **Awesome LLMOps** | Listed in evaluation category |
| **lm-evaluation-harness** | Different focus (benchmarks vs app testing) |

---

## Key Links

| Resource | URL |
|----------|-----|
| GitHub | https://github.com/promptfoo/promptfoo |
| Documentation | https://promptfoo.dev/docs |
| Website | https://promptfoo.dev |

---

## Bottom Line

Promptfoo is the **testing framework every LLM application needs**.

**Why it matters**:
- 100% local execution (privacy)
- 51 assertion types for comprehensive testing
- Built-in red teaming for security
- 50+ provider support
- CI/CD ready

**The key insight**: You wouldn't ship code without tests. Why would you ship prompts without testing them? Promptfoo makes LLM testing as natural as unit testing.

For our repository, Promptfoo connects the evaluation tools (SWE-bench, lm-evaluation-harness) with the security tools (LLM Guard, NeMo Guardrails) - it's the bridge that ensures your LLM applications work correctly AND safely.

---

*Document created: January 2026*
*Sources: [GitHub - promptfoo](https://github.com/promptfoo/promptfoo), [promptfoo.dev](https://promptfoo.dev)*
