TestSmith

A project-agnostic Python test scaffold generator

TestSmith analyzes your Python source code via AST parsing and automatically generates pytest test scaffolds, mock fixtures, and test infrastructure—so you can focus on writing assertions, not boilerplate.

How It Works

TestSmith follows a simple pipeline: Analyze → Classify → Generate

graph LR
    A[Source File] -->|AST Parse| B[Analyze Imports]
    B --> C{Classify Import}
    C -->|stdlib| D[Skip]
    C -->|internal| E[Add to conftest paths]
    C -->|external| F[Generate Mock Fixture]
    
    E --> G[Generate Test File]
    F --> G
    G --> H[Update conftest.py]
    
    style A fill:#4a90d9,color:#fff
    style B fill:#7b68ee,color:#fff
    style G fill:#50c878,color:#fff
    style H fill:#ffa07a,color:#fff

What happens:

Analyze: Parse source file with Python's AST to extract imports, classes, and functions
Classify: Categorize each import as stdlib (skip), internal (add path), or external (mock)
Generate: Create test file with proper structure, mock fixtures for external dependencies
Update: Modify conftest.py to ensure internal imports resolve correctly

Features

Core Functionality

✅ Zero Configuration: Works on any Python project structure
✅ Smart Import Classification: Automatically detects stdlib, internal, and external dependencies
✅ Shared Mock Fixtures: Generates reusable *.fixture.py files for external dependencies
✅ Idempotent: Safe to run multiple times—won't duplicate or break existing tests
✅ Project-Aware: Auto-detects project root and package structure

Advanced Features

🤖 LLM Test Body Generation: Use --generate-bodies to fill in test assertions with AI
📊 Dependency Graph Visualization: Generate Mermaid diagrams with --graph
🧹 Fixture Pruning: Remove unused fixtures with --prune
📈 Coverage Gap Analysis: Identify untested code with --coverage-gaps
👀 Watch Mode: Auto-regenerate tests on file changes with --watch

Distribution

📦 Standalone Binaries: No Python installation required
🐍 PyPI Package: Install with pipx or pip
🖥️ Multi-Platform: Linux, macOS (Intel + Apple Silicon), Windows

Installation

Option 1: Binary (No Python Required)

Download the latest binary for your platform from GitHub Releases:

# Linux
curl -LO https://github.com/orieken/testsmith/releases/latest/download/testsmith-linux-amd64
chmod +x testsmith-linux-amd64
sudo mv testsmith-linux-amd64 /usr/local/bin/testsmith

# macOS (Intel)
curl -LO https://github.com/orieken/testsmith/releases/latest/download/testsmith-macos-amd64
chmod +x testsmith-macos-amd64
sudo mv testsmith-macos-amd64 /usr/local/bin/testsmith

# macOS (Apple Silicon)
curl -LO https://github.com/orieken/testsmith/releases/latest/download/testsmith-macos-arm64
chmod +x testsmith-macos-arm64
sudo mv testsmith-macos-arm64 /usr/local/bin/testsmith

# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/orieken/testsmith/releases/latest/download/testsmith-windows-amd64.exe -OutFile testsmith.exe

Option 2: pipx (Recommended for Python Users)

pipx install testsmith

Option 3: pip

pip install testsmith

Quick Start

1. Initialize TestSmith in Your Project

cd your-project/
testsmith --init

This creates:

tests/ directory
tests/fixtures/ for shared mocks
tests/fixtures/conftest.py for fixture registration

2. Generate Tests for a File

testsmith src/services/payment.py

This creates:

tests/src/services/test_payment.py with test scaffolds
Mock fixtures in tests/fixtures/ for external dependencies
Updates conftest.py with necessary paths

3. Run Your Tests

pytest tests/

Usage Examples

Basic Test Generation

# Generate test for a single file
testsmith src/api/users.py

# Generate tests for all untested files
testsmith --all

# Generate tests for a directory
testsmith --path src/services/

Advanced Features

# Generate test bodies with AI (requires ANTHROPIC_API_KEY)
testsmith src/api/users.py --generate-bodies

# Visualize dependency graph
testsmith --graph --graph-output deps.md

# Find and remove unused fixtures
testsmith --prune --confirm

# Analyze coverage gaps and prioritize testing
testsmith --coverage-gaps

# Watch mode: auto-regenerate on file changes
testsmith --watch

Dry Run Mode

# Preview what would be generated without writing files
testsmith src/api/users.py --dry-run

Configuration

