Metadata-Version: 2.4
Name: aware-test-runner
Version: 0.1.1
Summary: Unified test runner for the Aware platform with OSS-ready packaging.
Project-URL: Homepage, https://pypi.org/project/aware-test-runner/
Project-URL: Documentation, https://github.com/aware-network/aware/blob/main/tools/test-runner/README.md
Project-URL: Changelog, https://github.com/aware-network/aware/blob/main/tools/test-runner/CHANGELOG.md
Project-URL: Source, https://github.com/aware-network/aware
Project-URL: Issues, https://github.com/aware-network/aware/issues
Author: Aware OSS Team
License: MIT License
        
        Copyright (c) 2025 Aware Network
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: automation,aware,ci,manifests,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: pytest>=8.2
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Provides-Extra: internal
Provides-Extra: tests
Requires-Dist: pytest>=8.2; extra == 'tests'
Description-Content-Type: text/markdown

# aware-test-runner

`aware-test-runner` packages the manifest-driven test orchestration we use across the
Aware platform. It exposes a tiny CLI (`aware-tests`) that mirrors our CI layout so
contributors can run the same curated suites locally or inside automation.

The project ships with an **OSS manifest** that exercises the open-source surface.
Internal manifests live alongside the package and can be layered on top when the
monorepo is present.

## Key capabilities

- Declarative manifests (`stable.json`, `runtime.json`) that describe suites,
  marks, and pytest flags.
- CLI helpers to list suites, execute a subset, or hand over execution to pytest.
- Environment variable overrides so CI can provide a different manifest directory
  without modifying the command line.
- Ready-to-extend extras (e.g. `internal`, `flutter`) for optional dependencies.

## Installation

```bash
pip install aware-test-runner
```

Requires Python 3.10+. The package works with both `pip` and `uv`. Extras will land
once the internal split for our larger matrix is stabilised.

## Quick start

Run the OSS stable suites:

```bash
aware-tests --manifest oss --stable
```

Discover available suites:

```bash
aware-tests --list
```

Execute a focused set and forward options to pytest:

```bash
aware-tests --suites kernel -- -k "smoke and not slow" --maxfail=1
```

## Manifest selection

Manifests can be controlled through identifiers, paths, or environment variables.

| Mechanism | Example |
| --- | --- |
| Named manifest | `aware-tests --manifest internal` |
| Manifest file | `aware-tests --manifest-file configs/manifests/internal/stable.json` |
| Directory search path | `AWARE_TEST_RUNNER_MANIFEST_DIRS=/tmp/manifests:$PWD/configs` |
| Explicit identifier (env) | `AWARE_TEST_RUNNER_MANIFEST=runtime` |
| Override file (env) | `AWARE_TEST_RUNNER_MANIFEST_FILE=/tmp/runtime.json` |

Each manifest can inherit from another via an `extends` field, allowing the internal
configuration to re-use the OSS baseline.

## CI usage

Add a job that configures the manifest directory and runs the stable matrix:

```yaml
- name: Run OSS suites
  run: |
    export AWARE_TEST_RUNNER_MANIFEST_DIRS=$GITHUB_WORKSPACE/tools/test-runner/configs/manifests
    aware-tests --manifest oss --stable --no-warnings
```

For larger installations we recommend pinning the manifest alongside the workspace
so agents and humans see the exact same suite definitions.

## Roadmap

- Publish optional extras for internal-only dependencies.
- Ship pre-built manifest bundles targeting different providers (CI, Studio, SDK).
- Expose a Python API for embedding manifests inside other orchestration layers.

## Support

- OSS quickstart: this README.
- Release automation: tracked under
  `docs/projects/aware-developer-tools/tasks/aware-test-runner-tooling/`.
- Legacy compatibility: importing `aware_tests` still works but emits a notice
  pointing to `aware_test_runner`.

Bug reports and suggestions are welcome via issues in `aware-network/aware`.

## License

Distributed under the MIT License. See `LICENSE` for details.
