test: Add automated pytest suite for extension validation

4 test modules covering manifest, commands, structure, and config.
CI workflow runs on Python 3.11/3.12/3.13 via GitHub Actions.

Author: sakitA

.github/workflows/test.yml

@@ -0,0 +1,19 @@
+name: Tests
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install pytest pyyaml
+      - run: pytest

pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "spec-kit-optimize"
+version = "1.0.0"
+requires-python = ">=3.11"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0", "pyyaml>=6.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = ["-v", "--strict-markers", "--tb=short"]

tests/conftest.py

@@ -0,0 +1,40 @@
+"""Shared fixtures for spec-kit-optimize tests."""
+
+import pytest
+import yaml
+from pathlib import Path
+
+
+ROOT = Path(__file__).parent.parent
+
+
+@pytest.fixture
+def root():
+    """Extension root directory."""
+    return ROOT
+
+
+@pytest.fixture
+def manifest(root):
+    """Parsed extension.yml manifest."""
+    with open(root / "extension.yml") as f:
+        return yaml.safe_load(f)
+
+
+@pytest.fixture
+def extension(manifest):
+    """The extension section of the manifest."""
+    return manifest["extension"]
+
+
+@pytest.fixture
+def commands(manifest):
+    """List of provided commands from the manifest."""
+    return manifest["provides"]["commands"]
+
+
+@pytest.fixture
+def config_template(root):
+    """Parsed config-template.yml."""
+    with open(root / "config-template.yml") as f:
+        return yaml.safe_load(f)

tests/test_commands.py

@@ -0,0 +1,71 @@
+"""Tests for command file validation."""
+
+import yaml
+
+
+def test_command_files_exist(root, commands):
+    for cmd in commands:
+        cmd_file = root / cmd["file"]
+        assert cmd_file.exists(), f"Command file not found: {cmd['file']}"
+
+
+def test_command_files_non_empty(root, commands):
+    for cmd in commands:
+        cmd_file = root / cmd["file"]
+        content = cmd_file.read_text(encoding="utf-8")
+        assert len(content.strip()) > 0, f"Command file is empty: {cmd['file']}"
+
+
+def test_command_frontmatter_valid(root, commands):
+    for cmd in commands:
+        cmd_file = root / cmd["file"]
+        content = cmd_file.read_text(encoding="utf-8")
+        assert content.startswith("---"), (
+            f"Command file must start with YAML frontmatter: {cmd['file']}"
+        )
+        end = content.index("---", 3)
+        frontmatter = content[3:end].strip()
+        parsed = yaml.safe_load(frontmatter)
+        assert isinstance(parsed, dict), (
+            f"Frontmatter must be a YAML mapping: {cmd['file']}"
+        )
+
+
+def test_command_frontmatter_has_description(root, commands):
+    for cmd in commands:
+        cmd_file = root / cmd["file"]
+        content = cmd_file.read_text(encoding="utf-8")
+        end = content.index("---", 3)
+        frontmatter = yaml.safe_load(content[3:end])
+        assert "description" in frontmatter, (
+            f"Frontmatter missing 'description': {cmd['file']}"
+        )
+
+
+def test_command_has_markdown_body(root, commands):
+    for cmd in commands:
+        cmd_file = root / cmd["file"]
+        content = cmd_file.read_text(encoding="utf-8")
+        end = content.index("---", 3) + 3
+        body = content[end:].strip()
+        assert len(body) > 100, (
+            f"Command body too short ({len(body)} chars): {cmd['file']}"
+        )
+
+
+def test_command_has_goal_section(root, commands):
+    for cmd in commands:
+        cmd_file = root / cmd["file"]
+        content = cmd_file.read_text(encoding="utf-8")
+        assert "## Goal" in content, (
+            f"Command file missing '## Goal' section: {cmd['file']}"
+        )
+
+
+def test_command_has_execution_steps(root, commands):
+    for cmd in commands:
+        cmd_file = root / cmd["file"]
+        content = cmd_file.read_text(encoding="utf-8")
+        assert "## Execution Steps" in content or "## Execution" in content, (
+            f"Command file missing execution steps: {cmd['file']}"
+        )

tests/test_config.py

@@ -0,0 +1,43 @@
+"""Tests for config template validation."""
+
+import yaml
+
+
+def test_config_template_valid_yaml(root):
+    with open(root / "config-template.yml") as f:
+        config = yaml.safe_load(f)
+    assert isinstance(config, dict), "Config template must be a YAML mapping"
+
+
+def test_config_template_has_categories(config_template):
+    assert "categories" in config_template, "Config template missing 'categories'"
+
+
+def test_config_template_has_thresholds(config_template):
+    assert "thresholds" in config_template, "Config template missing 'thresholds'"
+
+
+def test_defaults_match_config_structure(manifest, config_template):
+    defaults = manifest.get("defaults", {})
+    if "categories" in defaults:
+        for key in defaults["categories"]:
+            assert key in config_template.get("categories", {}), (
+                f"Default category '{key}' not in config template"
+            )
+
+
+def test_threshold_values_positive(config_template):
+    thresholds = config_template.get("thresholds", {})
+    for key, value in thresholds.items():
+        assert isinstance(value, (int, float)), (
+            f"Threshold '{key}' must be numeric, got {type(value).__name__}"
+        )
+        assert value > 0, f"Threshold '{key}' must be positive, got {value}"
+
+
+def test_config_template_documented(root):
+    content = (root / "config-template.yml").read_text(encoding="utf-8")
+    comment_lines = [line for line in content.splitlines() if line.strip().startswith("#")]
+    assert len(comment_lines) >= 5, (
+        f"Config template should have documentation comments (found {len(comment_lines)})"
+    )

