Metadata-Version: 2.4
Name: docus
Version: 0.1.1
Summary: Pytest client for the Docus test recorder service
Project-URL: Homepage, https://github.com/dooblai/pydocusclient
Project-URL: Source, https://github.com/dooblai/pydocusclient
Project-URL: Issues, https://github.com/dooblai/pydocusclient/issues
Classifier: Framework :: Pytest
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pytest>=7

# docus

An installable pytest plugin that sends test sessions and results to a Docus
test recorder service. It uses the pytest11 entry point, so existing test
files do not need to change.

## Install and run

```sh
pip install docus
TEST_RECORDER_URL=https://recorder.example.com pytest
```

The plugin stays inactive until `TEST_RECORDER_URL` or `--recorder-url` is
provided. Set `TEST_RECORDER_API_TOKEN` when the service requires a bearer
token. Set `TEST_RECORDER_REPO` to the canonical Git repository identifier;
otherwise the plugin uses `GITHUB_REPOSITORY` or Git origin. The optional
`TEST_RECORDER_ACTOR` overrides the current user.

The plugin records collected tests, test results, pytest phase durations,
captured output, Git commit and branch, and a session ID. It sends a batch
at session end. If delivery fails, pytest results are unchanged and the batch
is saved under `.test-recorder/spool`. Retry with:

```sh
TEST_RECORDER_URL=https://recorder.example.com pydocus-resend
```

To keep a test identity across a pytest function rename, mark it with
`@pytest.mark.record_id("logical-name")`. Parameter IDs should remain stable.
Output and failure fields are capped at 64 KiB each; the batch indicates when
truncation occurred.

The Docus service is developed at
[dooblai/docus](https://github.com/dooblai/docus). This package only depends
on pytest and the Python standard library. Other languages can send the same
JSON event format directly to the service.

## Build and release to PyPI

1. Install the package and run `python testing_suite_client.py`.
2. Run `python -m pip install build twine`, `python -m build`, and
   `python -m twine check dist/*` from this repository.
3. Create a GitHub environment named `pypi` in `dooblai/pydocusclient`.
4. In PyPI, configure a **pending trusted publisher** for project name
   `docus`: owner `dooblai`, repository `pydocusclient`,
   workflow filename `release.yml`, environment `pypi`. This must match
   `.github/workflows/release.yml` exactly.
5. Push a version tag such as `v0.1.1`, then publish a GitHub Release for
   that tag. The release workflow builds a wheel and source distribution and
   publishes them using GitHub OIDC. No long lived PyPI API token is needed.
6. Verify with `pip install docus` in a fresh environment.

PyPI does not reserve a name when a pending publisher is configured. Check
that `docus` is available immediately before the first release.
For later releases, update the version in `pyproject.toml` and use a new
matching GitHub tag. Choose and add a license before public distribution if
you intend to grant reuse rights.

See the [PyPI trusted publishing guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
and [Python packaging guide](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
for the current publishing steps.
