Declarative LLM Testing: Matrix Evaluations and Red Teaming with Promptfoo

Language model applications are uniquely susceptible to silent regressions. An innocuous adjustment to a system prompt, a revision to retrieval-augmented generation (RAG) context embeddings, or an underlying model replacement (such as transitioning from GPT-4 to Gemini) can degrade answer consistency or reintroduce prompt vulnerabilities. In traditional software development, regression suites rely on deterministic invariants; in generative AI, non-deterministic completions have historically pushed teams toward manual prompt spot-checking or ad-hoc Jupyter notebooks.

Promptfoo brings standard software testing rigor to LLM development. Operating as a local-first command-line interface and library, Promptfoo allows developers to write declarative test configurations, execute combinatorial test matrices, apply tiered assertions, and run automated red-team security audits within local environments and CI/CD pipelines.

Combinatorial Matrix Evaluation Mechanics

Promptfoo organizes evaluations around a declarative Cartesian product model. As detailed in the Promptfoo Official Introduction, testing is defined declaratively within a configuration file (promptfooconfig.yaml), combining prompt variations, target model providers, and test scenarios:

$$\text{Total Executions} = |\text{Prompts}| \times |\text{Providers}| \times |\text{Test Cases}|$$

In his guide on Generative AI Evaluation with Promptfoo, ML system architect Yuki Nagae demonstrates that defining two prompt templates across two provider configurations against three test cases results in 12 concurrent evaluations. By separating the prompt variation from provider wrappers and input variables, teams can systematically benchmark performance and detect regressions across model updates.

To keep local iteration cycles fast and prevent redundant external calls, the engine integrates caching, concurrency controls, and live reloading directly into the evaluation cycle.

Multi-Tiered Assertion Architecture

A central design decision in Promptfoo is its multi-tiered validation model. Because natural language outputs vary while underlying business constraints remain rigid, Promptfoo provides three levels of assertions:

Deterministic Syntactic Assertions: Checks such as icontains (case-insensitive substring presence) and regular expressions run locally with zero API cost, catching obvious regressions instantly.
Custom Script Assertions: Programmatic assertions written in JavaScript or Python. As shown in community configurations, developers can evaluate programmatic invariants directly, such as string length penalties (1 / (output.length + 1)) or structured schema validation.
Model-Graded Rubrics (llm-rubric): For qualitative attributes like tone, humor, or safety policies that cannot be validated via regular expressions, Promptfoo delegates grading to an LLM judge (such as GPT-4o) using defined natural-language criteria.

This tiered structure allows development teams to fail fast on deterministic criteria before committing tokens to qualitative model-graded evaluations.

Local Configuration and Workflow Setup

According to the promptfoo README, Promptfoo requires Node.js >=22.22.0 (with Node.js 24 LTS recommended) for npm and npx installations, and is also installable via Homebrew or Python's pip. Configuration lives in a declarative YAML manifest:

description: "Customer Support Routing Evaluation"

prompts:
  - "You are a support bot. Triage the user inquiry: {{inquiry}}"
  - "Analyze the customer message and classify priority and domain: {{inquiry}}"

providers:
  - "openai:gpt-4o-mini"
  - "openai:gpt-4o"

tests:
  - vars:
      inquiry: "I was double-charged for my enterprise subscription."
    assert:
      - type: icontains
        value: "billing"
      - type: javascript
        value: "output.toLowerCase().includes('priority') || output.toLowerCase().includes('urgent')"

  - vars:
      inquiry: "How do I reset my SSO password?"
    assert:
      - type: llm-rubric
        value: "ensure that the output is helpful and directs to identity settings"

Running evaluations and inspecting results follows standard CLI conventions:

# Set required provider credentials
export OPENAI_API_KEY=sk-abc123

# Execute evaluation matrix
promptfoo eval

# Launch the local web viewer to inspect outputs side-by-side
promptfoo view

The web viewer surfaces side-by-side completion tables, per-assertion pass/fail breakdowns, and latency metrics across models.

Automated AI Red Teaming and Vulnerability Auditing

Beyond prompt regression testing, Promptfoo incorporates automated red-teaming scanners. As highlighted in community reporting on daily.dev, the tool scans agents, prompts, and RAG architectures for security vulnerabilities, adversarial jailbreaks, and compliance risks.

Rather than manually designing attack strings, the red-teaming engine generates adversarial inputs to probe model safeguards, producing structured vulnerability reports that can be integrated into pull-request code scanning and CI/CD pipelines.

Privacy Boundaries and Operational Tradeoffs

Promptfoo emphasizes a local-first execution model: evaluations run entirely on the developer's local machine or CI runner, communicating directly with target LLM APIs without routing data through intermediary evaluation SaaS platforms. Key operational considerations include:

Collaboration and Sharing: Promptfoo provides built-in sharing features alongside its local web viewer, allowing teams to collaborate on evaluation matrices. However, teams should govern when test outputs are shared externally versus maintained strictly within local environments.
Evaluation Determinism: Relying heavily on llm-rubric assertions reintroduces model non-determinism into test pipelines. Automated CI gates function most reliably when grounded in deterministic assertions, reserving model rubrics for pre-deployment reviews.
Ecosystem Neutrality: Although Promptfoo announced that it joined OpenAI, the project maintains its open-source status under the permissive MIT license, preserving native support for OpenAI, Anthropic, Google, Azure, and local inference targets like Llama and Ollama.

Sources

Primary Documentation & Repositories

promptfoo GitHub Repository — Repository metadata, open issues, and TypeScript codebase.
promptfoo README Documentation — Runtime prerequisites, CLI commands, and feature overview.
Promptfoo Official Introduction — Workflow philosophy, local evaluation architecture, and web viewer capabilities.

Independent Technical Coverage

Generative AI Evaluation with Promptfoo: A Comprehensive Guide by Yuki Nagae — Practical test case patterns, matrix generation, and tiered assertion walkthroughs.
daily.dev Technical Overview by Jobayer Hossen — Discussion of LLM red teaming, vulnerability scanning, and CI/CD automated checks.