tests/test_manifest.py

@@ -0,0 +1,72 @@
+"""Tests for extension.yml manifest validation."""
+
+import re
+
+
+def test_schema_version(manifest):
+    assert manifest["schema_version"] == "1.0"
+
+
+def test_required_fields(extension):
+    required = ["id", "name", "version", "description", "author", "repository", "license"]
+    for field in required:
+        assert field in extension, f"Missing required field: extension.{field}"
+
+
+def test_id_format(extension):
+    assert re.match(r"^[a-z0-9-]+$", extension["id"]), (
+        f"Extension ID must be lowercase with hyphens only, got: {extension['id']}"
+    )
+
+
+def test_version_semver(extension):
+    assert re.match(r"^\d+\.\d+\.\d+$", extension["version"]), (
+        f"Version must follow semver (X.Y.Z), got: {extension['version']}"
+    )
+
+
+def test_description_length(extension):
+    assert len(extension["description"]) < 200, (
+        f"Description too long: {len(extension['description'])} chars (max 200)"
+    )
+
+
+def test_repository_url(extension):
+    assert extension["repository"].startswith("https://"), (
+        f"Repository must be an HTTPS URL, got: {extension['repository']}"
+    )
+
+
+def test_tags_present(manifest):
+    tags = manifest.get("tags", [])
+    assert 2 <= len(tags) <= 10, f"Expected 2-10 tags, got {len(tags)}"
+
+
+def test_tags_lowercase(manifest):
+    for tag in manifest.get("tags", []):
+        assert tag == tag.lower(), f"Tag must be lowercase: {tag}"
+
+
+def test_command_naming(manifest):
+    ext_id = manifest["extension"]["id"]
+    for cmd in manifest["provides"]["commands"]:
+        name = cmd["name"]
+        assert name.startswith(f"speckit.{ext_id}."), (
+            f"Command name must match speckit.{ext_id}.<cmd>, got: {name}"
+        )
+
+
+def test_command_has_description(manifest):
+    for cmd in manifest["provides"]["commands"]:
+        assert "description" in cmd, f"Command {cmd['name']} missing description"
+        assert len(cmd["description"]) > 0, f"Command {cmd['name']} has empty description"
+
+
+def test_command_has_file(manifest):
+    for cmd in manifest["provides"]["commands"]:
+        assert "file" in cmd, f"Command {cmd['name']} missing file reference"
+
+
+def test_requires_speckit_version(manifest):
+    assert "requires" in manifest
+    assert "speckit_version" in manifest["requires"], "Missing requires.speckit_version"

tests/test_structure.py

@@ -0,0 +1,60 @@
+"""Tests for extension file structure."""
+
+from pathlib import Path
+
+
+def test_required_files_exist(root):
+    required = ["extension.yml", "README.md", "LICENSE"]
+    for filename in required:
+        assert (root / filename).exists(), f"Required file missing: {filename}"
+
+
+def test_recommended_files_exist(root):
+    recommended = ["CHANGELOG.md"]
+    for filename in recommended:
+        assert (root / filename).exists(), f"Recommended file missing: {filename}"
+
+
+def test_config_template_exists(root, manifest):
+    configs = manifest.get("provides", {}).get("config", [])
+    for cfg in configs:
+        template = cfg.get("template")
+        if template:
+            assert (root / template).exists(), (
+                f"Config template not found: {template}"
+            )
+
+
+def test_no_stale_command_files(root, commands):
+    declared_files = {cmd["file"] for cmd in commands}
+    commands_dir = root / "commands"
+    if commands_dir.exists():
+        actual_files = {
+            f"commands/{f.name}" for f in commands_dir.glob("*.md")
+        }
+        stale = actual_files - declared_files
+        assert not stale, (
+            f"Stale command files not declared in manifest: {stale}"
+        )
+
+
+def test_commands_directory_exists(root):
+    assert (root / "commands").is_dir(), "commands/ directory missing"
+
+
+def test_license_not_empty(root):
+    content = (root / "LICENSE").read_text(encoding="utf-8")
+    assert len(content.strip()) > 50, "LICENSE file appears empty or too short"
+
+
+def test_readme_has_installation(root):
+    content = (root / "README.md").read_text(encoding="utf-8")
+    assert "install" in content.lower(), "README.md missing installation instructions"
+
+
+def test_readme_has_commands(root, commands):
+    content = (root / "README.md").read_text(encoding="utf-8")
+    for cmd in commands:
+        assert cmd["name"] in content, (
+            f"README.md does not document command: {cmd['name']}"
+        )