Metadata-Version: 2.4
Name: pytest-devant-cloud
Version: 0.7.0
Summary: pytest plugin that streams runs, results, and step trees to Devant's /v1/runs API.
Project-URL: Homepage, https://github.com/devant-net/devq-cloud/tree/main/packages/pytest-devant-cloud
Project-URL: Repository, https://github.com/devant-net/devq-cloud
Author: Devant
License: Devant Enterprise License
        
        Copyright (c) 2026 Devant. All rights reserved.
        
        ================================================================================
        THIS IS A TEMPLATE. Review with legal counsel before publishing to npm.
        ================================================================================
        
        1. DEFINITIONS
        
           "Software" means this npm package and its source code, including all
           modifications and derivative works.
        
           "Service" means the Devant hosted product made available by Devant
           to its customers.
        
           "Subscription" means a current, paid commercial agreement between you and
           Devant authorising use of the Service, OR a free-tier registration
           accepted by Devant.
        
           "You" means the individual or legal entity exercising rights under this
           License.
        
        2. GRANT OF USE
        
           Subject to the terms below and the existence of an active Subscription,
           Devant grants You a non-exclusive, non-transferable, revocable license
           to:
        
           (a) install and run the Software on Your own systems and continuous
               integration infrastructure;
           (b) use the Software solely to connect to and interact with the Service;
           (c) make modifications to the Software for Your own internal use, provided
               such modifications are not distributed.
        
        3. RESTRICTIONS
        
           You may not, except to the extent expressly permitted by applicable law:
        
           (a) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
               Software or any modified version of the Software to any third party;
           (b) use the Software to provide a managed, hosted, or commercial service
               that competes with the Service;
           (c) remove, alter, or obscure any proprietary notices in the Software;
           (d) reverse engineer, decompile, or disassemble the Software, except as
               expressly permitted by applicable law notwithstanding this limitation;
           (e) use the Software in violation of any applicable law or regulation.
        
        4. NO TRANSFER OF OWNERSHIP
        
           The Software is licensed, not sold. Devant retains all right, title,
           and interest in and to the Software, including all intellectual property
           rights.
        
        5. TERMINATION
        
           This License terminates automatically and immediately if Your Subscription
           ends, expires, or is terminated for any reason. Upon termination, You must
           cease all use of the Software and destroy all copies in Your possession.
        
        6. NO WARRANTY
        
           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.
        
        7. LIMITATION OF LIABILITY
        
           IN NO EVENT SHALL DEVQ CLOUD OR ITS CONTRIBUTORS 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. DEVQ CLOUD'S TOTAL LIABILITY FOR
           ALL CLAIMS RELATED TO THE SOFTWARE SHALL NOT EXCEED THE FEES PAID BY YOU
           FOR THE SUBSCRIPTION IN THE TWELVE (12) MONTHS PRECEDING THE CLAIM.
        
        8. GOVERNING LAW
        
           This License is governed by the laws of the jurisdiction in which DevQ
           Cloud is incorporated, without regard to its conflict of law principles.
        
        9. ENTIRE AGREEMENT
        
           This License, together with the Subscription terms, constitutes the
           entire agreement between You and Devant concerning the Software and
           supersedes all prior or contemporaneous agreements, proposals, or
           communications.
        
        For commercial licensing inquiries, contact: licensing@devq.cloud
License-File: LICENSE
Keywords: ci,devant,devq,pytest,reporter,test-reporting
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Requires-Dist: pytest>=7.0
Description-Content-Type: text/markdown

# pytest-devant-cloud