TestSmith works with zero configuration, but you can customize behavior in pyproject.toml:

[tool.testsmith]
test_root = "tests/"
fixture_root = "tests/fixtures/"
exclude_dirs = ["venv", ".venv", "node_modules", "__pycache__"]

Architecture

TestSmith is organized into distinct layers:

src/testsmith/
├── cli.py                  # CLI entry point
├── core/                   # Core analysis engine
│   ├── source_analyzer.py  # AST parsing & import extraction
│   ├── import_classifier.py # stdlib/internal/external classification
│   └── project_detector.py # Project structure detection
├── generation/             # Code generation
│   ├── test_generator.py   # Test file generation
│   ├── fixture_generator.py # Mock fixture generation
│   └── conftest_updater.py # conftest.py management
├── llm/                    # LLM integration
│   └── test_body_generator.py # AI-powered test bodies
├── visualization/          # Dependency graphs
│   ├── graph_builder.py    # Build dependency graphs
│   └── mermaid_renderer.py # Render Mermaid diagrams
├── maintenance/            # Maintenance tools
│   ├── fixture_pruner.py   # Remove unused fixtures
│   └── coverage_analyzer.py # Coverage gap analysis
└── support/                # Shared utilities
    ├── config.py           # Configuration management
    ├── models.py           # Data models
    └── templates.py        # Code templates

See docs/architecture.md for detailed design documentation.

Platform Support

Linux: Ubuntu 20.04+, Debian 10+, RHEL 7+, Fedora 30+, CentOS 7+
macOS: macOS 11+ (Big Sur and later), Intel and Apple Silicon
Windows: Windows 10, Windows 11, Windows Server 2019+

Development

Local Setup

# Clone repository
git clone https://github.com/orieken/testsmith.git
cd testsmith

# Install dependencies (including dev tools)
poetry install --with dev,build

Using Source Version Locally

To use the development version of TestSmith in other projects on your machine:

Activate the environment:

# Activate the virtual environment in your shell
source $(poetry env info --path)/bin/activate

Navigate to your target project:
```
cd ../my-other-project
```

Run TestSmith:

# The 'testsmith' command is now available in your PATH
testsmith --generate-bodies src/app.py

Development Tasks

TestSmith uses poethepoet for task automation. Run poe to see all available tasks:

# Testing
poe test              # Run all tests with coverage
poe test-unit         # Run only unit tests
poe test-integration  # Run only integration tests
poe test-fast         # Stop on first failure, run failed tests first

# Linting & Formatting
poe lint              # Check code with ruff
poe format            # Format code with black
poe format-check      # Check formatting without modifying
poe check             # Run all checks (lint + format + test)

# Building
poe build             # Build binary with PyInstaller
poe build-test        # Build and test binary

# Cleaning
poe clean             # Remove build artifacts and caches

# Development
poe install           # Install all dependencies
poe version           # Show current version

Manual Commands (if not using poe)

# Run tests
poetry run pytest tests/ --cov=src/testsmith --cov-report=term-missing

# Lint
poetry run ruff check src/ tests/
poetry run black --check src/ tests/

Build Binary Locally

# Using poe (recommended)
poe build

# Or using scripts directly
# Linux/macOS
./scripts/build-local.sh

# Windows
.\scripts\build-local.ps1

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Portfolio: https://rieken-portfolio.netlify.app/

About

TestSmith was built as a learning project to explore static code analysis, test automation, and AI-assisted development. Read more about the story and philosophy behind the project in ABOUT.md.

Acknowledgments

Built with:

Python AST for source analysis
pytest for testing framework
Anthropic Claude for LLM test generation
PyInstaller for binary builds
GitHub Actions for CI/CD

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src/testsmith		src/testsmith
tests		tests
.gitignore		.gitignore
ABOUT.md		ABOUT.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
RELEASING.md		RELEASING.md
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
testsmith.spec		testsmith.spec

Folders and files

Latest commit

History

Repository files navigation

TestSmith

How It Works

Features

Core Functionality

Advanced Features

Distribution

Installation

Option 1: Binary (No Python Required)

Option 2: pipx (Recommended for Python Users)

Option 3: pip

Quick Start

1. Initialize TestSmith in Your Project

2. Generate Tests for a File

3. Run Your Tests

Usage Examples

Basic Test Generation

Advanced Features

Dry Run Mode

Configuration

Architecture

Platform Support

Development

Local Setup

Using Source Version Locally

Development Tasks

Manual Commands (if not using poe)

Build Binary Locally

Contributing

License

About

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages