Guardrails Test Example

This example demonstrates the guardrail assertion feature, which allows you to test whether validators (guardrails) trigger as expected in your prompt configurations.

Overview

The guardrail_triggered assertion type enables you to:

• Verify guardrails trigger when they should - Test that your validators catch problematic inputs
• Verify guardrails don’t trigger when they shouldn’t - Ensure clean inputs pass through without false positives
• Test in non-production mode - Use suppress_validation_exceptions: true to allow execution to continue after validation failures, so you can assert on the guardrail behavior

Key Concept: SuppressValidationExceptions

By default, when a validator fails, it throws a ValidationError and halts execution. This is the correct behavior for production.

For testing purposes, Arena automatically enables SuppressValidationExceptions mode in the validator middleware. This allows:

1. The validator to run and record its result (pass/fail)
2. Execution to continue even if validation fails
3. Assertions to inspect whether the guardrail triggered

Important: This suppression behavior is built into Arena’s pipeline construction, not configured in the PromptConfig. Your production prompt configurations remain unchanged - they use the same validator definitions for both production and testing.

Example Structure

guardrails-test/
├── arena.yaml              # Test scenarios with guardrail_triggered assertions
├── prompts/
│   └── content-filter.yaml # Prompt with banned_words validator
└── providers/
    └── openai.yaml         # OpenAI provider configuration

Configuration Details

Prompt Configuration (prompts/content-filter.yaml)

The prompt includes a banned_words validator - the same configuration used in production:

validators:
  - type: banned_words
    params:
      words:
        - damn
        - crap
        - hell
      case_sensitive: false

Note: No special test-only flags are needed in the PromptConfig. Arena’s test framework automatically enables suppression mode when running validators.

Test Scenarios (arena.yaml)

Four test scenarios demonstrate different assertion patterns:

1. guardrail-should-trigger: Input contains banned words → expect validator to trigger
2. guardrail-should-not-trigger: Clean input → expect validator not to trigger
3. multiple-violations: Multiple banned words → expect validator to trigger
4. streaming-guardrail-trigger: Tests guardrail in streaming mode → expect validator to trigger and interrupt stream

Each scenario uses the guardrail_triggered assertion:

assertions:
  - type: guardrail_triggered
    validator: banned_words        # Name of the validator to check
    should_trigger: true           # Expected behavior (true = should fail, false = should pass)
    message: "Descriptive message for test output"

Running the Tests

1. Set up your OpenAI API key:

   export OPENAI_API_KEY="your-api-key-here"

2. Run the Arena tests:

   promptarena run examples/guardrails-test/arena.yaml

Expected Results

• ✅ guardrail-should-trigger: PASS (validator triggered as expected)
• ✅ guardrail-should-not-trigger: PASS (validator did not trigger as expected)
• ✅ multiple-violations: PASS (validator triggered on multiple violations as expected)
• ✅ streaming-guardrail-trigger: PASS (validator triggered in streaming mode and interrupted stream as expected)

Streaming Mode Support

The streaming-guardrail-trigger scenario demonstrates how guardrails work with streaming responses:

• Real-time validation: Validators process each chunk as it arrives
• Stream interruption: When a validation fails, the stream is immediately interrupted
• Suppression behavior: With suppression enabled (Arena test mode), the stream interrupts but no error is thrown
• Recorded results: Validation failures are still recorded in metadata for assertions to inspect

This ensures that guardrails work correctly in both regular and streaming execution modes.

How It Works

1. Execution Phase:

   • User input is processed through the prompt
   • Validators run (Arena automatically enables suppression mode)
   • Validation results are recorded in execution context, but errors are suppressed
   • LLM generates a response

2. Assertion Phase:

   • The guardrail_triggered assertion inspects the execution context
   • It finds the last assistant message and its validation results
   • It checks if the specified validator passed or failed
   • It compares the actual result against the should_trigger expectation

3. Test Outcome:

   • If actual behavior matches expectation → Test PASS
   • If actual behavior differs from expectation → Test FAIL with descriptive error

Use Cases

This pattern is valuable for:

• Regression testing: Ensure guardrails continue to work as expected over time
• Configuration validation: Verify validator configs (banned word lists, patterns, etc.) are correct
• Coverage testing: Confirm edge cases are properly handled by your guardrails
• CI/CD integration: Automated testing of prompt safety measures

Production vs Test Mode

Production Mode (SDK/Conversation API - default):

// Production code uses DynamicValidatorMiddleware with default behavior
middleware.DynamicValidatorMiddleware(registry)

• Validation failures throw errors immediately
• Execution halts on first validation failure
• Appropriate for live user-facing systems

Test Mode (Arena test framework):

// Arena automatically uses suppression mode
middleware.DynamicValidatorMiddlewareWithSuppression(registry, true)

• Validation failures are logged but don’t throw errors
• Execution continues so assertions can inspect results
• Appropriate for automated testing and development

The same PromptConfig works in both modes - no test-specific configuration needed!

Related Documentation

• GUARDRAIL_ASSERTION_PROPOSAL.md - Original proposal
• GitHub Issue #25 - Implementation tracking
• Arena User Guide - General Arena testing documentation