TeDS Tutorial — Test-Driven Schema Development

# Install from PyPI
pip install teds

# Verify installation
teds --version

# Clone and setup for development
git clone https://github.com/yaccob/teds.git
cd teds
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

# Verify installation
./teds.py --version

# user_email.yaml
type: string
format: email

version: "1.0.0"
tests:
  user_email.yaml#/:
    valid:
      simple_email:
        description: "Basic valid email"
        payload: "alice@example.com"
      email_with_subdomain:
        description: "Email with subdomain"
        payload: "bob@mail.company.com"
    invalid:
      missing_at:
        description: "Email without @ symbol"
        payload: "alice.example.com"
      missing_domain:
        description: "Email without domain"
        payload: "alice@"

version: "1.0.0"
tests:
  user_email.yaml#/:
    valid:
      '"alice@example.com"':    # Key becomes payload: "alice@example.com"
        description: "Valid email from key"
      '"bob@company.com"':      # Key becomes payload: "bob@company.com"
        description: "Another valid email"
    invalid:
      '"alice.example.com"':    # Key becomes payload: "alice.example.com"
        description: "Invalid: missing @"
      '"@example.com"':         # Key becomes payload: "@example.com"
        description: "Invalid: missing user"

teds verify user_email.tests.yaml

version: 1.0.0
tests:
  user_email.yaml#/:
    valid:
      simple_email:
        payload: alice@example.com
        result: SUCCESS
      email_with_subdomain:
        payload: bob@mail.company.com
        result: SUCCESS
    invalid:
      missing_at:
        payload: alice.example.com
        result: WARNING
        message: |
          UNEXPECTEDLY VALID
          A validator that *ignores* 'format' accepted this instance...

# user_email.yaml (improved)
type: string
format: email
pattern: '^[^@]+@[^@]+\.[^@]+$'  # Basic email pattern

cat demo/sample_schemas.yaml

cat api_spec.components~1schemas.tests.yaml

# Add to existing generated file
tests:
  api_spec.yaml#/components/schemas/Email:
    valid:
      # ... generated cases here ...
    invalid:
      not_an_email:
        description: "String without email format"
        payload: "not-an-email"
      empty_string:
        description: "Empty string"
        payload: ""

# schemas/user.yaml
type: object
additionalProperties: false
required: [id, name, email]
properties:
  id:
    type: string
    format: uuid
  name:
    type: string
    minLength: 1
  email:
    type: string
    format: email

# user.tests.yaml
version: "1.0.0"
tests:
  schemas/user.yaml#/:
    valid:
      complete_user:
        description: "User with all required fields"
        payload:
          id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          name: "Alice Example"
          email: "alice@example.com"
    invalid:
      missing_email:
        description: "Missing required email field"
        payload:
          id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          name: "Alice Example"
      extra_field:
        description: "Additional property not allowed"
        payload:
          id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          name: "Alice Example"
          email: "alice@example.com"
          age: 25  # This should be rejected
      invalid_uuid:
        description: "Invalid UUID format"
        payload:
          id: "not-a-uuid"
          name: "Alice Example"
          email: "alice@example.com"

# schemas/age.yaml
type: integer
minimum: 0
maximum: 150

# age.tests.yaml
version: "1.0.0"
tests:
  schemas/age.yaml#/:
    valid:
      minimum_age:
        description: "Minimum valid age"
        payload: 0
      maximum_age:
        description: "Maximum valid age"
        payload: 150
      typical_age:
        description: "Typical age"
        payload: 25
    invalid:
      negative_age:
        description: "Below minimum"
        payload: -1
      too_old:
        description: "Above maximum"
        payload: 151
      not_integer:
        description: "Not an integer"
        payload: 25.5

# schemas/status.yaml
type: string
enum: ["draft", "published", "archived"]

# status.tests.yaml
version: "1.0.0"
tests:
  schemas/status.yaml#/:
    valid:
      draft_status:
        payload: "draft"
      published_status:
        payload: "published"
      archived_status:
        payload: "archived"
    invalid:
      wrong_case:
        description: "Wrong case should be rejected"
        payload: "Draft"
      unknown_status:
        description: "Status not in enum"
        payload: "deleted"
      empty_string:
        description: "Empty string not in enum"
        payload: ""

# schemas/contact.yaml
oneOf:
  - type: object
    required: [email]
    properties:
      email:
        type: string
        format: email
  - type: object
    required: [phone]
    properties:
      phone:
        type: string
        pattern: '^\+[1-9]\d{1,14}$'  # E.164 format

# contact.tests.yaml
version: "1.0.0"
tests:
  schemas/contact.yaml#/:
    valid:
      email_contact:
        description: "Contact with email only"
        payload:
          email: "alice@example.com"
      phone_contact:
        description: "Contact with phone only"
        payload:
          phone: "+1234567890"
    invalid:
      both_fields:
        description: "Both email and phone (should fail oneOf)"
        payload:
          email: "alice@example.com"
          phone: "+1234567890"
      neither_field:
        description: "Neither email nor phone"
        payload:
          name: "Alice"
      invalid_email:
        description: "Invalid email format"
        payload:
          email: "not-an-email"
      invalid_phone:
        description: "Invalid phone format"
        payload:
          phone: "123"  # Too short for E.164

