output-dev-scenario-file

What this skill does

# Creating Scenario Files

## Overview

This skill documents how to create test scenario JSON files for Output SDK workflows. Scenarios provide predefined inputs for testing workflows during development and validation.

## When to Use This Skill

- Creating test inputs for a new workflow
- Documenting different use cases
- Setting up regression tests
- Debugging workflow behavior with specific inputs

## Location Convention

Scenario files are stored INSIDE the workflow folder:

```
src/workflows/{workflow-name}/
├── workflow.ts
├── steps.ts
├── types.ts
└── scenarios/
    ├── basic_input.json
    ├── complex_input.json
    └── edge_case_empty.json
```

**Important**: Scenarios are workflow-specific and live inside the workflow folder.

## File Naming Convention

Use `snake_case` for scenario file names:

```
{description}_input.json
```

Examples:
- `basic_input.json`
- `test_input_solar_panels.json`
- `edge_case_empty_content.json`
- `complex_with_references.json`

Naming patterns:
- `basic_*` - Minimal valid input
- `complex_*` - Full-featured input with all options
- `edge_case_*` - Boundary conditions and edge cases
- `error_*` - Inputs expected to produce errors

## Basic Structure

A scenario file is a JSON file that matches the workflow's `inputSchema`:

```json
{
  "fieldName": "value",
  "optionalField": "optional value",
  "numericField": 42,
  "arrayField": ["item1", "item2"]
}
```

## Matching inputSchema

The scenario JSON must match the Zod schema defined in `types.ts`:

### Example Schema (types.ts)

```typescript
export const WorkflowInputSchema = z.object({
  content: z.string().describe('Text content to process'),
  numberOfIdeas: z.number().min(1).max(10).default(1),
  colorPalette: z.string().optional(),
  aspectRatio: z.enum(['1:1', '16:9', '9:16']).default('1:1'),
  referenceUrls: z.array(z.string()).optional()
});
```

### Corresponding Scenarios

**basic_input.json** (minimal required fields)
```json
{
  "content": "This is sample content for testing the workflow."
}
```

**complete_input.json** (all fields specified)
```json
{
  "content": "This is sample content for testing the workflow.",
  "numberOfIdeas": 3,
  "colorPalette": "blue and green tones",
  "aspectRatio": "16:9",
  "referenceUrls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ]
}
```

## Real-World Example

Based on `image_infographic_nano` workflow:

### test_input_solar_panels.json

```json
{
  "content": "Solar panels work by converting sunlight into electricity through the photovoltaic effect. The process begins when photons from sunlight strike the silicon cells in the panel, knocking electrons loose from their atoms. These free electrons flow through the semiconductor material, creating an electric current. The panels contain multiple layers: a protective glass covering, anti-reflective coating to maximize light absorption, silicon cells (both n-type and p-type layers forming a junction), and a backing material. The DC electricity generated by the panels flows through an inverter, which converts it to AC electricity suitable for home use or feeding back into the power grid. Modern solar panels achieve 15-20% efficiency, meaning they convert that percentage of sunlight into usable electricity. The entire system includes mounting hardware, wiring, inverters, and often battery storage for excess energy.",
  "numberOfIdeas": 3,
  "aspectRatio": "16:9",
  "resolution": "2K",
  "numberOfGenerations": 1
}
```

### test_input_complex.json

```json
{
  "content": "Detailed explanation of the topic...",
  "numberOfIdeas": 5,
  "colorPalette": "warm earth tones with orange accents",
  "artDirection": "minimalist corporate style",
  "aspectRatio": "1:1",
  "resolution": "4K",
  "numberOfGenerations": 2,
  "referenceImageUrls": [
    "https://storage.example.com/style-guide.png"
  ],
  "storageNamespace": "test/infographics"
}
```

## Running Scenarios

### Using CLI

```bash
# Run with scenario file
npx output workflow run workflowName --input path/to/scenarios/basic_input.json

# Run with inline JSON
npx output workflow run workflowName --input '{"content": "test"}'
```

### Example Commands

