pytest-balance 0.1.0a1__tar.gz

pytest_balance-0.1.0a1/.commitlintrc.yml

@@ -0,0 +1,2 @@
+extends:
+  - "@commitlint/config-conventional"

pytest_balance-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,103 @@
+name: CI
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  commitlint:
+    name: Commit messages
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+      - uses: wagoid/commitlint-github-action@f133a0d95090ef2609192b4a21f54e20af819ea9 # v6
+
+  format:
+    name: Format
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run ruff format --check src tests
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run ruff check src tests
+
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run mypy src
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run pytest --cov --cov-report=xml --tb=short
+        if: matrix.python-version == '3.14'
+      - run: uv run pytest --tb=short
+        if: matrix.python-version != '3.14'
+      - uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5
+        if: matrix.python-version == '3.14'
+        with:
+          files: coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+
+  test-without-xdist:
+    name: Test (without xdist)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --no-group dev
+      - run: uv run pytest --tb=short -k "not test_xdist"

pytest_balance-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,115 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  ci-check:
+    name: CI Gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        with:
+          enable-cache: true
+
+      - name: Verify tag matches package version
+        env:
+          TAG_REF: ${{ github.ref }}
+        run: |
+          TAG="${TAG_REF#refs/tags/v}"
+          PY_VER=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "Tag: $TAG | pyproject: $PY_VER"
+          if [ "$TAG" != "$PY_VER" ]; then
+            echo "::error::Tag v$TAG does not match pyproject.toml version $PY_VER"
+            exit 1
+          fi
+
+      - run: uv sync
+      - run: uv run ruff format --check src tests
+      - run: uv run ruff check src tests
+      - run: uv run mypy src
+      - run: uv run pytest --tb=short
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+      - run: uv build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: [build, ci-check]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment: PyPI
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        with:
+          attestations: true
+
+  release:
+    name: GitHub Release
+    needs: [build, ci-check]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - name: Generate checksums
+        run: |
+          cd dist
+          sha256sum * > SHA256SUMS
+
+      - name: Generate release notes
+        id: cliff
+        uses: orhun/git-cliff-action@c93ef52f3d0ddcdcc9bd5447d98d458a11cd4f72 # v4
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+        env:
+          GITHUB_REPO: ${{ github.repository }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2
+        with:
+          body: ${{ steps.cliff.outputs.content }}
+          prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/SHA256SUMS

pytest_balance-0.1.0a1/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+
+# Tool caches (pytest, mypy, ruff)
+.cache/
+
+# Virtual environments
+.venv/
+
+# Duration store
+.balance/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+
+# Coverage
+.coverage
+
+# Review
+.full-review/
+
+# Ongoing documentation
+docs/

pytest_balance-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoffrey Guéret
+
+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_balance-0.1.0a1/Makefile

@@ -0,0 +1,28 @@
+.PHONY: install lint typecheck test format check all clean
+
+install:
+	uv sync
+
+lint:
+	uv run ruff check src tests
+
+typecheck:
+	uv run mypy src
+
+test:
+	uv run pytest
+
+format:
+	uv run ruff format src tests
+	uv run ruff check --fix src tests
+
+check:
+	uv run ruff format --check src tests
+	uv run ruff check src tests
+	uv run mypy src
+
+all: lint typecheck test
+
+clean:
+	rm -rf .cache .coverage htmlcov dist build *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

pytest_balance-0.1.0a1/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: pytest-balance
+Version: 0.1.0a1
+Summary: Intelligent test distribution for pytest based on actual execution times, not file count
+Project-URL: Homepage, https://github.com/ggueret/pytest-balance
+Project-URL: Repository, https://github.com/ggueret/pytest-balance.git
+Project-URL: Documentation, https://github.com/ggueret/pytest-balance
+Project-URL: Issues, https://github.com/ggueret/pytest-balance/issues
+Project-URL: Changelog, https://github.com/ggueret/pytest-balance/releases
+Author-email: Geoffrey Guéret <geoffrey@gueret.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: CI,distribution,load-balancing,pytest,testing,xdist
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+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.10
+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: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pytest>=8
+Provides-Extra: xdist
+Requires-Dist: pytest-xdist>=3.5; extra == 'xdist'
+Description-Content-Type: text/markdown
+
+# pytest-balance
+
+[![PyPI](https://img.shields.io/pypi/v/pytest-balance)](https://pypi.org/project/pytest-balance/)
+[![Python](https://img.shields.io/pypi/pyversions/pytest-balance)](https://pypi.org/project/pytest-balance/)
+[![License](https://img.shields.io/github/license/ggueret/pytest-balance)](https://github.com/ggueret/pytest-balance/blob/main/LICENSE)
+
+Intelligent test distribution for pytest. Split your test suite across CI runners and
+xdist workers based on actual execution times, not file count.
+
+Most CI parallelism strategies split tests naively: round-robin, alphabetical, or by file
+count. The result is predictable. One runner finishes in 2 minutes, another grinds for
+12, and your pipeline is only as fast as the slowest shard.
+
+**pytest-balance fixes this.** It records test durations, learns from them, and uses a
+scheduling algorithm with real guarantees to spread the load evenly.
+
+### What makes it different
+
+- **LPT scheduling.** The Longest Processing Time First algorithm assigns the heaviest
+  test groups first and greedily fills the lightest bucket. This minimizes your total wall
+  time with a proven worst-case bound of 4/3 optimal.
+- **Deterministic partitioning.** Given the same duration data and the same test
+  collection, every CI run produces the exact same split. No flaky ordering, no
+  cache-busting surprises, no "works on my shard" mysteries. Ties are broken
+  lexicographically, so the output is reproducible down to the test.
+- **Scope-aware grouping.** Tests that share module or class fixtures stay together,
+  avoiding expensive teardown/setup cycles across nodes.
+- **Work-stealing.** When used with pytest-xdist, idle workers steal complete test groups
+  from the busiest worker at runtime. Static estimates are never perfect;
+  work-stealing closes the gap.
+- **Adaptive estimation.** An exponential moving average (EMA) tracks duration trends
+  over time, so a test that got slower last week weighs more than one that was slow six
+  months ago.
+
+## Installation
+
+```bash
+pip install pytest-balance
+
+# With pytest-xdist support
+pip install pytest-balance[xdist]
+```
+
+## Quick Start
+
+**Step 1: record durations** on your first run (or in a baseline pipeline step):
+
+```bash
+pytest --balance-store
+```
+
+This writes `.balance/durations.jsonl` (locally) or `.balance/durations-<run_id>-<node>.jsonl`
+(in CI). After a parallel CI run, merge the partial files:
+
+```bash
+pytest-balance merge
+```
+
+**Step 2: distribute tests** using the recorded data:
+
+```bash
+pytest --balance
+```
+
+In CI, the plugin auto-detects the node index and total from the environment and runs only
+the slice assigned to the current node.
+
+## CI Integration
+
+### GitHub Actions
+
+GitHub Actions does not expose parallel job indices natively. Pass them from the matrix:
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shard: [0, 1, 2, 3]
+    env:
+      PYTEST_BALANCE_NODE_INDEX: ${{ matrix.shard }}
+      PYTEST_BALANCE_NODE_TOTAL: 4
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install pytest-balance
+      - run: pytest --balance --balance-store
+      - uses: actions/upload-artifact@v4
+        with:
+          name: durations-${{ matrix.shard }}
+          path: .balance/durations-*.jsonl
+
+  merge-durations:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+      - run: pip install pytest-balance
+      - run: pytest-balance merge durations-*/durations-*.jsonl -o .balance/durations.jsonl
+      - uses: actions/upload-artifact@v4
+        with:
+          name: balance-store
+          path: .balance/durations.jsonl
+```
+
+### GitLab CI
+
+GitLab's `parallel:` keyword sets `CI_NODE_INDEX` (1-based) and `CI_NODE_TOTAL`
+automatically. The plugin converts the 1-based index to 0-based internally.
+
+```yaml
+test:
+  image: python:3.14
+  parallel: 4
+  script:
+    - pip install pytest-balance
+    - pytest --balance --balance-store
+  artifacts:
+    paths:
+      - .balance/durations-*.jsonl
+    expire_in: 7 days
+
+merge-durations:
+  image: python:3.14
+  stage: .post
+  needs: [test]
+  script:
+    - pip install pytest-balance
+    - pytest-balance merge .balance/durations-*.jsonl -o .balance/durations.jsonl
+  artifacts:
+    paths:
+      - .balance/durations.jsonl
+    expire_in: 30 days
+```
+
+### CircleCI
+
+CircleCI's `parallelism:` sets `CIRCLE_NODE_INDEX` (0-based) and `CIRCLE_NODE_TOTAL`
+automatically.
+
+```yaml
+jobs:
+  test:
+    docker:
+      - image: cimg/python:3.14
+    parallelism: 4
+    steps:
+      - checkout
+      - run: pip install pytest-balance
+      - run: pytest --balance --balance-store
+      - store_artifacts:
+          path: .balance/
+```
+
+### Azure DevOps
+
+Azure Pipelines sets `SYSTEM_JOBPOSITIONINPHASE` (1-based) and `SYSTEM_TOTALJOBSINPHASE`
+when using a matrix or parallel strategy. The plugin converts to 0-based internally.
+
+### Buildkite
+
+Buildkite sets `BUILDKITE_PARALLEL_JOB` (0-based) and `BUILDKITE_PARALLEL_JOB_COUNT`
+when `parallelism:` is configured in the pipeline.
+
+### Generic / other CI
+
+Set `PYTEST_BALANCE_NODE_INDEX` and `PYTEST_BALANCE_NODE_TOTAL` manually on any CI system
+that does not have native parallelism variables.
+
+## xdist Integration
+
+When `pytest-balance[xdist]` is installed, passing `--balance` alongside `-n` activates
+the `BalanceScheduler` instead of the default xdist load scheduler:
+
+```bash
+pytest -n 4 --balance
+```
+
+The scheduler uses LPT pre-assignment (see How It Works) and falls back to work-stealing
+at runtime when workers finish early. `--dist each` is incompatible with `--balance`.
+
+## CLI Options
+
+All options are available as pytest command-line flags:
+
+| Flag | Default | Description |
+|---|---|---|
+| `--balance` | off | Enable balanced test distribution across CI nodes |
+| `--balance-store` | off | Record test durations to the balance store |
+| `--balance-scope` | `module` | Grouping scope: `test`, `class`, `module`, `group` |
+| `--balance-path` | `.balance/` | Path to the balance store directory |
+| `--balance-plan` | off | Show the distribution plan without running tests (requires `--balance`) |
+| `--balance-node-index` | auto | Explicit node index (overrides CI auto-detection) |
+| `--balance-node-total` | auto | Explicit total node count (overrides CI auto-detection) |
+| `--balance-estimator` | `ema` | Duration estimation strategy: `ema`, `median`, `last` |
+| `--balance-no-report` | off | Suppress the balance summary after the test run |
+
+## Standalone CLI
+
+The `pytest-balance` command manages the duration store outside of a test run.
+
+```
+pytest-balance [--path PATH] <command> [options]
+```
+
+### merge
+
+Merge per-node partial files into a single `durations.jsonl`:
+
+```bash
+pytest-balance merge
+pytest-balance merge .balance/durations-abc-0.jsonl .balance/durations-abc-1.jsonl
+pytest-balance merge -o custom/path/durations.jsonl
+```
+
+After merging, the partial files are deleted automatically.
+
+### prune
+
+Remove old run data, keeping only the most recent runs per test:
+
+```bash
+pytest-balance prune
+pytest-balance prune --keep-runs 20
+```
+
+Default is 50 runs. Entries without a `run_id` are always kept.
+
+### stats
+
+Display a summary of the duration store:
+
+```bash
+pytest-balance stats
+pytest-balance stats --json
+```
+
+Output includes total tests, total and average estimated time, and the slowest and fastest
+tests.
+
+### plan
+
+Preview how tests would be distributed for a given node count:
+
+```bash
+pytest-balance plan 4
+pytest-balance plan 4 --scope class --estimator median --json
+```
+
+## Duration Store
+
+Durations are stored as JSONL (one JSON object per line) in `.balance/durations.jsonl`.
+Each line records a single test result:
+
+```json
+{"test_id":"tests/test_api.py::test_login","duration":0.42,"timestamp":"2024-01-15T10:30:00+00:00","run_id":"12345-1","worker":"node0","phase":"call"}
+```
+
+**In CI:** each parallel node writes to a separate partial file
+(`durations-<run_id>-<node_index>.jsonl`) to avoid write conflicts. Run
+`pytest-balance merge` after all nodes finish to consolidate them.
+
+**Locally:** durations are appended directly to `durations.jsonl`.
+
+Commit `durations.jsonl` to version control so all branches and CI runs share the same
+history.
+
+## Scope
+
+The `--balance-scope` option controls how tests are grouped before partitioning:
+
+| Scope | Grouping | When to use |
+|---|---|---|
+| `test` | Each test is its own unit | Tests are fully independent and durations vary widely |
+| `class` | All tests in a class are kept together | Tests share class-level fixtures |
+| `module` | All tests in a file are kept together (default) | Tests share module-level fixtures |
+| `group` | Tests tagged with `@<group>` in their node ID | Custom grouping via markers |
+
+Keeping related tests together avoids fixture teardown/setup overhead between nodes.
+The xdist work-stealing also respects scope boundaries, stealing complete groups rather
+than splitting them.
+
+## How It Works
+
+**CI-level splitting (--balance):**
+
+1. On collection, the plugin reads duration estimates from the store.
+2. Tests are grouped by the configured scope.
+3. The Longest Processing Time First (LPT) algorithm assigns groups to nodes: sort groups
+   by descending estimated duration, then greedily assign each group to the node with the
+   currently lowest total load.
+4. Only the slice for the current node index runs; the rest are deselected.
+
+**xdist scheduling (--balance with -n):**
+
+1. After all workers collect, the same LPT algorithm pre-assigns groups to workers and
+   sends each worker its initial batch.
+2. As workers finish, idle workers steal complete scope groups from the busiest worker.
+   With `--balance-scope test`, individual tests can be stolen instead of groups.
+3. Workers with no remaining work are shut down so the run ends as soon as all tests
+   complete.
+
+**Estimation strategies:**
+
+- `ema` (default): exponential moving average (alpha=0.3) over the recorded history,
+  giving more weight to recent runs.
+- `median`: statistical median over all recorded durations.
+- `last`: the single most recent recorded duration.
+
+Unknown tests (not in the store) fall back to the median estimated duration of all known
+tests.
+
+## Status
+
+Alpha. The API and file format may change between releases.