[![PyPI version](https://img.shields.io/pypi/v/pytest-devant-cloud.svg)](https://pypi.org/project/pytest-devant-cloud/)
[![Python versions](https://img.shields.io/pypi/pyversions/pytest-devant-cloud.svg)](https://pypi.org/project/pytest-devant-cloud/)
[![License](https://img.shields.io/pypi/l/pytest-devant-cloud.svg)](https://pypi.org/project/pytest-devant-cloud/)

pytest plugin that streams runs, results, and per-test step trees into
[Devant.net](https://devant.net) while your suite runs.

## Requirements

Python 3.10 or newer, and pytest 7 or newer.

## Quick start

Install the plugin:

```bash
pip install pytest-devant-cloud
```

Point it at your project. Copy the token and project id from your Devant
CI/CD settings:

```bash
export DEVANT_API_URL=https://acme.devant.net
export DEVANT_TOKEN=your-ci-token
export DEVANT_PROJECT_ID=42
```

Run pytest as you normally would:

```bash
pytest
```

Results show up in Devant while the suite is still running. There is nothing
to add to `conftest.py`; the plugin registers itself through pytest's
`pytest11` entry-point group.

## Upgrading from 0.1.x

**Every environment variable was renamed, and all config defaults were removed.**
Upgrade without changing your CI and the plugin disables itself — your suite
still passes, so reporting stops without anything failing.

| 0.1.x | 0.4.0+ |
|---|---|
| `DEVANT_CLOUD_API_URL` (or `DEVQ_API_URL`) | `DEVANT_API_URL` — **required** |
| `DEVANT_CLOUD_TOKEN` (or `DEVQ_TOKEN`) | `DEVANT_TOKEN` — **required** |
| `DEVANT_CLOUD_PROJECT_ID` (or `DEVQ_PROJECT_ID`) | `DEVANT_PROJECT_ID` — **required** |
| `DEVANT_CLOUD_RUN_NAME` / `DEVANT_CLOUD_RUN_ID` | `DEVANT_RUN_NAME` / `DEVANT_RUN_ID` |

0.1.x silently fell back to `http://localhost:32124`, the token
`dev-admin-token`, and project `1`. A misconfigured CI job therefore either
401'd against a real tenant or filed its results under whatever project
happened to be id 1. There are no fallbacks now.

When configuration is missing or unusable, the plugin writes one JSON line to
stderr and does nothing further:

```json
{"level":"error","source":"pytest-devant-cloud","msg":"not configured","missing":["DEVANT_TOKEN"]}
```

After upgrading, grep your CI logs for `"msg":"not configured"`.

## Configuration

Configure with environment variables:

| Variable | Default | Notes |
|---|---|---|
| `DEVANT_API_URL` | **required** | Your tenant's URL |
| `DEVANT_TOKEN` | **required** | CI token from Settings → CI/CD |
| `DEVANT_PROJECT_ID` | **required** | Devant project id |
| `DEVANT_RUN_NAME` | `pytest — <ISO date>` | Display name on the run |
| `DEVANT_RUN_ID` | _(unset)_ | Attach to an externally-created run instead of creating one |
| `DEVANT_COVERAGE` | `./coverage.xml`, then `<rootdir>/coverage.xml` | Cobertura report to submit as the run's coverage |

The same settings work as CLI flags, which win over the environment:

```bash
pytest \
  --devant-api-url=https://acme.devant.net \
  --devant-token=$DEVANT_TOKEN \
  --devant-project-id=42
```

Turn the plugin off for a single run without uninstalling it:

```bash
pytest -p no:devant_cloud
```

## Binding tests to cases

Each test maps to one case in Devant. The plugin chooses the case in this
order:

1. The `@pytest.mark.devant("DEF-AB12")` marker on the test, if present.
2. An existing case whose name matches the test.
3. A new case, created on the spot, with a key like `DEF-XYZ9`.

An auto-created case is tied to the test's name and its place in the suite
tree, so renaming or moving the test starts a fresh case. To keep a test's
history across renames, copy its key from your Devant dashboard and pin it in
source:

```python
@pytest.mark.devant("DEF-XYZ9")
def test_login(): ...
```

## Coverage

Coverage is read from the Cobertura XML `pytest-cov` writes, so you need
`--cov-report=xml` — an HTML-only report produces no XML and the upload
silently no-ops:

```bash
pytest --cov=myapp --cov-report=xml --cov-report=html
```

The plugin picks up `coverage.xml` from the working directory (then rootdir)
by default; point it elsewhere
with `--devant-coverage path/to/coverage.xml` or `DEVANT_COVERAGE`. Line and
branch percentages are sent; Cobertura carries no function metric, and
coverage.py's lines *are* its statements, so those two fields stay null.
A missing or unparseable report is warned-and-skipped, never fatal.

## Suites

The plugin turns each test's location into a nested suite tree, built from the
directories, module, and class around it. The leaf is the test function plus
any parametrize id.

| Test | Suite path | Case name |
|---|---|---|
| `tests/test_x.py::test_foo` | tests / test_x | `test_foo` |
| `tests/api/test_x.py::TestThing::test_y[a-1]` | tests / api / test_x / TestThing | `test_y[a-1]` |

If you re-parent a suite by hand in the dashboard, the plugin leaves your
change alone on later runs.

## CI metadata

On GitHub Actions, GitLab CI, CircleCI, Jenkins, and Azure DevOps (or any
runner that sets `CI=true`), the plugin attaches the commit, branch, and
pull request to each run, so Devant can link a run back to the code that
triggered it.
