Test scaffolding

Test Scaffolding Skill

Generate test file scaffolds for source files, enabling TDD workflows. Scaffolds contain TODO stubs that the test-engineer agent fills during lane execution.

Variables

Variable	Default	Description
SOURCE_FILES	[]	List of source files to scaffold tests for
TEST_FRAMEWORK	auto	Framework to use (auto-detects from manifest)
OUTPUT_DIR	tests/	Where to place generated test files
NAMING_CONVENTION	language-default	Test file naming pattern
INCLUDE_FIXTURES	true	Generate fixture stubs
STUB_STYLE	todo	todo (TODO comments) or skip (skip markers)

Workflow (Mandatory)

1. Detect stack: Read package manifest (pyproject.toml, package.json, go.mod, Cargo.toml)
2. Identify framework: Match test dependencies (pytest, vitest, jest, testing, cargo test)
3. Analyze sources: Extract public functions, classes, methods from each source file
4. Map to tests: Apply naming convention to determine test file paths
5. Generate scaffolds: Use language template, insert TODO stubs for each testable unit
6. Return manifest: JSON with generated files, skipped files, and unit counts

Supported Frameworks

Language	Frameworks	Detection
Python	pytest, unittest	pyproject.toml → [tool.pytest] or pytest in deps
TypeScript	vitest, jest	package.json → vitest or jest in devDeps
JavaScript	vitest, jest	package.json → vitest or jest in devDeps
Go	testing	go.mod → built-in testing package
Rust	cargo test	Cargo.toml → built-in test harness
Dart	flutter_test, test	pubspec.yaml → flutter_test or test in dev_deps

Naming Conventions

Language	Source	Test File
Python	src/auth/login.py	tests/auth/test_login.py
TypeScript	src/auth/login.ts	src/auth/login.test.ts or tests/auth/login.test.ts
Go	pkg/auth/login.go	pkg/auth/login_test.go
Rust	src/auth/login.rs	inline #[cfg(test)] module
Dart	lib/auth/login.dart	test/auth/login_test.dart

Source Analysis Heuristics

Python

• Detect def function_name( where name doesn't start with _
• Detect class ClassName: for public classes
• Extract method signatures within classes
• Skip __init__, __str__, etc. (dunder methods)

TypeScript/JavaScript

• Detect export function, export const, export class
• Detect export default function/class
• Parse JSDoc/TSDoc for parameter types

Go

• Detect exported functions (capitalized names)
• Detect exported methods on structs
• Detect exported types

Rust

• Detect pub fn, pub struct, pub enum
• Detect impl blocks with public methods

Output Schema

{
  "format": "scaffold-manifest/v1",
  "generated_at": "<ISO-8601 UTC>",
  "framework": "pytest",
  "generated": [
    {
      "source": "src/auth/login.py",
      "test": "tests/auth/test_login.py",
      "units": ["login", "logout", "refresh_token"],
      "unit_count": 3
    }
  ],
  "skipped": [
    {
      "source": "src/auth/utils.py",
      "reason": "test file exists"
    }
  ],
  "total_units": 12
}

Red Flags (Stop & Verify)

• No package manifest found → prompt user for framework
• Source file has no public functions → skip with warning
• Test file already exists → skip unless --force specified
• Unable to parse source file → log warning, continue with others

Integration Points

With /ai-dev-kit:plan-phase

• Called to auto-populate Tests Owned Files column
• Uses Owned Artifacts from impl tasks as source files

With /ai-dev-kit:execute-lane

• Called before test-engineer agent runs
• Scaffolds committed with chore(P{n}-{lane}): scaffold test files

With test-engineer agent

• Agent detects TODO markers in scaffolds
• Fills in test implementations
• Removes TODO markers when complete

Provider Notes

• Use this skill when /ai-dev-kit:scaffold-tests is invoked
• Prefer TODO-style stubs over skip markers for visibility
• Preserve source file structure in test organization
• Include proper imports based on detected framework