Metadata-Version: 2.5
Name: testuary
Version: 0.2.0
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.0
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)](https://pypi.org/project/testuary/)
[![Python versions](https://img.shields.io/pypi/pyversions/testuary)](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 test suites for Python and Java code, and for C code on
Linux, with a language model.
It runs the generated tests, measures their line and branch coverage and how
many deliberately injected faults (mutants) they detect, and asks the model to
close the gaps until the goals or the limits are reached. It then removes the
tests that add no coverage and catch no extra mutant, and delivers the
suite with its measurements.

Language support comes from LangAdapter, a separate package
(`langadapter`).

## Install

Testuary runs on Python 3.10 or newer. It is supported on Windows and Linux. On
macOS it is expected to work, but this release has not run on a Mac: [Tested
environments](https://k-kammler.github.io/testuary/reference/tested-environments/)
says what is known. 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. pip installs LangAdapter with it:

```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`. 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 Linux, 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.0/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.0/CHANGELOG.md)

## License

Testuary is licensed under the
[MIT license](https://github.com/k-kammler/testuary/blob/v0.2.0/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.0/THIRD_PARTY_NOTICES.md)
lists them.
