Metadata-Version: 2.5
Name: testuary
Version: 0.2.1
Summary: Test generation with coverage and mutation feedback for Python, Java and C
Project-URL: Homepage, https://github.com/k-kammler/testuary
Project-URL: Repository, https://github.com/k-kammler/testuary
Project-URL: Documentation, https://k-kammler.github.io/testuary/
Project-URL: Issues, https://github.com/k-kammler/testuary/issues
Project-URL: Changelog, https://github.com/k-kammler/testuary/blob/main/CHANGELOG.md
Project-URL: LangAdapter, https://github.com/k-kammler/langadapter
Author: Kevin Kammler
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: src/testuary/demo/data/LICENSE-tenacity.txt
License-File: src/testuary/demo/data/java/LICENSE-jsonassert.txt
License-File: src/testuary/demo/data/tutorial/LICENSE-tenacity.txt
Keywords: agent,automated-testing,llm,mutation-testing,test-generation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cosmic-ray==8.4.1
Requires-Dist: coverage==7.16.2; python_version >= '3.14'
Requires-Dist: coverage==7.6.8; python_version < '3.14'
Requires-Dist: httpx[socks]<1,>=0.28
Requires-Dist: langadapter<0.2,>=0.1.1
Requires-Dist: langchain-core<2.0,>=1.4
Requires-Dist: langchain-openai<1.7,>=1.6
Requires-Dist: langgraph<2.0,>=1.2
Requires-Dist: lizard<2,>=1.17
Requires-Dist: openai<4,>=2.0
Requires-Dist: platformdirs<5,>=4.0
Requires-Dist: psutil<8,>=7.0
Requires-Dist: pulp==3.3.2
Requires-Dist: pydantic<3.0,>=2.12
Requires-Dist: pytest==8.1.1; python_version < '3.14'
Requires-Dist: pytest==8.4.2; python_version >= '3.14'
Requires-Dist: python-json-logger<5,>=4.0
Requires-Dist: rich<16,>=14
Requires-Dist: tenacity!=8.4.0,<10,>=8.1
Requires-Dist: typing-extensions<5,>=4.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: packaging>=22; extra == 'dev'
Requires-Dist: pytest-cov==6.2.1; extra == 'dev'
Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]<1,>=0.26; extra == 'docs'
Requires-Dist: pymdown-extensions<12,>=10; extra == 'docs'
Description-Content-Type: text/markdown

# Testuary

