Pets

Appearance

Testing Guide ​

How to test your pets before publishing.

Validation ​

Basic Validation ​

bash
# Validate pet configuration
pets validate

# Validate specific pet
cd pets/my-pet
pets validate

Validation checks:

  • package.json has required fields
  • index.ts exports a valid plugin
  • Environment variables are documented
  • Schema types are compatible

Local Testing ​

Test Connection ​

bash
bun test:pet my-pet --query "test connection"

Test Individual Tools ​

bash
pets tools my-pet
pets exec my-pet-list-items --args '{}' --json

Interactive Testing ​

bash
# Start a session
bun test:pet my-pet --query "test connection"

# Continue with follow-up prompts:
bun test:pet my-pet --query "test connection" --follow "now list all items"

Scenario Testing ​

Define Scenarios ​

In package.json:

json
{
  "scenarios": {
    "basic-workflow": [
      "test my-pet connection",
      "list all items from my-pet",
      "get details for item ABC123"
    ],
    "create-workflow": [
      "create a new item called Test",
      "verify the item was created",
      "delete the test item"
    ]
  }
}

Check Scenario Catalog Entries ​

bash
# Check all scenarios for a pet
bun run test:scenarios my-pet

# Show a specific scenario
bun run test:scenarios my-pet --scenario basic-workflow

# List available scenarios
bun run test:scenarios:list

Query Testing ​

Define Test Queries ​

In package.json:

json
{
  "queries": [
    "list all my items",
    "search for items matching 'test'",
    "create a new item with name Example"
  ]
}

Run Query Tests ​

bash
# Quick query test
bun test:pet my-pet --query "list all my items"

# Full query/case test
bun run test:pet -- my-pet --cases pets/my-pet/test-cases.json

Testing Checklist ​

Before publishing, verify:

Configuration ​

  • [ ] pets validate passes
  • [ ] All required env vars documented
  • [ ] package.json has queries and scenarios

Functionality ​

  • [ ] test-connection tool works
  • [ ] All tools return valid JSON
  • [ ] Errors are handled gracefully
  • [ ] Unconfigured state returns limited tools

Documentation ​

  • [ ] README explains setup
  • [ ] Example queries work
  • [ ] FAQ covers common issues

Debugging ​

Enable Logging ​

bash
# Enable all logs
ENABLE_LOGGING=true bun test:pet my-pet --query "test query"

# Debug level
LOG_LEVEL=debug bun test:pet my-pet --query "test query"

Check Output Format ​

All tools should return JSON strings:

typescript
// Good
return JSON.stringify({ success: true, data: result }, null, 2)

// Bad - returns object
return { success: true, data: result }

Common Issues ​

"Tool not found"

  • Check tool name matches {pet-name}-{action} pattern
  • Verify pets tools my-pet lists the expected tool

"Schema validation failed"

  • Check for unsupported Zod types
  • Ensure no nested objects in arrays

"API error"

  • Verify environment variables
  • Check API credentials are valid
  • Review rate limits

CI/CD Testing ​

GitHub Actions Example ​

yaml
name: Test Pet
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1
      
      - name: Install dependencies
        run: bun install
        
      - name: Validate pet
        run: pets validate
        working-directory: pets/my-pet
        
      - name: Check scenario catalog
        run: bun run test:scenarios my-pet
        env:
          MY_PET_API_KEY: ${{ secrets.MY_PET_API_KEY }}

Next Steps ​