# List all available templates
teds verify tests.yaml --list-templates

# Available built-in templates:
# - default.html: Full HTML with syntax highlighting
# - default.md: Markdown with emoji indicators
# - default.adoc: AsciiDoc with color coding
# - summary.html: Compact HTML overview
# - summary.md: Brief Markdown summary

# Generate HTML report
teds verify sample_tests.yaml --report default.html

# Generate Markdown report
teds verify sample_tests.yaml --report default.md

# Generate AsciiDoc report
teds verify sample_tests.yaml --report default.adoc

# Generate compact summary
teds verify sample_tests.yaml --report summary.md

# Specify custom output filenames
teds verify tests.yaml --report default.html=my_report.html
teds verify tests.yaml --report summary.md=project_summary.md

# Show only errors (CI-friendly)
teds verify tests.yaml --output-level error

# Show warnings and errors (default)
teds verify tests.yaml --output-level warning

# Show everything including successes
teds verify tests.yaml --output-level all

# CI-friendly: only show errors
teds verify tests/**/*.yaml --output-level error

# Exit code handling
if teds verify tests/**/*.yaml --output-level error; then
  echo "All schema tests passed!"
else
  case $? in
    1) echo "Some tests failed - review ERROR cases" ;;
    2) echo "Hard failure - check configuration/schemas" ;;
  esac
fi

# Update test files with results
teds verify my_tests.yaml --in-place

# This updates only the 'tests' section, preserving version and comments

# Verify multiple specifications
teds verify user.tests.yaml product.tests.yaml order.tests.yaml

# Generate reports for multiple files
teds verify tests/*.yaml --report default.html

# Enable network access for remote $ref resolution
teds verify spec.yaml --allow-network

# With custom timeouts
TEDS_NETWORK_TIMEOUT=10 teds verify spec.yaml --allow-network

tests:
  schema.yaml#/User:
    valid:
      complex_from_string:
        description: "User from JSON string"
        parse_payload: true
        payload: '{"id":"123","name":"Alice","email":"alice@example.com"}'

      api_response_format:
        description: "Testing JSON strings within YAML (common in API responses)"
        parse_payload: true
        payload: '{"user": {"profile": {"name": "Bob", "settings": {"theme": "dark"}}}}'

# JSON Pointer syntax with template variables
teds generate schema.yaml#/components/schemas={base}.{pointer}.custom.yaml

# JSON Path syntax with template variables
teds generate '{"schema.yaml": {"paths": ["$.components.schemas.*"], "target": "{base}_{ext}_tests.yaml"}}'

# generation-config.yaml
api_spec.yaml:
  paths: ["$.components.schemas.*", "$.components.responses.*"]
  target: "api_validation.tests.yaml"

legacy_schema.yaml: ["$.definitions.*"]

teds generate @generation-config.yaml

tests:
  schema.yaml#/Email:
    valid:
      deprecated_format:
        payload: "user@company.co.uk"
        warnings: ["This email format will be deprecated in v2.0"]

# Network settings
export TEDS_NETWORK_TIMEOUT=10        # seconds (default: 5)
export TEDS_NETWORK_MAX_BYTES=10485760 # bytes (default: 5MB)

# Use in commands
teds verify remote_specs.yaml --allow-network

# CI script example
if teds verify tests/*.yaml --output-level error; then
  echo "✅ All schema contracts validated"
else
  exit_code=$?
  case $exit_code in
    1) echo "❌ Schema validation failures found" ;;
    2) echo "🚨 Configuration or file errors" ;;
  esac
  exit $exit_code
fi

project/
├── schemas/
│   ├── user.yaml
│   ├── product.yaml
│   └── order.yaml
├── tests/
│   ├── user.tests.yaml
│   ├── product.tests.yaml
│   └── order.tests.yaml
└── docs/
    └── api-validation-report.html

# Weak - format may not be enforced by all validators
type: string
format: email

# Strong - pattern ensures consistent validation across validators
type: string
format: email
pattern: '^[^@]+@[^@]+\.[^@]+$'

# Ambiguous - might allow extra properties
type: object
properties:
  name: {type: string}

# Clear - extra properties forbidden
type: object
additionalProperties: false
properties:
  name: {type: string}

# For minimum: 1, test 0, 1, 2
# For maximum: 100, test 99, 100, 101
# For minLength: 3, test "", "ab", "abc", "abcd"

# 1. Run verification and save output
teds verify my_tests.yaml > verification_results.yaml

# 2. Edit the results file to add new test cases or modify existing ones
# (The output format is valid TeDS input format)

# 3. Use edited results as new input
teds verify verification_results.yaml --in-place

# Start with basic tests
teds verify user.tests.yaml --in-place

# This updates user.tests.yaml with results. Now you can:
# 1. Add more test cases directly to user.tests.yaml
# 2. Copy successful patterns to new test sections
# 3. Incrementally build comprehensive test suites

# Re-run verification to validate new additions
teds verify user.tests.yaml --in-place

# Generate initial tests from schema
teds generate schemas.yaml#/components/schemas > user_generated.tests.yaml

# Add manual test cases to generated file
# (Edit user_generated.tests.yaml to add invalid cases)

# Verify and clean up with in-place updates
teds verify user_generated.tests.yaml --in-place

# The file is now a clean, validated test specification
# ready for version control and CI integration