# TDD Plan — `godotiq_build_scene`

Testing framework: pytest + pytest-asyncio (asyncio_mode = "auto")
Test location: `tests/test_tools/test_build_scene.py`
Conventions: Follow existing patterns in `tests/test_tools/` — class-based test grouping, fixtures from `conftest.py`

---

## Section 1: Python-side Tool — `build_scene.py`

### Tests for `validate_build_params`

```python
# Test: no mode specified returns error with clear message
# Test: two modes specified (grid + scatter) returns error
# Test: grid with rows=3, cols=3 passes validation, returns correct params dict
# Test: grid with rows=17, cols=16 (272) returns error mentioning 256 limit
# Test: grid missing rows key returns error
# Test: grid with cols=0 returns error
# Test: grid 1x1 passes (single node)
# Test: line with 2 points passes validation
# Test: line with 1 point returns error (needs >= 2)
# Test: scatter with 3 items passes, returns correct params
# Test: scatter missing items key returns error
# Test: scatter with empty items list returns error
# Test: scatter with 257 items returns error
# Test: nodes list with 4 items passes validation
# Test: nodes empty list returns error
```

### Tests for line node count estimation

```python
# Test: line with 2 points, distance 10, spacing 1.0 estimates ~11 nodes
# Test: line with 3 points (L-shape), total length 10, spacing 2.0 estimates ~6 nodes
# Test: line count estimation matches or exceeds actual GDScript expansion count
```

---

## Section 2: GDScript Handler — `_handle_build_scene`

GDScript tests require a running Godot addon. These are documented for manual testing or future E2E integration.

### Grid expansion tests (manual/E2E)

```
# Test: grid 3x3 with spacing 2.0 creates 9 nodes at correct positions
# Test: grid with override at "1,1" uses override scene and name
# Test: grid with override that has custom position uses that position, not calculated
# Test: grid axis="xy" places nodes in XY plane instead of XZ
# Test: grid with origin=[5,0,5] offsets all positions
```

### Line expansion tests (manual/E2E)

```
# Test: line with 2 points, spacing=1.0, creates correct number of nodes
# Test: line endpoint is included (node at last point)
# Test: line endpoint epsilon check: if last node is very close to endpoint, no duplicate
# Test: line align_to_path rotates nodes to face direction
# Test: line multi-segment carries remainder correctly
```

### Node creation tests (manual/E2E)

```
# Test: node from scene path loads and instantiates
# Test: node from type name creates correct class
# Test: node with invalid scene path returns error (partial success)
# Test: 3D node gets Vector3 position, rotation_degrees, scale
# Test: 2D node gets Vector2 position, scale, no rotation
# Test: custom properties are set via add_do_property
# Test: all created nodes have owner set (for scene saving)
```

### Safety tests (manual/E2E)

```
# Test: GDScript caps at 256 nodes even if more are expanded
# Test: parent not found returns PARENT_NOT_FOUND error
# Test: no scene open returns NO_SCENE error
# Test: single undo (Ctrl+Z) removes all created nodes
```

---

## Section 3: Creation Workflow Prompt

No automated tests. Verify manually that the prompt section is well-formed markdown and references correct tool names.

---

## Section 4: Integration & Backward Compatibility

```python
# Test: all existing tests in tests/ still pass (pytest tests/ -v)
# Test: import godotiq.tools.bridge succeeds (tool registration works)
# Test: godotiq_build_scene is registered as an MCP tool
```