```bash
# Basic scenario
npx output workflow run contentUtilsImageInfographicNano --input src/workflows/content_utils/image_infographic_nano/scenarios/test_input_solar_panels.json

# Complex scenario
npx output workflow run contentUtilsImageInfographicNano --input src/workflows/content_utils/image_infographic_nano/scenarios/test_input_complex.json
```

**Related Skill**: `output-workflow-run` for detailed CLI usage

## Scenario Categories

### 1. Basic/Happy Path

Minimal valid input to verify the workflow works:

```json
{
  "content": "Simple test content",
  "numberOfIdeas": 1
}
```

### 2. Complete/Full-Featured

All optional fields populated:

```json
{
  "content": "Detailed content...",
  "numberOfIdeas": 5,
  "colorPalette": "custom palette",
  "artDirection": "specific style",
  "aspectRatio": "16:9",
  "resolution": "4K",
  "numberOfGenerations": 3,
  "referenceImageUrls": ["https://example.com/ref.jpg"],
  "storageNamespace": "test/folder"
}
```

### 3. Edge Cases

Test boundary conditions:

**edge_case_min_values.json**
```json
{
  "content": "x",
  "numberOfIdeas": 1
}
```

**edge_case_max_values.json**
```json
{
  "content": "Very long content string...",
  "numberOfIdeas": 10
}
```

### 4. Error Cases (for validation testing)

**error_missing_required.json**
```json
{
  "numberOfIdeas": 3
}
```

Note: Error scenarios won't pass validation but are useful for testing error handling.

## Best Practices

### 1. Document the Purpose

Add a comment field (if supported) or create a companion README:

```json
{
  "_comment": "Tests workflow with multiple reference images",
  "content": "...",
  "referenceImageUrls": ["url1", "url2", "url3"]
}
```

### 2. Use Realistic Data

```json
{
  "content": "Actual representative content that matches real use cases..."
}
```

Not:
```json
{
  "content": "test"
}
```

### 3. Cover All Enum Values

If schema has enums, create scenarios for each:

```json
// scenario_aspect_1x1.json
{ "aspectRatio": "1:1", ... }

// scenario_aspect_16x9.json
{ "aspectRatio": "16:9", ... }

// scenario_aspect_9x16.json
{ "aspectRatio": "9:16", ... }
```

### 4. Include Optional Field Variations

```json
// without_optional_fields.json
{ "content": "..." }

// with_all_optional_fields.json
{ "content": "...", "colorPalette": "...", "artDirection": "..." }

// with_some_optional_fields.json
{ "content": "...", "colorPalette": "..." }
```

### 5. Create Regression Test Scenarios

Save inputs from bug reports:

```json
// regression_issue_123.json
{
  "_issue": "https://github.com/org/repo/issues/123",
  "content": "Input that caused the bug..."
}
```

## Scenario Organization

For workflows with many scenarios, organize into subfolders:

```
scenarios/
├── basic/
│   └── minimal_input.json
├── complete/
│   └── all_options.json
├── edge_cases/
│   ├── empty_array.json
│   └── max_length.json
└── regression/
    └── issue_123.json
```

## Verification Checklist

- [ ] Scenario file located in `scenarios/` folder inside workflow directory
- [ ] File uses `.json` extension
- [ ] File name uses `snake_case`
- [ ] JSON is valid and parseable
- [ ] All required fields from inputSchema are present
- [ ] Field types match schema (strings, numbers, arrays, etc.)
- [ ] Enum values are valid options from schema
- [ ] Numbers are within min/max constraints
- [ ] At least one basic scenario exists
- [ ] Workflow runs successfully with the scenario

## Testing Scenarios

### Validate JSON Syntax

```bash
# Check JSON is valid
cat scenarios/basic_input.json | jq .
```

### Run and Verify

```bash
# Run workflow with scenario
npx output workflow run workflowName --input scenarios/basic_input.json

# Check status if async
npx output workflow status <workflowId>

# Get result
npx output workflow result <workflowId>
```

## Related Skil