# Add Test Cases to Question Files - Context Prompt

## Overview

This document provides context for adding `function_signature` and `test_cases` sections to question YAML files in the CodeTutor project.

## Current Status

- **Total question files**: 401
- **Files with test cases**: 120
- **Files needing test cases**: ~281

## File Location

All question files are in: `/mnt/work/dev/portfolio/codetutor/backend/data/questions/`

## YAML Structure

Each question file should have `function_signature` and `test_cases` sections placed **after the `patterns` section and before the `description` section**.

### Example Structure

```yaml
title: Two Sum
slug: two-sum
difficulty: easy
leetcode_id: 1
leetcode_url: https://leetcode.com/problems/two-sum/
categories:
  - arrays
  - hash-tables
patterns:
  - two-pointers

function_signature: "def two_sum(nums: list[int], target: int) -> list[int]:"

test_cases:
  visible:
    - input: { nums: [2, 7, 11, 15], target: 9 }
      expected: [0, 1]
    - input: { nums: [3, 2, 4], target: 6 }
      expected: [1, 2]
    - input: { nums: [3, 3], target: 6 }
      expected: [0, 1]
  hidden:
    - input: { nums: [1, 5, 3, 7, 2], target: 10 }
      expected: [2, 3]
    - input: { nums: [-1, -2, -3, -4, -5], target: -8 }
      expected: [2, 4]
    - input: { nums: [0, 4, 3, 0], target: 0 }
      expected: [0, 3]

description: |
  Given an array of integers...
```

## Function Signature Conventions

- Use Python type hints: `list[int]`, `str`, `int`, `bool`, `list[list[int]]`
- Use snake_case for function and parameter names
- Match LeetCode's function signature where possible, but use Pythonic naming:
  - `twoSum` → `two_sum`
  - `numCourses` → `num_courses`
  - `obstacleGrid` → `obstacle_grid`

### Special Types

For linked lists and trees, use:
- `ListNode` for linked list problems
- `TreeNode` for binary tree problems

Example:
```yaml
function_signature: "def reorder_list(head: ListNode) -> None:"
function_signature: "def diameter_of_binary_tree(root: TreeNode) -> int:"
```

## Test Case Guidelines

### Visible Tests (2-3 cases)
- Include the examples from the problem description
- Cover basic happy path scenarios
- Keep inputs simple and easy to understand

### Hidden Tests (5-7 cases)
- **Edge cases**: empty inputs, single elements, nulls
- **Boundary conditions**: min/max values, overflow scenarios
- **Special patterns**: all same values, strictly increasing/decreasing
- **Negative numbers**: if applicable
- **Large inputs**: for performance edge cases

### Data Types in YAML

```yaml
# Arrays
input: { nums: [1, 2, 3] }

# Strings (use quotes)
input: { s: "hello" }

# Nested arrays (matrices)
input: { grid: [[0, 0, 0], [0, 1, 0], [0, 0, 0]] }

# Multiple parameters
input: { nums: [1, 2, 3], target: 6 }

# Boolean expected values
expected: true
expected: false

# Linked lists (as arrays)
input: { head: [1, 2, 3, 4] }
expected: [1, 4, 2, 3]

# Trees (level-order with nulls)
input: { root: [1, 2, 3, null, 4] }
```

## Finding Files Without Test Cases

Run this command to find files missing the `function_signature`:

```bash
cd /mnt/work/dev/portfolio/codetutor/backend/data/questions
for f in *.yaml; do
  if ! grep -q "^function_signature:" "$f"; then
    echo "$f"
  fi
done
```

Or use grep to count:
```bash
grep -L "^function_signature:" *.yaml | wc -l
```

## Workflow

1. **Read the problem file** to understand:
   - The function parameters and return type
   - Example inputs/outputs from the `examples` section
   - Constraints for edge case ideas

2. **Add the sections** after `patterns:` and before `description:`

3. **Verify YAML syntax** - ensure proper indentation (2 spaces)

4. **Commit in batches** with message format:
   ```
   feat(content): add test cases for N additional problems
   ```

## Priority Problems

Focus on commonly asked interview problems first:
- LeetCode Top 100
- Blind 75
- NeetCode 150

### Categories Still Needing Coverage

Run this to see which files still need test cases:
```bash
grep -L "^function_signature:" *.yaml | head -50
```

## Example: Adding Tests to a New File

### Before (file without tests):
```yaml
patterns:
  - sliding-window

description: |
  ...
```

### After (file with tests):
```yaml
patterns:
  - sliding-window

function_signature: "def max_sliding_window(nums: list[int], k: int) -> list[int]:"

test_cases:
  visible:
    - input: { nums: [1, 3, -1, -3, 5, 3, 6, 7], k: 3 }
      expected: [3, 3, 5, 5, 6, 7]
    - input: { nums: [1], k: 1 }
      expected: [1]
  hidden:
    - input: { nums: [9, 11], k: 2 }
      expected: [11]
    - input: { nums: [4, 3, 2, 1], k: 2 }
      expected: [4, 3, 2]
    - input: { nums: [7, 7, 7, 7], k: 3 }
      expected: [7, 7]

description: |
  ...
```

## Changelog Update

After committing, update `/mnt/work/dev/portfolio/codetutor/changelog.md`:

```markdown
## [Unreleased]

### Added

- Test cases for N additional questions bringing total to M:
  - Category: problem1, problem2, problem3
  - Category: problem4, problem5
```

## Notes

- The test runner uses Pyodide (Python in WebAssembly) to execute code
- Visible tests run client-side; hidden tests are validated server-side
- Expected outputs must be JSON-serializable
- Order matters for list outputs unless the problem states "any order"