Metadata-Version: 2.4
Name: vault88
Version: 0.2.0
Summary: Python automated test framework
Author-email: Brad Murdoch <brad.murdoch@me.ca>
License: MIT
Project-URL: Documentation, https://gitlab.glider-eng.com/python-packages/vault88/-/wikis/home
Project-URL: Issues, https://gitlab.glider-eng.com/python-packages/vault88/-/work_items
Project-URL: Source, https://gitlab.glider-eng.com/python-packages/vault88
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: junit-xml==1.9
Requires-Dist: paramiko<4,>=3.0
Requires-Dist: selenium<5,>=4.0

# vault88

**vault88** is a Python automated test framework designed for structured hardware and software validation in CI/CD pipelines. Tests are written as Python classes, organised into stages, and results can be published through configurable reporters.

## Architecture

| Component | Role |
|---|---|
| `Loader` | Discovers test classes from files or directories; supports tag-based include/exclude filtering |
| `Logger` | Centralised logging with rotating file handler and optional verbose (debug) output |
| `Runner` | Instantiates and executes a test class through its full lifecycle: `selfCheck` → `setup` → `run` → `teardown` |
| `Reporter` | Pluggable reporters loaded from the config file; built-in reporters include JUnit XML and log archive |

Test results are grouped into named **stages** within each test, and each result records an action, expected value, actual value, outcome, timestamp, and optional requirement references.

## Installation

```bash
pip install vault88
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add vault88
```

## Writing a test

Subclass `Test` and implement the four lifecycle methods:

```python
from vault88 import Test

class MyTest(Test):
    name = "My Test"
    tags = ["smoke"]

    def selfCheck(self) -> bool:
        # Return False to skip the test entirely
        return True

    def setup(self) -> bool:
        # Prepare resources; return False to abort
        return True

    def run(self) -> None:
        self.newStage("Basic checks")
        self.assertEqual("Verify result", expected=42, actual=compute())

    def teardown(self) -> None:
        pass
```

Available assertion helpers: `assertEqual`, `assertNotEqual`, `assertTrue`, `assertFalse`, `assertGreaterThan`, `assertLessThan`, `assertGreaterThanOrEqual`, `assertLessThanOrEqual`, `assertIn`, `assertNotIn`, `assertIsNone`, `assertIsNotNone`.

## Running tests

```bash
vault88 <testpath> [options]
```

| Option | Description |
|---|---|
| `testpath` | Path to a test file or directory |
| `-t TAG [TAG ...]` | Only run tests that have **at least one** of these tags |
| `-nt TAG [TAG ...]` | Exclude tests that have any of these tags |
| `-r` | Recursively search directories for tests |
| `-l FILE` | Log file path (default: `./test_execution.log`) |
| `-v` | Verbose / debug logging |
| `--env PATH_OR_URL` | Load an environment from a JSON file or HTTP(S) URL |
| `--junit` | Generate a `testresults.xml` JUnit report in the current directory |

## Configuration

Reporters are configured in `/etc/vault88.conf` (INI format). Each `[REPORTER<n>]` section loads one reporter:

```ini
[REPORTER1]
module = vault88.core.reporters.junit_reporter
class = JUnitReporter
enabled = true
suite_name = My Project Tests

[REPORTER2]
module = vault88.core.reporters.log_archive_reporter
class = LogArchiveReporter
enabled = true
output_dir = ./logs
```

## Development

Dependencies are managed with [uv](https://docs.astral.sh/uv/). Install the project with test dependencies:

```bash
uv sync
```

### Running the test suite

```bash
uv run pytest
```

Run with coverage:

```bash
uv run pytest --cov=vault88 --cov-report=term-missing
```

Run tests in parallel:

```bash
uv run pytest -n auto
```

### Linting with ruff

Check for issues:

```bash
uv run ruff check .
```

Auto-fix fixable issues:

```bash
uv run ruff check --fix .
```

Check formatting:

```bash
uv run ruff format --check .
```

Apply formatting:

```bash
uv run ruff format .
```

## License

MIT