[![PyPI version](https://img.shields.io/pypi/v/testuary?color=green)](https://pypi.org/project/testuary/)
[![Python versions](https://img.shields.io/pypi/pyversions/testuary?color=green)](https://pypi.org/project/testuary/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/k-kammler/testuary/blob/main/LICENSE)
[![Documentation](https://github.com/k-kammler/testuary/actions/workflows/docs.yml/badge.svg)](https://k-kammler.github.io/testuary/)

Testuary writes unit tests for Python, Java and C code with a language model.
It runs the tests, measures which lines and branches they cover and how many
mutants (small deliberate bugs) they catch, and asks the model for more tests
wherever something is still missed, until your goals or limits are reached.
It then keeps only the tests that add coverage or catch an extra mutant, and
hands you the finished test suite with its measurements.

Testuary is built to be extended: your own model service, prompt profile,
hints for your project or a new language each come as one file, or a few
lines in one. Running and measuring the tests is the job of
[LangAdapter](https://github.com/k-kammler/langadapter), a separate package
that installs with Testuary.

## Supported systems

| Projects in | Windows | Linux | macOS |
| --- | --- | --- | --- |
| Python | yes | yes | expected to work |
| Java | yes | yes | expected to work |
| C | in WSL | yes | not yet supported |

Testuary was tested on Windows 11, Ubuntu 24.04 under WSL and AlmaLinux 8.10.
This release has not run on a Mac. On Windows, C projects run with Testuary
installed inside [WSL](https://k-kammler.github.io/testuary/guide/machine/#windows-with-wsl).
[Tested environments](https://k-kammler.github.io/testuary/reference/tested-environments/)
says what is known.

## Install

Testuary runs on Python 3.10 or newer. Install Testuary into a virtual
environment of its own, outside the directory of the project you test, as
[getting started](https://k-kammler.github.io/testuary/getting-started/#install)
explains:

```bash
python3 -m venv testuary-env
source testuary-env/bin/activate
python -m pip install testuary
```

On Windows, create the environment with `python -m venv testuary-env` and
activate it with `testuary-env\Scripts\activate` in cmd or PowerShell. In
PowerShell, run `Set-ExecutionPolicy -Scope Process RemoteSigned` first: the
default policy of Windows PowerShell refuses the activation script, and this
command allows local scripts in that window only. On Debian and Ubuntu,
`python3 -m venv` needs the package `python3-venv`
(`sudo apt install python3-venv`), as [Set up your machine](https://k-kammler.github.io/testuary/guide/machine/)
describes.

Testing a C file needs LangAdapter's extra for C
(`python -m pip install "langadapter[c]"`) and the compiler tools that
[LangAdapter's C guide](https://k-kammler.github.io/langadapter/guide/c/)
lists.

Testuary comes with a local web interface. Start it in the directory you
work in:

```bash
testuary-web
```

It opens the interface in your browser, or in an SSH login prints the
`ssh -L` line for your own computer.
[The web interface](https://k-kammler.github.io/testuary/guide/web/) describes
its pages and, under [Access](https://k-kammler.github.io/testuary/guide/web/#access),
how to start it on a machine you share.

The project you test needs its own test tools: pytest, coverage and Cosmic Ray
for Python, or a JDK and the project's Maven or Gradle build for Java.
[Tested environments](https://k-kammler.github.io/testuary/reference/tested-environments/)
lists the tested versions. For Java,
LangAdapter downloads the JUnit launcher, JaCoCo and PIT into its cache on
first use, unless `LANGADAPTER_JAVA_TOOLS_OFFLINE` is set to 1.

## Example

Create the configuration templates in your project's directory:

```bash
cd /path/to/project
testuary init
```

This writes `models.ini` into your user directory and `hints.json` into the
project's directory, and names each file it writes. Then add your model to that
`models.ini`. The section name is the alias you pass with
`--model`, and `provider =` names the kind of model service, `ollama`,
`openai` or `vllm`:

```ini
[ollama_qwen]
provider = ollama
model = qwen3-coder:30b
api_url = http://localhost:11434/v1
```

Run the quick check in the project's directory.
[The check's report](https://k-kammler.github.io/testuary/guide/terminal/#the-checks-report)
says what it looks at and what it leaves alone:

```bash
testuary check --model ollama_qwen --python-executable /path/to/project-env/bin/python --source-files package/module.py
```

Generate a suite for one target. For a first run, a few lines in the project's
settings file keep it small, as
[getting started](https://k-kammler.github.io/testuary/getting-started/#run-with-small-limits)
shows. Run it in the project's directory too, where the run reads that file:

```bash
testuary generate --model ollama_qwen --python-executable /path/to/project-env/bin/python --source-files package/module.py
```

The results go to `.testuary/results/ollama_qwen` in the project's directory.

At a paid service, model requests can cost money. To see a run of all four phases without
a model, play back the offline demonstration with `testuary --demo --output-dir demo-python`.

The [quickstart directory](https://github.com/k-kammler/testuary/tree/v0.2.1/examples/quickstart)
of the repository, also in the source distribution, holds these first steps
as scripts and commands: the demonstrations, the web interface started from
the console or from Python, and two small projects, one Python file and one
Java class, to run with your own model.

## Documentation

- [Getting started](https://k-kammler.github.io/testuary/getting-started/): install, check your setup, run
  with small limits and read the results.
- [Terminal output](https://k-kammler.github.io/testuary/guide/terminal/): the progress views and the
  check's report.
- [Results and logs](https://k-kammler.github.io/testuary/guide/output/): the run directory, the delivered
  suite, the exit status and how to continue a run.
- [Offline demonstrations](https://k-kammler.github.io/testuary/guide/demonstrations/): recorded runs without
  a model.
- [Web interface](https://k-kammler.github.io/testuary/guide/web/): `testuary-web`, a local browser
  interface for projects, models, settings, runs and results.
- [Configuration](https://k-kammler.github.io/testuary/guide/configuration/): models, settings and hints.
- [Running on a cluster](https://k-kammler.github.io/testuary/guide/cluster/): mutation workers, node-local
  scratch, proxies and resuming batch jobs.
- [Models and prompt profiles](https://k-kammler.github.io/testuary/models-and-prompts/)
- [Extension points](https://k-kammler.github.io/testuary/extending/): every way to
  extend Testuary, with its guide.
- [Make a language ready for Testuary](https://k-kammler.github.io/testuary/extending/languages/)
- [Measurement and recovery](https://k-kammler.github.io/testuary/explanation/measurement-and-recovery/)
- [Result files](https://k-kammler.github.io/testuary/reference/result-files/)
- [Contributing](https://k-kammler.github.io/testuary/contributing/)
- [Changelog](https://github.com/k-kammler/testuary/blob/v0.2.1/CHANGELOG.md)

## License

Testuary is licensed under the
[MIT license](https://github.com/k-kammler/testuary/blob/v0.2.1/LICENSE).
A few files from other projects, in the demonstration data, keep their own
licenses, and so do the installed dependencies.
[Third-party material](https://github.com/k-kammler/testuary/blob/v0.2.1/THIRD_PARTY_NOTICES.md)
lists them.
