Imported from se2p/pynguin (AGENTS.md). Install upstream with npx skills add se2p/pynguin. Copyright stays with the author.

Pynguin - Automated Unit Test Generation for Python

Purpose

Pynguin (IPA: ˈpɪŋɡuiːn) is a research tool for automated generation of unit tests for Python programs. It uses search-based techniques (genetic algorithms) to automatically generate test suites that achieve high code coverage. The tool is developed at the University of Passau and represents the first fully-automated unit test generator for general-purpose Python programs.

Project Status

• Python Support: 3.10 (stable), 3.11-3.14 (experimental)
• License: MIT

Key Files

Subdirectories

For AI Agents

Working In This Project

1. Development Setup:

   • Use Poetry for dependency management: poetry install
   • Python 3.10+ required
   • Run make check before committing (runs tests, linting, type checking)

2. Code Quality Standards:

   • Linting: Ruff (extensive ruleset enabled, see pyproject.toml)
   • Type Checking: mypy with strict settings
   • Formatting: Black formatter
   • Documentation: Google-style docstrings
   • Testing: pytest with >80% coverage requirement

Testing Requirements

• Unit Tests: Located in tests/ mirroring src/ structure
• Coverage: Minimum 80%, configured in tool.coverage section
• Test Framework: pytest with plugins (pytest-cov, pytest-mock, pytest-sugar)
• Run Tests: make test or pytest tests/
• Coverage Report: make cov generates HTML report in cov_html/

Common Patterns

1. Module Structure:

   • Source code in src/pynguin/
   • Tests in tests/ with same directory structure
   • Fixtures in tests/fixtures/ organized by feature area

2. Genetic Algorithm Architecture:

   • Algorithms in src/pynguin/ga/algorithms/
   • Operators (crossover, selection, mutation) in src/pynguin/ga/operators/
   • Test case representation in src/pynguin/testcase/

3. Instrumentation:

   • Code instrumentation in src/pynguin/instrumentation/
   • Version-specific handling in src/pynguin/instrumentation/version/
   • Instrumentation transformations for coverage tracking

4. Type System:

   • Type tracing and inference throughout codebase
   • Active optimization work to reduce execution overhead
   • Fixtures in tests/fixtures/type_tracing/

5. LLM Integration (Optional):

   • Large language model features in src/pynguin/large_language_model/
   • Requires openai extra: poetry install --extras openai
   • Assertion generation and test case prompting

Dependencies

Core Dependencies

• bytecode - Python bytecode manipulation
• networkx - Graph algorithms (for control flow)
• pytest - Testing framework (used both for running Pynguin and generated tests)
• black - Code formatting
• libcst - Concrete syntax tree manipulation
• Jinja2 - Template engine (for test generation)

Optional Features ("--extras")

Development Dependencies

• mypy - Static type checking
• ruff - Fast Python linter
• pre-commit - Git hooks for code quality
• sphinx - Documentation generation
• coverage - Code coverage measurement
• hypothesis - Property-based testing

Architecture Overview

Pynguin Test Generation Pipeline:
1. Module Analysis → Parse Python code, build control flow graph
2. Algorithm Selection → Choose search strategy (DYNAMOSA, MIO, MOSA, etc.)
3. Test Generation → Genetic algorithm evolves test cases
4. Assertion Generation → Add assertions via mutation analysis or LLM
5. Output → Generated test suite as executable pytest tests

Key Components

• GA (Genetic Algorithms): Core search-based test generation
• Instrumentation: Runtime code monitoring for coverage tracking
• Assertion Generation: Automated oracle creation
• Test Case Representation: Internal model for test cases
• Slicer: Program slicing for focused testing
• Resources: Test data generation (primitives, objects, collections)

Common Tasks

Navigation Tips

• For algorithm work: See src/pynguin/ga/AGENTS.md
• For instrumentation: See src/pynguin/instrumentation/AGENTS.md
• For test case structure: See src/pynguin/testcase/AGENTS.md
• For LLM features: See src/pynguin/large_language_model/AGENTS.md
• For examples: Browse tests/fixtures/ subdirectories

AI Agent Development Guidelines

1. Code Quality Standards

SPDX Headers: All new source files must start with an SPDX license header:

# This file is part of the Pynguin automated unit test generation framework.
# Copyright (C) 2024 Lukas Krodinger
# SPDX-License-Identifier: MIT

Type Hints & Imports:

• Use from __future__ import annotations at the top of all new modules
• All function parameters and return types must have type hints
• Enable strict mypy checking: mypy src/

Documentation:

• Use Google-style docstrings for all public functions and classes
• Include Args, Returns, and Raises sections where applicable
• Example:

def generate_tests(module: str, timeout: int = 60) -> list[TestCase]:
    """Generate unit tests for the specified module.

    Args:
        module: Full module path (e.g., 'foo.bar.baz')
        timeout: Maximum generation time in seconds

    Returns:
        List of generated test cases

    Raises:
        ValueError: If module cannot be imported
    """

Formatting:

• Use Ruff for all formatting
• Maximum line length: 100 characters
• Run: ruff check --fix src/ and ruff format src/

2. Testing Requirements

Test Structure:

• Unit tests located in tests/ mirroring src/ directory structure
• Example: Source at src/pynguin/ga/foo.py → Test at tests/ga/test_foo.py

Testing Workflow:

• Run before committing: make test or pytest tests/
• Use pytest fixtures from tests/fixtures/ for common patterns
• Use parametrized tests for multiple input scenarios
• Test framework: pytest with plugins (pytest-cov, pytest-mock, pytest-sugar)

3. File Modification Boundaries

Can Modify:

• src/ - Main source code
• tests/ - Test suite
• docs/ - Documentation
• AGENTS.md - This file (in manual section only)

Cannot Modify (Without Explicit Authorization):

• pyproject.toml - Poetry configuration and dependency management
• poetry.lock - Dependency lock file
• .github/workflows/ - CI/CD configurations
• .git/ - Git internals

Dependency Changes:

• Do NOT modify pyproject.toml for dependency changes without discussion
• Consult with project maintainers before adding new dependencies

4. Pre-commit Workflow

Before Every Commit:

1. Run pre-commit hooks:

   pre-commit run --all-files

2. May need to run twice if Ruff reformats files:

   pre-commit run --all-files
   pre-commit run --all-files  # Run again if first run made changes

3. Verify all checks pass before committing

4. Run full test suite:

   make test

5. Common Restrictions

Version Control:

• No pushing to remote repositories
• No force-pushing or rewriting history

CI/CD & Dependencies:

• Do not modify CI/CD configurations (.github/workflows/)
• Do not change dependency versions in poetry.lock
• Do not add new dependencies without discussion

Development Practices:

• Always work on feature branches (not main)
• Commit frequently with clear messages
• Create pull requests for review before merging to main

6. Quick Reference Checklist

Before marking work complete:

• Code follows SPDX header format (if new file)
• Type hints added with from __future__ import annotations
• Google-style docstrings for all public APIs
• Ruff formatting: ruff check --fix && ruff format
• Tests written/updated in tests/ mirroring src/
• Pre-commit passes: pre-commit run --all-files (twice if needed)
• All tests pass: make test
• No modifications to protected files (pyproject.toml, poetry.lock, CI/CD)