# Sprint 0 Scaffolding - Integration & E2E Test Skeletons

Design Doc: `docs/design/sprint-0-scaffolding.md`
Generated: 2026-03-02 | Budget Used: 3/3 integration, 1/2 E2E

## Generation Report

```json
{
  "status": "completed",
  "feature": "sprint-0-scaffolding",
  "generatedFiles": {
    "integration": "tests/test_scaffolding_int.py",
    "e2e": "tests/test_scaffolding_e2e.py"
  },
  "budgetUsage": {
    "integration": "3/3",
    "e2e": "1/2"
  },
  "filteredOut": {
    "AC-4 (Parser dataclasses)": "UNIT_LEVEL - pure Python instantiation, already in test_server.py",
    "AC-5 (FileCache operations)": "UNIT_LEVEL - in-memory logic with simple fs access, ROI 32",
    "AC-6 (Config loader)": "DUPLICATE - already covered by test_config_defaults and test_config_loads_json in test_server.py"
  }
}
```

## ROI Summary

| Test | AC Coverage | ROI Score | Rationale |
|------|-------------|-----------|-----------|
| INT-1: Project structure complete | AC-1, AC-8 | 70 | Verifies all dirs, init files, config files exist |
| INT-2: All modules importable | AC-2, AC-3, AC-7 (partial) | 90 | Verifies install produces working Python packages |
| INT-3: MCP server ping tool registered | AC-3 | 100 | Core functionality: server starts, tool responds |
| E2E-1: Full install-test-import cycle | AC-7 | Critical | Full user journey: pip install -> pytest -> import |

---

## Integration Test File: `tests/test_scaffolding_int.py`

```python
# Sprint 0 Scaffolding Integration Tests - Design Doc: sprint-0-scaffolding.md
# Generated: 2026-03-02 | Budget Used: 3/3 integration, 0/2 E2E
# Framework: pytest + pytest-asyncio (detected from AC-2 dev dependencies)

import pytest
from pathlib import Path


# ---------------------------------------------------------------------------
# INT-1: Project structure matches specification
# ---------------------------------------------------------------------------
# AC-1: "Directory structure matches the specification exactly"
# AC-8: "Configuration files present and valid"
# ROI: 70 | Business Value: 8 (foundation for all future sprints) | Frequency: 8
# Behavior: After scaffolding -> All specified dirs, __init__.py, .gitkeep,
#           and config files exist at their expected paths
# @category: core-functionality
# @dependency: filesystem
# @complexity: medium
#
# Verification items:
# - src/ and all sub-packages exist (src/, src/parsers/, src/cache/, src/tools/)
# - All 9 tool category directories exist under src/tools/
#   (bridge, spatial, code, animation, flow, assets, memory, ui, navigation)
# - Every Python package directory contains __init__.py
# - Empty directories contain .gitkeep (tests/fixtures/, test_parsers/, test_tools/,
#   godot-addon/addons/godotiq/)
# - Root config files present: pyproject.toml, .gitignore, CLAUDE.md, README.md,
#   .godotiq.example.json, LICENSE
# - Parser files exist: tscn_parser.py, gd_parser.py, tres_parser.py
# - Core files exist: server.py, config.py, file_cache.py
#
# Pass criteria: All paths resolve to existing files/directories on disk.
#   No missing entries compared to the specification tree.

class TestProjectStructureComplete:

    def test_ac1_ac8_project_structure_matches_specification(self):
        # Arrange: Determine project root (parent of tests/)
        # Act: Walk the expected directory tree from the design doc
        # Assert: Every specified path exists; every package has __init__.py;
        #         every empty dir has .gitkeep; all config files at root
        ...


# ---------------------------------------------------------------------------
# INT-2: All source modules importable after install
# ---------------------------------------------------------------------------
# AC-2: "pyproject.toml valid and installable"
# AC-3: "src/server.py imports and initializes mcp.server.Server" (import side)
# AC-7: "python -c 'from src.server import server; print(OK)' works" (partial)
# ROI: 90 | Business Value: 10 (blocks all development if broken) | Frequency: 9
# Behavior: After editable install -> every module under src/ can be imported
#           without error, and key symbols are accessible
# @category: core-functionality
# @dependency: src, pyproject.toml, pip install
# @complexity: medium
#
# Verification items:
# - `from src.server import server, main` succeeds
# - `from src.parsers.tscn_parser import TscnNode, TscnScene, parse_tscn` succeeds
# - `from src.parsers.gd_parser import GdSignal, GdFunction, GdScript, parse_gd` succeeds
# - `from src.parsers.tres_parser import parse_tres` succeeds
# - `from src.cache.file_cache import FileCache, CacheEntry` succeeds
# - `from src.config import load_config, GodotIQConfig` succeeds
# - All 9 tool category packages importable (src.tools.bridge, etc.)
# - No circular import errors
#
# Pass criteria: All imports complete without ImportError or ModuleNotFoundError.

class TestAllModulesImportable:

    def test_ac2_ac3_all_source_modules_import_without_error(self):
        # Arrange: (none - relies on editable install already done)
        # Act: Import every public module and symbol specified in the design doc
        # Assert: No ImportError raised; key classes/functions are callable types
        ...


# ---------------------------------------------------------------------------
# INT-3: MCP server initializes with ping tool registered and responsive
# ---------------------------------------------------------------------------
# AC-3: "Registers a godotiq_ping tool returning {'status': 'ok', 'version': '0.1.0'}"
# AC-3: "Has a main() function that starts the server with stdio transport"
# ROI: 100 | Business Value: 10 (core MCP contract) | Frequency: 10 | Defect: 10
# Behavior: Server instance created -> tool list includes godotiq_ping ->
#           calling ping returns exact expected payload
# @category: core-functionality
# @dependency: src.server, mcp SDK
# @complexity: high
#
# Verification items:
# - Server instance is created without error
# - server.list_tools() (or equivalent MCP SDK introspection) includes "godotiq_ping"
# - Invoking the godotiq_ping tool returns exactly {"status": "ok", "version": "0.1.0"}
# - Response content type is text (MCP TextContent)
# - main() function exists and is callable
#
# Pass criteria: godotiq_ping is discoverable in the tool registry and returns
#   the exact JSON payload specified. No other tools are registered in Sprint 0.

class TestMcpServerPingToolRegistered:

    @pytest.mark.asyncio
    async def test_ac3_ping_tool_registered_and_returns_correct_response(self):
        # Arrange: Import server, obtain tool registry or handler reference
        # Act: List registered tools; invoke godotiq_ping handler
        # Assert: Tool name present in registry; response matches
        #         {"status": "ok", "version": "0.1.0"} exactly
        ...
```

---

## E2E Test File: `tests/test_scaffolding_e2e.py`

```python
# Sprint 0 Scaffolding E2E Test - Design Doc: sprint-0-scaffolding.md
# Generated: 2026-03-02 | Budget Used: 1/2 E2E
# Test Type: End-to-End Test
# Implementation Timing: After all Sprint 0 implementations complete
# Framework: pytest (subprocess-based, no fixtures from the project itself)

import pytest


# ---------------------------------------------------------------------------
# E2E-1: Full install -> pytest -> import cycle
# ---------------------------------------------------------------------------
# User Journey: Developer clones repo -> pip install -e ".[dev]" -> pytest ->
#               import smoke check -> all green
# AC-7: "pip install -e '.[dev]' completes without errors"
# AC-7: "pytest runs and ALL tests pass (6+ tests)"
# AC-7: "python -c 'from src.server import server; print(OK)' works"
# ROI: Critical (business-critical user journey, gates all future development)
# Business Value: 10 | Frequency: 10 (every developer, every clone) | Legal: false
# @category: e2e
# @dependency: full-system (pyproject.toml, all src/, all tests/)
# @complexity: high
#
# Verification items:
# - `pip install -e ".[dev]"` exits with code 0 (no build errors)
# - `pytest` exits with code 0 (all tests pass)
# - pytest output reports 6 or more tests collected and passed
# - `python -c "from src.server import server; print('OK')"` exits 0, stdout contains "OK"
#
# Pass criteria: All three subprocess commands succeed with exit code 0.
#   pytest reports zero failures. Import smoke check prints "OK".
#
# Implementation notes:
# - Use subprocess.run() with check=True in a temporary virtualenv or
#   the current test environment
# - Capture stdout/stderr for diagnostic output on failure
# - Consider using tmp_path or venv isolation to avoid polluting the
#   test runner's environment

class TestFullInstallTestImportCycle:

    def test_ac7_full_install_pytest_import_cycle(self):
        # Arrange: Determine project root; optionally create isolated venv
        # Act:
        #   Step 1: Run `pip install -e ".[dev]"` as subprocess
        #   Step 2: Run `pytest` as subprocess, capture output
        #   Step 3: Run `python -c "from src.server import server; print('OK')"` as subprocess
        # Assert:
        #   - All three commands return exit code 0
        #   - pytest output contains "passed" and no "failed"
        #   - pytest collected >= 6 tests
        #   - Import check stdout contains "OK"
        ...
```

---

## Relationship to Existing `tests/test_server.py`

The sprint spec already defines 6 unit tests in `tests/test_server.py`:

| Existing Unit Test | AC | Why NOT duplicated here |
|---|---|---|
| `test_server_instance_created` | AC-3 | Unit: checks object creation. INT-3 checks tool registration + response. |
| `test_ping_tool_registered` | AC-3 | Unit: checks tool name in list. INT-3 checks full invocation + payload. |
| `test_ping_returns_expected` | AC-3 | Unit: checks return value. INT-3 verifies via MCP protocol path. |
| `test_parser_stubs_raise` | AC-4 | Unit-level, filtered out (UNIT_LEVEL). |
| `test_config_defaults` | AC-6 | Unit-level, filtered out (DUPLICATE). |
| `test_config_loads_json` | AC-6 | Unit-level, filtered out (DUPLICATE). |

The integration tests (INT-1, INT-2, INT-3) and E2E test (E2E-1) operate at a higher abstraction level:
- INT-1 validates the entire filesystem layout as a cohesive whole
- INT-2 validates that all modules form a valid, importable Python package
- INT-3 validates the MCP tool registration through the full server pathway
- E2E-1 validates the complete developer onboarding journey (clone -> install -> test -> use)

No overlap with existing unit test coverage.

---

## Filtered ACs (with justification)

| AC | Filter Reason | Recommendation |
|---|---|---|
| AC-4 (Parser placeholders) | UNIT_LEVEL - Pure dataclass instantiation and NotImplementedError. Already covered by `test_parser_stubs_raise` in test_server.py. | Keep as unit test only. |
| AC-5 (FileCache operations) | UNIT_LEVEL - In-memory data structure with simple mtime check. ROI 32, below integration threshold. | Add unit tests in `tests/test_cache.py` during Sprint 0 implementation if not already planned. |
| AC-6 (Config loader) | DUPLICATE - Already covered by `test_config_defaults` and `test_config_loads_json` in test_server.py. Filesystem interaction is minimal (read one JSON file). | Keep as unit test only. |
