Metadata-Version: 2.4
Name: karva
Version: 0.0.1a2
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
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: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Rust
License-File: LICENSE
Summary: A Python test framework, written in Rust.
Home-Page: https://github.com/karva-dev/karva
Author-email: Matthew McKee <matthewmckee4@yahoo.co.uk>
Requires-Python: >=3.10, <3.15
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://karva-dev.github.io/karva/
Project-URL: Homepage, https://karva-dev.github.io/karva/
Project-URL: Issues, https://github.com/karva-dev/karva/issues
Project-URL: Repository, https://github.com/karva-dev/karva

# Karva (0.0.1-alpha.2)

![PyPI - Version](https://img.shields.io/pypi/v/karva)

A Python test framework, written in Rust.

<div align="center">
  <img src="https://raw.githubusercontent.com/karva-dev/karva/main/docs/assets/benchmark_results.svg" alt="Benchmark results" width="70%">
</div>

## About Karva

Karva aims to be an efficient alternative to `pytest` and `unittest`.

While we do not yet support all of pytest's features, we aim to gradually add support for pytest alternatives as we add features.

## Getting started

### Installation

Karva is available as [`karva`](https://pypi.org/project/karva/) on PyPI.

Use karva directly with `uvx`:

```bash
uvx karva test
uvx karva version
```

Or install karva with `uv`, or `pip`:

```bash
# With uv.
uv tool install karva@latest

# Add karva to your project.
uv add --dev karva

# With pip.
pip install karva
```

### Usage

By default, Karva will respect your `.gitignore` files when discovering tests in specified directories.

To run your tests, try any of the following:

```bash
# Run all tests.
karva test

# Run tests in a specific directory.
karva test tests/

# Run tests in a specific file.
karva test tests/test_example.py
```

#### Example

Here is a small example usage

```py title="tests/test.py"
def test_pass():
    assert True


def test_fail():
    assert False, "This test should fail"


def test_error():
    raise ValueError("This is an error")
```

Running karva:

```bash
uv run karva test tests/
```

Provides the following output:

```text
test tests.test::test_pass ... ok
test tests.test::test_fail ... FAILED
test tests.test::test_error ... FAILED

diagnostics:

error[test-failure]: Test `test_fail` failed
 --> tests/test.py:5:5
  |
5 | def test_fail():
  |     ^^^^^^^^^
6 |     assert False, "This test should fail"
  |
info: Test failed here
 --> tests/test.py:6:5
  |
5 | def test_fail():
6 |     assert False, "This test should fail"
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
info: Error message: This test should fail

error[test-failure]: Test `test_error` failed
  --> tests/test.py:9:5
   |
 9 | def test_error():
   |     ^^^^^^^^^^
10 |     raise ValueError("This is an error")
   |
info: Test failed here
  --> tests/test.py:10:5
   |
 9 | def test_error():
10 |     raise ValueError("This is an error")
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
info: Error message: This is an error

test result: FAILED. 1 passed; 2 failed; 0 skipped; finished in 8ms
```

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](https://github.com/karva-dev/karva/blob/main/CONTRIBUTING.md) for more information.

You can also join us on [Discord](https://discord.gg/XG95vNz4Zu)

