pytest-nats 0.0.2.dev1__tar.gz

pytest_nats-0.0.2.dev1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikołaj Nowak
+
+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.

pytest_nats-0.0.2.dev1/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: pytest-nats
+Version: 0.0.2.dev1
+Summary: Pytest helpers for running ad-hoc NATS servers
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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.15
+Classifier: Typing :: Typed
+Project-URL: Repository, https://github.com/m3nowak/pytest-nats
+Project-URL: Issues, https://github.com/m3nowak/pytest-nats/issues
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.12.0
+Requires-Dist: platformdirs>=4.11.5
+Requires-Dist: pytest>=8.4.2
+Description-Content-Type: text/markdown
+
+# pytest-nats
+
+Pytest helpers for starting isolated test NATS servers.
+
+## Installation
+
+```shell
+pip install pytest-nats
+```
+
+pytest-nats does not register a global pytest plugin. Declare each server fixture
+explicitly in `conftest.py`; the variable name becomes the fixture name:
+
+```python
+from pytest_nats import nats_server_fixture
+
+nats_server = nats_server_fixture()
+```
+
+Tests receive a read-only `NatsServer` with the client URL, host, dynamic port,
+resolved NATS version, JetStream state, and live `stdout` and `stderr` snapshots:
+
+```python
+from pytest_nats import NatsServer
+
+
+def test_messaging(nats_server: NatsServer) -> None:
+    assert nats_server.url == f"nats://127.0.0.1:{nats_server.port}"
+    assert not nats_server.jetstream_enabled
+```
+
+The fixture binds its unauthenticated client and internal monitoring listeners
+only to `127.0.0.1`, selects dynamic ports, and waits for both a NATS protocol
+exchange and the health endpoint before yielding. It terminates the server and
+removes generated configuration and data at the end of the selected scope.
+
+## JetStream
+
+Enable JetStream when declaring the fixture. One server supports both memory-
+and file-backed streams; client code remains responsible for creating streams
+and consumers.
+
+```python
+from pytest_nats import nats_server_fixture
+
+jetstream_server = nats_server_fixture(
+    jetstream=True,
+    max_memory_store=512 * 1024 * 1024,
+    max_file_store=2 * 1024 * 1024 * 1024,
+)
+```
+
+The default aggregate limits are 256 MiB of memory and 1 GiB of file storage.
+File data is isolated per server and removed during teardown.
+
+## Fixture Scope
+
+Function scope is the default. Module and session scopes retain server and
+JetStream state for their normal pytest lifetime:
+
+```python
+module_nats = nats_server_fixture(scope="module")
+session_nats = nats_server_fixture(scope="session", jetstream=True)
+```
+
+Supported scopes are `function`, `module`, and `session`.
+
+## NATS executable selection
+
+By default, pytest-nats finds `nats-server` on setup-time `PATH` and validates
+that it reports a NATS 2.x semantic version. Use `Local` to select another
+command name or path. Relative paths containing a directory are resolved from
+pytest's root path.
+
+```python
+from pathlib import Path
+
+from pytest_nats import GitHub, Local, Mise, Provision, nats_server_fixture
+
+default_local_nats = nats_server_fixture()
+alternate_local_nats = nats_server_fixture(Local("nats-server-another"))
+local_path_nats = nats_server_fixture(Local(Path("tools/nats-server")))
+latest_nats = nats_server_fixture(Provision())
+mise_nats = nats_server_fixture(Mise("2.12"))
+github_nats = nats_server_fixture(GitHub("2.12.15", cache_dir=Path(".cache/nats")))
+```
+
+`Local`, `Provision`, `Mise`, and `GitHub` are immutable source values. Raw
+strings and paths are not accepted as the fixture's `binary` argument.
+`Provision` prefers Mise when it is available on setup-time `PATH` and uses
+GitHub otherwise. Automatic provisioning accepts `latest`, major, major-minor,
+and exact stable NATS 2.x selectors that can select releases starting at 2.2.0.
+`startup_timeout` sets the positive setup deadline in seconds and defaults to
+10 seconds.
+
+### mise
+
+[mise](https://mise.jdx.dev/) is a development-tool version manager. `Mise`
+asks the `mise` executable on `PATH` to install and locate the selector through its
+[GitHub backend](https://mise.jdx.dev/dev-tools/backends/github.html). The
+selector is passed directly to Mise. Successful acquisition is reused for the
+rest of the pytest process, while failures remain retryable.
+
+### GitHub
+
+`GitHub` downloads official
+[NATS Server releases](https://github.com/nats-io/nats-server/releases),
+verifies their published checksums, and atomically stores executables in the
+selected cache directory. Existing regular executable cache entries are trusted
+without running or rehashing them. Set the optional `GITHUB_TOKEN` environment variable
+to authenticate GitHub API and download requests, which can avoid anonymous API
+rate limits. See GitHub's
+[personal access token documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+for token creation and handling guidance.
+
+Executable lookup, version resolution, and provisioning failures raise
+`NatsExecutableError`. Its `category` is an `ExecutableErrorCategory` value.
+Server startup and lifecycle failures raise `NatsServerError`; its `returncode`,
+`stdout`, and `stderr` attributes retain available diagnostics.
+
+## Development
+
+Install [mise](https://mise.jdx.dev/getting-started.html), then install the project
+tools and dependencies:
+
+```shell
+mise run install
+mise run setup
+```
+
+Run tests and checks:
+
+```shell
+mise run test
+mise run check
+```
+
+Apply automatic lint and formatting fixes:
+
+```shell
+mise run fix
+```
+
+## Releasing
+
+Releases run from `.github/workflows/release.yml`. The workflow accepts a stable,
+canonical PEP 440 version, runs the complete CI workflow, builds and validates
+the source distribution and wheel, publishes them to PyPI, then publishes the
+draft GitHub Release. Run it from the `main` branch in the GitHub Actions UI.
+The first intended version is `0.0.1`, which creates tag `v0.0.1`.
+
+Before the first release, create a pending Trusted Publisher on PyPI with these
+values:
+
+- PyPI project: `pytest-nats`
+- GitHub owner: `m3nowak`
+- GitHub repository: `pytest-nats`
+- Workflow filename: `release.yml`
+- Environment: `pypi`
+
+Create the `pypi` environment in the GitHub repository without required
+reviewers. The workflow requests an OIDC token only in the PyPI publication job;
+no PyPI API token is needed.

pytest_nats-0.0.2.dev1/README.md

@@ -0,0 +1,163 @@
+# pytest-nats
+
+Pytest helpers for starting isolated test NATS servers.
+
+## Installation
+
+```shell
+pip install pytest-nats
+```
+
+pytest-nats does not register a global pytest plugin. Declare each server fixture
+explicitly in `conftest.py`; the variable name becomes the fixture name:
+
+```python
+from pytest_nats import nats_server_fixture
+
+nats_server = nats_server_fixture()
+```
+
+Tests receive a read-only `NatsServer` with the client URL, host, dynamic port,
+resolved NATS version, JetStream state, and live `stdout` and `stderr` snapshots:
+
+```python
+from pytest_nats import NatsServer
+
+
+def test_messaging(nats_server: NatsServer) -> None:
+    assert nats_server.url == f"nats://127.0.0.1:{nats_server.port}"
+    assert not nats_server.jetstream_enabled
+```
+
+The fixture binds its unauthenticated client and internal monitoring listeners
+only to `127.0.0.1`, selects dynamic ports, and waits for both a NATS protocol
+exchange and the health endpoint before yielding. It terminates the server and
+removes generated configuration and data at the end of the selected scope.
+
+## JetStream
+
+Enable JetStream when declaring the fixture. One server supports both memory-
+and file-backed streams; client code remains responsible for creating streams
+and consumers.
+
+```python
+from pytest_nats import nats_server_fixture
+
+jetstream_server = nats_server_fixture(
+    jetstream=True,
+    max_memory_store=512 * 1024 * 1024,
+    max_file_store=2 * 1024 * 1024 * 1024,
+)
+```
+
+The default aggregate limits are 256 MiB of memory and 1 GiB of file storage.
+File data is isolated per server and removed during teardown.
+
+## Fixture Scope
+
+Function scope is the default. Module and session scopes retain server and
+JetStream state for their normal pytest lifetime:
+
+```python
+module_nats = nats_server_fixture(scope="module")
+session_nats = nats_server_fixture(scope="session", jetstream=True)
+```
+
+Supported scopes are `function`, `module`, and `session`.
+
+## NATS executable selection
+
+By default, pytest-nats finds `nats-server` on setup-time `PATH` and validates
+that it reports a NATS 2.x semantic version. Use `Local` to select another
+command name or path. Relative paths containing a directory are resolved from
+pytest's root path.
+
+```python
+from pathlib import Path
+
+from pytest_nats import GitHub, Local, Mise, Provision, nats_server_fixture
+
+default_local_nats = nats_server_fixture()
+alternate_local_nats = nats_server_fixture(Local("nats-server-another"))
+local_path_nats = nats_server_fixture(Local(Path("tools/nats-server")))
+latest_nats = nats_server_fixture(Provision())
+mise_nats = nats_server_fixture(Mise("2.12"))
+github_nats = nats_server_fixture(GitHub("2.12.15", cache_dir=Path(".cache/nats")))
+```
+
+`Local`, `Provision`, `Mise`, and `GitHub` are immutable source values. Raw
+strings and paths are not accepted as the fixture's `binary` argument.
+`Provision` prefers Mise when it is available on setup-time `PATH` and uses
+GitHub otherwise. Automatic provisioning accepts `latest`, major, major-minor,
+and exact stable NATS 2.x selectors that can select releases starting at 2.2.0.
+`startup_timeout` sets the positive setup deadline in seconds and defaults to
+10 seconds.
+
+### mise
+
+[mise](https://mise.jdx.dev/) is a development-tool version manager. `Mise`
+asks the `mise` executable on `PATH` to install and locate the selector through its
+[GitHub backend](https://mise.jdx.dev/dev-tools/backends/github.html). The
+selector is passed directly to Mise. Successful acquisition is reused for the
+rest of the pytest process, while failures remain retryable.
+
+### GitHub
+
+`GitHub` downloads official
+[NATS Server releases](https://github.com/nats-io/nats-server/releases),
+verifies their published checksums, and atomically stores executables in the
+selected cache directory. Existing regular executable cache entries are trusted
+without running or rehashing them. Set the optional `GITHUB_TOKEN` environment variable
+to authenticate GitHub API and download requests, which can avoid anonymous API
+rate limits. See GitHub's
+[personal access token documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+for token creation and handling guidance.
+
+Executable lookup, version resolution, and provisioning failures raise
+`NatsExecutableError`. Its `category` is an `ExecutableErrorCategory` value.
+Server startup and lifecycle failures raise `NatsServerError`; its `returncode`,
+`stdout`, and `stderr` attributes retain available diagnostics.
+
+## Development
+
+Install [mise](https://mise.jdx.dev/getting-started.html), then install the project
+tools and dependencies:
+
+```shell
+mise run install
+mise run setup
+```
+
+Run tests and checks:
+
+```shell
+mise run test
+mise run check
+```
+
+Apply automatic lint and formatting fixes:
+
+```shell
+mise run fix
+```
+
+## Releasing
+
+Releases run from `.github/workflows/release.yml`. The workflow accepts a stable,
+canonical PEP 440 version, runs the complete CI workflow, builds and validates
+the source distribution and wheel, publishes them to PyPI, then publishes the
+draft GitHub Release. Run it from the `main` branch in the GitHub Actions UI.
+The first intended version is `0.0.1`, which creates tag `v0.0.1`.
+
+Before the first release, create a pending Trusted Publisher on PyPI with these
+values:
+
+- PyPI project: `pytest-nats`
+- GitHub owner: `m3nowak`
+- GitHub repository: `pytest-nats`
+- Workflow filename: `release.yml`
+- Environment: `pypi`
+
+Create the `pypi` environment in the GitHub repository without required
+reviewers. The workflow requests an OIDC token only in the PyPI publication job;
+no PyPI API token is needed.

pytest_nats-0.0.2.dev1/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "pytest-nats"
+dynamic = []
+description = "Pytest helpers for running ad-hoc NATS servers"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = [
+    "LICENSE",
+]
+classifiers = [
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx2>=2.12.0",
+    "platformdirs>=4.11.5",
+    "pytest>=8.4.2",
+]
+version = "0.0.2.dev1"
+
+[project.urls]
+Repository = "https://github.com/m3nowak/pytest-nats"
+Issues = "https://github.com/m3nowak/pytest-nats/issues"
+
+[build-system]
+requires = [
+    "pdm-backend>=2.4.0,<3",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm.version]
+source = "scm"
+tag_filter = "v*"
+fallback_version = "0.0.0"
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "-m",
+    "not integration",
+]
+markers = [
+    "integration: uses real NATS providers and requires PYTEST_NATS_RUN_INTEGRATION=1",
+]
+testpaths = [
+    "tests",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+extend-select = [
+    "ANN001",
+    "ANN002",
+    "ANN003",
+    "ANN201",
+    "ANN202",
+    "ANN204",
+    "ANN205",
+    "ANN206",
+]
+
+[dependency-groups]
+dev = [
+    "nats-py>=2.11.0",
+    "pyright>=1.1.405",
+    "pytest-httpx2>=1.0.0",
+    "ruff>=0.12.12",
+]

pytest_nats-0.0.2.dev1/src/pytest_nats/__init__.py

@@ -0,0 +1,16 @@
+"""Pytest helpers for running test NATS servers."""
+
+from ._provisioning import ExecutableErrorCategory, GitHub, Local, Mise, NatsExecutableError, Provision
+from ._runtime import NatsServer, NatsServerError, nats_server_fixture
+
+__all__ = [
+    "ExecutableErrorCategory",
+    "GitHub",
+    "Local",
+    "Mise",
+    "NatsExecutableError",
+    "NatsServer",
+    "NatsServerError",
+    "Provision",
+    "nats_server_fixture",
+]