pytest-nijam 0.1.0__tar.gz

pytest_nijam-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: lint + types + build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # mypy/ruff run on a modern Python; the package itself targets 3.8+ (ruff's
+      # target-version in pyproject enforces 3.8-compatible syntax).
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - name: Install (with dev extras)
+        run: pip install -e '.[dev]'
+
+      - name: Ruff
+        run: ruff check src
+
+      - name: Mypy
+        run: mypy
+
+      # Catch packaging errors (entry point, metadata) on every PR.
+      - name: Build sanity check
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*

pytest_nijam-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,113 @@
+name: Publish
+
+# One-click release for pytest-nijam:
+#   set version (in pyproject + __init__) → verify → guard → build → publish to PyPI
+#   via Trusted Publishing (OIDC, no token) → commit + tag (vX.Y.Z) → push.
+# Run it from the Actions tab: "Publish" → "Run workflow", enter the new version.
+#
+# No secret needed. Set up Trusted Publishing once on PyPI BEFORE the first run:
+#   PyPI → (project, or "Your projects → Publishing" for a *pending* publisher) →
+#   Add a publisher: owner = getnijam, repo = pytest-reporter,
+#   workflow = publish.yml, environment = pypi.
+# A pending publisher lets the first run create the project. Also create a GitHub
+# environment named "pypi" (Settings → Environments) — optionally gated by reviewers.
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'New version (PEP 440 — e.g. 0.1.0a2, 0.1.0, 1.0.0)'
+        type: string
+        required: true
+
+permissions:
+  contents: write # push the version-bump commit + tag
+  id-token: write # PyPI Trusted Publishing (OIDC)
+
+# Never let two publishes overlap.
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Must match the environment named in the PyPI trusted-publisher config.
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history so the bump commit + tag push cleanly
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      # Validate BEFORE bumping/publishing anything.
+      - name: Validate (lint + types)
+        run: |
+          pip install -e '.[dev]'
+          ruff check src
+          mypy
+
+      # Write the requested version into pyproject.toml + __init__ (kept in sync).
+      - name: Set version
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          python - <<'PY'
+          import os, re, pathlib
+          v = os.environ["VERSION"].strip()
+          if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+([abrc][0-9]+|rc[0-9]+|\.dev[0-9]+|\.post[0-9]+)?", v):
+              raise SystemExit(f"::error::'{v}' is not a PEP 440 version")
+          targets = [
+              ("pyproject.toml", r'(?m)^version = ".*"$', f'version = "{v}"'),
+              ("src/nijam_pytest/__init__.py", r'(?m)^__version__ = ".*"$', f'__version__ = "{v}"'),
+          ]
+          for path, pat, repl in targets:
+              p = pathlib.Path(path)
+              s = p.read_text()
+              s2, n = re.subn(pat, repl, s, count=1)
+              if n != 1:
+                  raise SystemExit(f"::error::could not set version in {path}")
+              p.write_text(s2)
+          print(f"version set to {v}")
+          PY
+
+      # Guard: this version must not already be published (PyPI rejects re-uploads).
+      - name: Guard — version not already on PyPI
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          code=$(curl -s -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/pytest-nijam/$VERSION/json")
+          if [ "$code" = "200" ]; then
+            echo "::error::pytest-nijam $VERSION is already on PyPI — bump again."
+            exit 1
+          fi
+          echo "OK — $VERSION is not on PyPI yet (HTTP $code)."
+
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*
+
+      # Trusted Publishing: no password — authenticates via OIDC (id-token: write)
+      # against the PyPI publisher you configured for this repo + environment.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      # Record the release in git only AFTER PyPI accepted it (publish is the one
+      # irreversible step). Pushes to the branch the workflow was dispatched from.
+      - name: Commit + tag the release
+        env:
+          VERSION: ${{ inputs.version }}
+          BRANCH: ${{ github.ref_name }}
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+          git commit -am "release: v$VERSION"
+          git tag "v$VERSION"
+          git push origin "HEAD:$BRANCH"
+          git push origin "v$VERSION"

pytest_nijam-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.venv/
+venv/
+*.log
+.DS_Store

pytest_nijam-0.1.0/CLAUDE.md

@@ -0,0 +1,82 @@
+# pytest-nijam — Claude instructions
+
+pytest plugin for **Nijam**. Implements pytest's hooks to capture a test run and ship it
+to the Nijam API. It is the Python sibling of `@nijam/pw-reporter` and reports into the
+**same** ingestion endpoints (`/v1/runs`, `…/executions`, `…/source`, `PATCH /v1/runs/:id`).
+
+**This is a public-facing artifact** — installed via `pip`, read on GitHub, pasted into
+users' `pytest.ini`. Code quality, **zero runtime dependencies**, and a copy-paste-runnable
+README matter more here than anywhere else.
+
+License: **MIT** (separate from the BSL platform — must be maximally adoptable).
+
+> This is an independent repo (`getnijam/pytest-reporter`), not part of a monorepo. It
+> shares nothing with the other repos except the API's wire format.
+
+## The one big difference from pw-reporter
+**pytest has no traces.** There is no artifact upload path at all (no trace / screenshot /
+video). We capture the error log (`longrepr`), the failing line, durations, run stats, and
+(opt-in) the test file source — everything the dashboard needs minus the trace viewer.
+Projects created as `pytest` in the dashboard hide trace UI accordingly.
+
+## Stack (locked — ask before changing the public option shape)
+- Python, `>=3.8`. `from __future__ import annotations` everywhere (3.8-safe typing).
+- **Zero runtime dependencies.** `pytest>=7` is the host. HTTP is **stdlib `urllib`** only
+  (no `requests`/`httpx`).
+- Build: **hatchling**, src-layout. Auto-loads via the `pytest11` entry point in `pyproject.toml`.
+- Tooling: `mypy --strict` and `ruff` must stay clean. No automated test suite in v0.1
+  (smoke-test by `pip install -e .` into a sample suite).
+
+## Layout
+```
+src/nijam_pytest/
+  plugin.py   # pytest hooks (addoption/configure/sessionstart/logreport/sessionfinish)
+  client.py   # NijamClient — HTTP to the API (urllib, soft-fail)
+  ci.py       # detect_run_context / relative_file — CI/git metadata (port of pw-reporter ci.ts)
+  buffer.py   # ExecutionBuffer — collect during run, flush in chunks at session finish
+  models.py   # payload dataclasses (RunContext, TestExecution, FinalizeRunPayload, …)
+  log.py      # [nijam]-prefixed warn/info
+```
+
+## Public config surface (design backward from this)
+ini options in `pytest.ini` / `[tool.pytest.ini_options]`, each overridable by env (env wins):
+`nijam_api_key` (`NIJAM_API_KEY`), `nijam_project_id` (`NIJAM_PROJECT_ID`),
+`nijam_api_url` (`NIJAM_API_URL`), `nijam_environment` (`NIJAM_ENVIRONMENT`),
+`nijam_upload_source` (bool, default true), `nijam_auto_complete` (bool, default true,
+`NIJAM_AUTO_COMPLETE`), `nijam_silent` (bool). Missing key/project → warn with the docs
+link + disable; no further work. Don't change these names/shape without asking.
+
+## Lifecycle & behavior
+- `pytest_configure` → register one `NijamPlugin`.
+- `pytest_sessionstart` → `detect_run_context` + `POST /v1/runs`, store `run_id`; on
+  failure log + disable for this run.
+- `pytest_runtest_logreport` → accumulate per-attempt state keyed by nodeid (setup → call
+  → teardown), emit **one execution per attempt** on the teardown report. Never block on I/O.
+- `pytest_sessionfinish` → drain the buffer, optionally upload sources, then
+  `PATCH /v1/runs/:id` to finalize with status + stats (unless `auto_complete` is off).
+- **Field mapping**: `testId`=nodeid, `title`=last `::` segment, `titlePath`=`::`-split minus
+  the file, `file`=git-root-relative (else rootdir-relative) of `report.location[0]`,
+  `line`=`report.location[1] + 1` (pytest is 0-based, the API is 1-based), `errorMessage`=
+  `longreprtext`, `durationMs`=summed phase durations, `id`=client `uuid4`.
+- **Status**: failed > skipped > passed precedence across phases. `xfail` lands as skipped.
+  `pytest-rerunfailures` reruns (outcome `rerun`) emit extra attempts with bumped `retry`,
+  which is how flaky is derived (a test that passed only after a retry). No reruns ⇒ no flaky.
+- **CI detection** (`ci.py`): per-field `CI var → generic GIT_* → git shell-out → empty`.
+  GitHub/GitLab/CircleCI/Bitbucket/generic. Leave `branch` None when unknown (dashboard
+  renders "No Branch Info"). Same env-var names as pw-reporter's `ci.ts`.
+- **HTTP**: Bearer `api_key`, 30s timeout, no retries, 402 → "plan limit reached" warning.
+
+## Guard rails — do NOT
+- ❌ **Raise from any hook** — wrap every hook body in try/except, `log.warn`, continue.
+  The plugin MUST NOT break a user's test run. Ever.
+- ❌ Add runtime dependencies (zero-dep goal) · use `requests`/`httpx` (stdlib `urllib` only).
+- ❌ Block the test path (`logreport`) on the network — only append to the buffer; flush at finish.
+- ❌ Add a trace/artifact upload path — pytest has no traces.
+- ❌ Use Python-3.10-only syntax in runtime code without `from __future__ import annotations`.
+- ❌ Change the public option names/shape, or the API wire format, without asking.
+- ❌ Ternary hell / one-liners that hurt readability — prefer early returns and `if`/`else`.
+
+## Build & publish
+- `pip install -e '.[dev]'` · `mypy` · `ruff check src` · smoke-test into a sample suite.
+- Versions: `0.1.0aN` until platform launch, then `0.1.0`; semver after. Bump the alpha on
+  each meaningful change. Publish: `python -m build && twine upload dist/*`.

pytest_nijam-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nijam
+
+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_nijam-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: pytest-nijam
+Version: 0.1.0
+Summary: pytest plugin for Nijam — captures test runs and ships them to the Nijam API.
+Project-URL: Homepage, https://nijam.dev
+Project-URL: Documentation, https://docs.nijam.dev
+Project-URL: Source, https://github.com/getnijam/pytest-reporter
+Author: Nijam
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ci,nijam,pytest,reporting,test-analytics
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Requires-Dist: pytest>=7.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytest-nijam
+
+pytest plugin for [Nijam](https://nijam.dev) — captures your test runs and ships them
+to the Nijam dashboard so you can track what failed, why, and where (error log +
+failing line), across CI runs and over time.
+
+> pytest has no traces, so — unlike the Playwright reporter — runs won't include a
+> trace viewer. Everything else (failures, error output, the failing line, durations,
+> and your test source) is captured.
+
+## Install
+
+```bash
+pip install pytest-nijam
+```
+
+The plugin auto-activates once installed (via pytest's `pytest11` entry point).
+
+## Configure
+
+Add your project ID to `pytest.ini` (or `pyproject.toml`), and provide the ingest API
+key via an environment variable (it's a secret — keep it out of source control):
+
+```ini
+# pytest.ini
+[pytest]
+nijam_project_id = 00000000-0000-0000-0000-000000000000
+```
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+nijam_project_id = "00000000-0000-0000-0000-000000000000"
+```
+
+```bash
+export NIJAM_API_KEY="nij_sk_…"   # from the Nijam dashboard → Secret keys
+pytest
+```
+
+Both the project ID and the API key can come from either the ini file or an
+environment variable; **the environment variable wins** when both are set.
+
+## Options
+
+| ini option            | env var               | default                  | what it does                                                        |
+| --------------------- | --------------------- | ------------------------ | ------------------------------------------------------------------- |
+| `nijam_api_key`       | `NIJAM_API_KEY`       | —                        | Ingest API key (required).                                          |
+| `nijam_project_id`    | `NIJAM_PROJECT_ID`    | —                        | Project UUID (required).                                            |
+| `nijam_api_url`       | `NIJAM_API_URL`       | `https://api.nijam.dev`  | API base URL.                                                       |
+| `nijam_environment`   | `NIJAM_ENVIRONMENT`   | —                        | Free-form environment tag (e.g. `staging`).                         |
+| `nijam_upload_source` | —                     | `true`                   | Upload each test file's source so the dashboard can show it.        |
+| `nijam_auto_complete` | `NIJAM_AUTO_COMPLETE` | `true`                   | Finalize the run when this process ends. Set `false` for fan-out.   |
+| `nijam_silent`        | —                     | `false`                  | Suppress `[nijam]` log lines.                                       |
+
+If `nijam_api_key` or `nijam_project_id` is missing, the plugin disables itself with a
+single warning — your tests run exactly as before.
+
+## CI metadata
+
+Run context (commit, branch, PR number, CI provider/run URL, commit author) is detected
+automatically from GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, or generic
+`GIT_*` env vars, falling back to `git` itself. No configuration needed.
+
+## Fan-out across CI jobs
+
+If you split your suite across several CI jobs (e.g. one job per test path) that all feed
+one Nijam run, set `nijam_auto_complete = false` (or `NIJAM_AUTO_COMPLETE=false`) on each
+job so none of them finalizes early, then complete the run once from a post-matrix step.
+See the [docs](https://docs.nijam.dev/reporter/pytest/).
+
+## Guarantees
+
+This plugin **never breaks your test run.** Every hook is fail-soft: a network error, a
+bad key, or an unreachable API produces a `[nijam]` warning and nothing more — your tests
+still pass or fail on their own merits.
+
+## License
+
+MIT

pytest_nijam-0.1.0/README.md

@@ -0,0 +1,80 @@
+# pytest-nijam
+
+pytest plugin for [Nijam](https://nijam.dev) — captures your test runs and ships them
+to the Nijam dashboard so you can track what failed, why, and where (error log +
+failing line), across CI runs and over time.
+
+> pytest has no traces, so — unlike the Playwright reporter — runs won't include a
+> trace viewer. Everything else (failures, error output, the failing line, durations,
+> and your test source) is captured.
+
+## Install
+
+```bash
+pip install pytest-nijam
+```
+
+The plugin auto-activates once installed (via pytest's `pytest11` entry point).
+
+## Configure
+
+Add your project ID to `pytest.ini` (or `pyproject.toml`), and provide the ingest API
+key via an environment variable (it's a secret — keep it out of source control):
+
+```ini
+# pytest.ini
+[pytest]
+nijam_project_id = 00000000-0000-0000-0000-000000000000
+```
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+nijam_project_id = "00000000-0000-0000-0000-000000000000"
+```
+
+```bash
+export NIJAM_API_KEY="nij_sk_…"   # from the Nijam dashboard → Secret keys
+pytest
+```
+
+Both the project ID and the API key can come from either the ini file or an
+environment variable; **the environment variable wins** when both are set.
+
+## Options
+
+| ini option            | env var               | default                  | what it does                                                        |
+| --------------------- | --------------------- | ------------------------ | ------------------------------------------------------------------- |
+| `nijam_api_key`       | `NIJAM_API_KEY`       | —                        | Ingest API key (required).                                          |
+| `nijam_project_id`    | `NIJAM_PROJECT_ID`    | —                        | Project UUID (required).                                            |
+| `nijam_api_url`       | `NIJAM_API_URL`       | `https://api.nijam.dev`  | API base URL.                                                       |
+| `nijam_environment`   | `NIJAM_ENVIRONMENT`   | —                        | Free-form environment tag (e.g. `staging`).                         |
+| `nijam_upload_source` | —                     | `true`                   | Upload each test file's source so the dashboard can show it.        |
+| `nijam_auto_complete` | `NIJAM_AUTO_COMPLETE` | `true`                   | Finalize the run when this process ends. Set `false` for fan-out.   |
+| `nijam_silent`        | —                     | `false`                  | Suppress `[nijam]` log lines.                                       |
+
+If `nijam_api_key` or `nijam_project_id` is missing, the plugin disables itself with a
+single warning — your tests run exactly as before.
+
+## CI metadata
+
+Run context (commit, branch, PR number, CI provider/run URL, commit author) is detected
+automatically from GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, or generic
+`GIT_*` env vars, falling back to `git` itself. No configuration needed.
+
+## Fan-out across CI jobs
+
+If you split your suite across several CI jobs (e.g. one job per test path) that all feed
+one Nijam run, set `nijam_auto_complete = false` (or `NIJAM_AUTO_COMPLETE=false`) on each
+job so none of them finalizes early, then complete the run once from a post-matrix step.
+See the [docs](https://docs.nijam.dev/reporter/pytest/).
+
+## Guarantees
+
+This plugin **never breaks your test run.** Every hook is fail-soft: a network error, a
+bad key, or an unreachable API produces a `[nijam]` warning and nothing more — your tests
+still pass or fail on their own merits.
+
+## License
+
+MIT

pytest_nijam-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytest-nijam"
+version = "0.1.0"
+description = "pytest plugin for Nijam — captures test runs and ships them to the Nijam API."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [{ name = "Nijam" }]
+keywords = ["pytest", "nijam", "test-analytics", "reporting", "ci"]
+classifiers = [
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+# Zero runtime dependencies. pytest is the host — declared so resolvers know the
+# minimum, but the plugin only ever loads inside a pytest process anyway.
+dependencies = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://nijam.dev"
+Documentation = "https://docs.nijam.dev"
+Source = "https://github.com/getnijam/pytest-reporter"
+
+# This entry point is what makes pytest auto-discover and load the plugin.
+[project.entry-points.pytest11]
+nijam = "nijam_pytest.plugin"
+
+[project.optional-dependencies]
+dev = ["mypy>=1.8", "ruff>=0.5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nijam_pytest"]
+
+[tool.mypy]
+strict = true
+files = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

pytest_nijam-0.1.0/src/nijam_pytest/__init__.py

@@ -0,0 +1,3 @@
+"""pytest plugin for Nijam — captures test runs and ships them to the Nijam API."""
+
+__version__ = "0.1.0"

pytest_nijam-0.1.0/src/nijam_pytest/buffer.py

@@ -0,0 +1,38 @@
+"""Batches test executions and flushes them in chunks.
+
+Unlike the Playwright reporter (which fire-and-forgets over the network on a worker
+thread), this buffer only *appends* during the test run — it never blocks the test
+path on I/O. The accumulated executions are flushed in `FLUSH_SIZE` chunks at
+`drain()` time (session finish), which keeps the hot path allocation-only and avoids
+threading complexity. pytest sessions are short-lived, so a single end-of-run flush
+is acceptable.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from . import log
+from .models import TestExecution
+
+FLUSH_SIZE = 50
+
+
+class ExecutionBuffer:
+    def __init__(self, flush_fn: Callable[[list[TestExecution]], None]) -> None:
+        self._flush_fn = flush_fn
+        self._items: list[TestExecution] = []
+
+    def add(self, item: TestExecution) -> None:
+        self._items.append(item)
+
+    def drain(self) -> None:
+        """Send everything collected, in FLUSH_SIZE chunks. A failed chunk drops that
+        batch with a warning (the flush fn soft-fails) and we continue with the rest."""
+        items, self._items = self._items, []
+        for start in range(0, len(items), FLUSH_SIZE):
+            batch = items[start : start + FLUSH_SIZE]
+            try:
+                self._flush_fn(batch)
+            except Exception as err:
+                log.warn(f"dropped a batch of {len(batch)} executions: {err}")