pytest-selective 0.3.0__tar.gz → 0.4.1__tar.gz

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     outputs:
       lanes: ${{ steps.plan.outputs.lanes }}
       mode: ${{ steps.files.outputs.mode }}
-      files: ${{ steps.paths.outputs.files }}
+      files: ${{ steps.files.outputs.test_roots_json }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -27,8 +27,6 @@ jobs:
         uses: ./actions/plan-lanes
         with:
           config: .github/test-lanes.json
-          base: ${{ github.event.pull_request.base.sha || github.event.before }}
-          full: ${{ github.run_attempt > 1 || contains(fromJSON('["workflow_dispatch","workflow_call","schedule","release"]'), github.event_name) || contains(github.event.pull_request.labels.*.name, 'test:full') }}
       - name: Share the repository graph and execution inputs with file selection
         env:
           PYTHONPATH: src
@@ -39,21 +37,7 @@ jobs:
         uses: ./
         with:
           config: ${{ runner.temp }}/test-impact.json
-          base: ${{ github.event.pull_request.base.sha || github.event.before }}
           full-roots: tests
-          full: ${{ github.run_attempt > 1 || contains(fromJSON('["workflow_dispatch","workflow_call","schedule","release"]'), github.event_name) || contains(github.event.pull_request.labels.*.name, 'test:full') }}
-      - id: paths
-        name: Forward exact selected paths without shell splitting
-        env:
-          MODE: ${{ steps.files.outputs.mode }}
-        run: |
-          python - <<'PY'
-          import json, os
-          from pathlib import Path
-          files = json.loads(Path('test-impact-report.json').read_text())['selected'] if os.environ['MODE'] == 'scoped' else []
-          with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
-              output.write('files=' + json.dumps(files) + '\n')
-          PY
   quality:
     runs-on: ubuntu-latest
     steps:

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/.github/workflows/public-actions.yml

@@ -19,8 +19,6 @@ jobs:
         uses: ./actions/plan-lanes
         with:
           config: .github/test-lanes.json
-          base: ${{ github.event.pull_request.base.sha || github.event.before }}
-          full: ${{ github.run_attempt > 1 || contains(fromJSON('["workflow_dispatch","workflow_call","schedule","release"]'), github.event_name) || contains(github.event.pull_request.labels.*.name, 'test:full') }}
           artifact-name: public-action-selection
   public-actions:
     needs: select-tests

pytest_selective-0.4.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.1"
+}

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.4.1](https://github.com/gigaverse-app/pytest-selective/compare/v0.4.0...v0.4.1) (2026-10-24)
+
+
+### Bug fixes
+
+* **selection:** preserve rerun scope and record planner reasons ([29d1df8](https://github.com/gigaverse-app/pytest-selective/commit/29d1df806816203bad1e7a4a53f38b7e75c1d268))
+
+## [0.4.0](https://github.com/gigaverse-app/pytest-selective/compare/v0.3.0...v0.4.0) (2026-10-24)
+
+
+### Features
+
+* **actions:** simplify selection adoption with shared defaults ([#63](https://github.com/gigaverse-app/pytest-selective/issues/63)) ([85e082d](https://github.com/gigaverse-app/pytest-selective/commit/85e082dfdbcf2f8c02ac3de38613c818cb749807))
+
 ## [0.3.0](https://github.com/gigaverse-app/pytest-selective/compare/v0.2.0...v0.3.0) (2026-10-23)
 
 

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytest-selective
-Version: 0.3.0
+Version: 0.4.1
 Summary: Explainable Python test impact analysis: select affected pytest files from Git changes
 Project-URL: Homepage, https://github.com/gigaverse-app/pytest-selective
 Project-URL: Documentation, https://pytest-selective.readthedocs.io/en/latest/
@@ -71,6 +71,9 @@ and slack. [See the source runs and method](https://github.com/gigaverse-app/ci-
 
 ## Choose how to use it
 
+Follow the [adoption tutorial and checklist](docs/tutorials/adoption-checklist.md)
+for local execution, CI routing, dependency audits, timing feedback and measured rollout.
+
 | You want to… | Use | What it saves |
 | --- | --- | --- |
 | Test local edits with your existing pytest command | `uv add --dev pytest-selective`, then `uv run pytest --selective` | Unaffected test execution; staged, unstaged and untracked changes are included |
@@ -231,7 +234,7 @@ skip pytest, because invoking pytest without paths runs the whole suite.
 | A transitive dependency | Import chains and package initialization |
 | A deleted or renamed module | Dependencies in both the base and head trees |
 | Fixtures or startup code | Ancestor conftests and configured global modules |
-| Templates, schemas, or data files | Reader-owned declarations and YAML sidecars |
+| Templates, schemas, or data files | [Reader-owned declarations and YAML sidecars](docs/tutorials/sidecar-dependencies.md) |
 | A surprisingly large selection | Dependency paths, startup-floor and blast-radius explanations |
 | A large CI suite | Cached parsing, graph reuse, and duration-based shard planning |
 | Undeclared runtime reads | An opt-in pytest recorder and audit command |

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/README.md

@@ -40,6 +40,9 @@ and slack. [See the source runs and method](https://github.com/gigaverse-app/ci-
 
 ## Choose how to use it
 
+Follow the [adoption tutorial and checklist](docs/tutorials/adoption-checklist.md)
+for local execution, CI routing, dependency audits, timing feedback and measured rollout.
+
 | You want to… | Use | What it saves |
 | --- | --- | --- |
 | Test local edits with your existing pytest command | `uv add --dev pytest-selective`, then `uv run pytest --selective` | Unaffected test execution; staged, unstaged and untracked changes are included |
@@ -200,7 +203,7 @@ skip pytest, because invoking pytest without paths runs the whole suite.
 | A transitive dependency | Import chains and package initialization |
 | A deleted or renamed module | Dependencies in both the base and head trees |
 | Fixtures or startup code | Ancestor conftests and configured global modules |
-| Templates, schemas, or data files | Reader-owned declarations and YAML sidecars |
+| Templates, schemas, or data files | [Reader-owned declarations and YAML sidecars](docs/tutorials/sidecar-dependencies.md) |
 | A surprisingly large selection | Dependency paths, startup-floor and blast-radius explanations |
 | A large CI suite | Cached parsing, graph reuse, and duration-based shard planning |
 | Undeclared runtime reads | An opt-in pytest recorder and audit command |

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/action.yml

@@ -10,7 +10,7 @@ inputs:
     required: true
   base:
     description: Complete change-set base (a validated ancestor, PR base, or push before SHA).
-    required: true
+    default: ${{ github.event.pull_request.base.sha || github.event.before }}
   head:
     description: Exact checked-out commit.
     default: HEAD
@@ -18,8 +18,9 @@ inputs:
     description: Space-separated complete test roots used if planning cannot prove a narrower scope.
     required: true
   full:
-    description: Force the complete suite for schedules, explicit labels, or coverage checkpoints.
-    default: 'false'
+    description: auto preserves selection on PR/push reruns and runs full for manual/scheduled/release checkpoints or test:full.
+      Override with true or false.
+    default: auto
   extra-files:
     description: Optional newline file containing prior failure canaries or additional changed paths.
     default: ''
@@ -58,6 +59,10 @@ inputs:
       with `head`, so they stay visible after `base` moves to a validated tree. Without it, or without the history, they compare
       against `base`.
     default: ${{ github.event.pull_request.base.sha }}
+  explanation-format:
+    description: 1 preserves the legacy explanation schema; 2 includes the actual planner reasons. Use 2 with a compatible
+      reporter.
+    default: '1'
 outputs:
   base:
     description: The base the selection was made from; `alternate-base` when it selected fewer tests.
@@ -68,6 +73,9 @@ outputs:
   test_roots:
     description: Exact selected files, or complete roots on fallback.
     value: ${{ steps.action.outputs.test_roots }}
+  test_roots_json:
+    description: JSON array of selected files or fallback roots; preserves spaces in paths. Empty array for none.
+    value: ${{ steps.action.outputs.test_roots_json }}
   shard_count:
     description: Number of shards.
     value: ${{ steps.action.outputs.shard_count }}
@@ -104,3 +112,4 @@ runs:
       dependency-token: ${{ inputs.dependency-token }}
       explanation-artifact: ${{ inputs.explanation-artifact }}
       graph-base: ${{ inputs.graph-base }}
+      explanation-format: ${{ inputs.explanation-format }}

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/actions/plan-lanes/action.yml

@@ -6,10 +6,10 @@ inputs:
     required: true
   base:
     description: Base commit containing the complete change set.
-    required: true
+    default: ${{ github.event.pull_request.base.sha || github.event.before }}
   full:
-    description: Run every lane for an explicit full-test checkpoint; ordinary PRs and pushes use selection.
-    default: 'false'
+    description: 'auto preserves selection on PR/push reruns and runs full for manual/scheduled/release checkpoints or test:full. Override with true or false.'
+    default: auto
   artifact-name:
     description: >
       Upload the lane plan under this name, where CI-esta's report renders it as
@@ -41,7 +41,7 @@ runs:
       run: |
         export PYTHONPATH="$SELECTIVE_ACTION/../../src${PYTHONPATH:+:$PYTHONPATH}"
         args=(--config "$SELECTIVE_CONFIG" --base "$SELECTIVE_BASE" --github-output "$GITHUB_OUTPUT")
-        if [ "$SELECTIVE_FULL" = true ]; then args+=(--full); fi
+        args+=(--full "$SELECTIVE_FULL")
         uv run --no-project --python 3.14 --with pydantic==2.13.4 --with pyyaml==6.0.3 \
           python -m pytest_selective.ci "${args[@]}" | tee test-lanes.json
         {

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/actions/test-impact/action.yml

@@ -9,7 +9,7 @@ inputs:
     required: true
   base:
     description: Complete change-set base (a validated ancestor, PR base, or push before SHA).
-    required: true
+    default: ${{ github.event.pull_request.base.sha || github.event.before }}
   head:
     description: Exact checked-out commit.
     default: HEAD
@@ -17,8 +17,8 @@ inputs:
     description: Space-separated complete test roots used if planning cannot prove a narrower scope.
     required: true
   full:
-    description: Force the complete suite for schedules, explicit labels, or coverage checkpoints.
-    default: 'false'
+    description: 'auto preserves selection on PR/push reruns and runs full for manual/scheduled/release checkpoints or test:full. Override with true or false.'
+    default: auto
   extra-files:
     description: Optional newline file containing prior failure canaries or additional changed paths.
     default: ''
@@ -60,6 +60,9 @@ inputs:
       its merge base with `head`, so they stay visible after `base` moves to a validated tree.
       Without it, or without the history, they compare against `base`.
     default: ${{ github.event.pull_request.base.sha }}
+  explanation-format:
+    description: '1 preserves the legacy explanation schema; 2 includes the actual planner reasons. Use 2 with a compatible reporter.'
+    default: '1'
 outputs:
   base:
     value: ${{ steps.select.outputs.base }}
@@ -70,6 +73,9 @@ outputs:
   test_roots:
     value: ${{ steps.select.outputs.test_roots }}
     description: Exact selected files, or complete roots on fallback.
+  test_roots_json:
+    value: ${{ steps.select.outputs.test_roots_json }}
+    description: JSON array of selected files or fallback roots; preserves spaces in paths. Empty array for none.
   shard_count:
     value: ${{ steps.select.outputs.shard_count }}
     description: Number of shards.
@@ -120,6 +126,7 @@ runs:
         # Environment only: the CLI never takes it on argv, and git gets it per process, not in config.
         IMPACT_DEPENDENCY_TOKEN: ${{ inputs.dependency-token }}
         IMPACT_GRAPH_BASE: ${{ inputs.graph-base }}
+        IMPACT_EXPLANATION_FORMAT: ${{ inputs.explanation-format }}
         SHARED_ACTION_PATH: ${{ github.action_path }}
       run: |
         export PYTHONPATH="$SHARED_ACTION_PATH/../../src${PYTHONPATH:+:$PYTHONPATH}"
@@ -136,10 +143,10 @@ runs:
         args=(affected --config "$IMPACT_CONFIG" --base "$IMPACT_BASE" --head "$IMPACT_HEAD"
               --max-shards "$IMPACT_SHARDS" --minimum-files "$IMPACT_MINIMUM" --github-output "$GITHUB_OUTPUT" --output test-impact-report.json
               --durations "$IMPACT_DURATIONS" --shard-seconds "$IMPACT_SHARD_SECONDS"
-              --explanation-output test-impact-explanation.json)
+              --explanation-output test-impact-explanation.json --explanation-format "${IMPACT_EXPLANATION_FORMAT:-1}")
         # A reused workspace must not upload a previous plan's explanation.
         rm -f test-impact-explanation.json
-        if [ "$IMPACT_FULL" = true ]; then args+=(--full); fi
+        args+=(--full "$IMPACT_FULL")
         if [ -n "$IMPACT_EXTRA" ]; then args+=(--extra-files "$IMPACT_EXTRA"); fi
         if [ -n "${IMPACT_GRAPH_BASE:-}" ]; then args+=(--graph-base "$IMPACT_GRAPH_BASE"); fi
         # Optional: an unfetchable alternate only forgoes a smaller selection.
@@ -170,6 +177,7 @@ runs:
             echo "base=$IMPACT_BASE"
             echo "mode=full"
             echo "test_roots=$IMPACT_ROOTS"
+            echo "test_roots_json=$(python3 -c 'import json,os,shlex; print(json.dumps(shlex.split(os.environ["IMPACT_ROOTS"])))')"
             echo "shard_count=$IMPACT_SHARDS"
             echo "groups=$(python3 -c 'import json,os; print(json.dumps(list(range(1,int(os.environ["IMPACT_SHARDS"])+1))))')"
             echo "reason=Test impact proof unavailable; complete suite fallback"

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/docs/README.md

@@ -4,6 +4,7 @@
 | --- | --- |
 | Have a coding agent optimize your test/CI workflow | [Agent prompt, skill and AGENTS.md instructions](agents.md) |
 | See a real regression caught by a smaller selection | [Runnable tutorial](tutorial.md) |
+| Declare fixture, schema, scanner, or subprocess inputs | [Sidecar tutorial](tutorials/sidecar-dependencies.md) |
 | Configure an existing Python project | [Configuration and dependency declarations](configuration.md) |
 | Use `pytest --selective` or run local edits before collection | [Native plugin and local runner](local-development.md) |
 | Run the selected files safely in CI | [GitHub Actions and runner integration](ci.md) |

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/docs/ci-toolkit.md

@@ -60,8 +60,9 @@ benchmark pairs can be declared with exact run/attempt/head references through
 Never turn the fraction of files or lanes skipped into a measured time saving.
 
 Ordinary label edits no longer launch the CI validation workflows. Add `test:full`
-before the next code update to force full validation, or use an explicit rerun
-or manual dispatch for immediate full execution. Ordinary PRs and main pushes
+before the next code update to force full validation, or use a manual dispatch
+for immediate full execution. A PR/push rerun preserves selection and uses the
+original event payload; adding a label afterward may not change that payload. Ordinary PRs and main pushes
 use dependency selection, including for contract and installed-package tests.
 Unreferenced documentation runs zero tests; explicit full checkpoints and
 failed-planning fallbacks retain complete coverage and required gates.

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/docs/ci.md

@@ -4,12 +4,26 @@ Plan on committed revisions with complete Git history and a known passing base.
 Keep a scheduled full-suite run. Do not drop unresolved failures merely by moving
 the base forward after a failed run.
 
+PR and push reruns preserve the selection policy for the same base, head and
+inputs. Rerunning does not request the full suite. Use `full: 'true'`, a
+`test:full` label present in the event, or a scheduled/manual/release checkpoint
+for full validation. `full: 'false'` overrides event defaults, while missing
+history and operational uncertainty still retain conservative execution.
+
+The planner records its actual reasons once and carries them into its report.
+The CLI explanation format 2 includes `selection_reasons`; `--explanation-format 1`
+omits that field for older strict readers. The public `actions/test-impact@v1`
+action defaults to format 1 for compatibility. A compatible reporter can request
+`explanation-format: '2'`; CI-esta's wrapper does this automatically. Older
+artifacts cannot identify a trigger they never recorded, so readers must say
+that the reason is unavailable rather than infer it from the attempt number.
+
 ## GitHub Actions
 
 This job uses the repository's composite action and runs the plan on the checked-out
 head. Use the moving `v1` release tag and adapt dependency installation to
-your project. The example assumes a uv project
-and test paths without spaces (the action's `test_roots` output is space-separated).
+your project. The example assumes a uv project and passes the planned paths as
+JSON, so spaces in filenames survive execution.
 
 ```yaml
 name: Affected tests
@@ -28,26 +42,44 @@ jobs:
         uses: gigaverse-app/pytest-selective@v1
         with:
           config: .github/test-impact.json
-          base: ${{ github.event.pull_request.base.sha }}
           full-roots: tests
       - if: steps.impact.outputs.mode != 'none'
         run: uv sync --locked
       - if: steps.impact.outputs.mode != 'none'
         env:
-          TEST_ROOTS: ${{ steps.impact.outputs.test_roots }}
+          TEST_ROOTS: ${{ steps.impact.outputs.test_roots_json }}
         shell: bash
         run: |
-          read -r -a roots <<< "$TEST_ROOTS"
-          if [ "${#roots[@]}" -eq 0 ]; then
-            echo "Expected test roots for a nonempty plan" >&2
-            exit 1
-          fi
-          uv run --locked pytest "${roots[@]}"
+          uv run --locked python - <<'PY'
+          import json, os, subprocess, sys
+          roots = json.loads(os.environ['TEST_ROOTS'])
+          if not roots:
+              raise SystemExit('Expected test roots for a nonempty plan')
+          raise SystemExit(subprocess.call([sys.executable, '-m', 'pytest', '-p', 'no:selective', *roots]))
+          PY
 ```
 
 The action creates its own Python 3.14 planner environment. Your uv project
 controls the test interpreter. `full-roots` must contain the complete roots, not
-the previous selection. With `full: 'true'`, the action requests a complete run.
+the previous selection. `base` defaults to the PR base or the push's previous
+commit. Override it only when you have validated a different comparison base.
+
+Both file and lane actions default to `full: auto`:
+
+| Trigger | Default |
+| --- | --- |
+| First ordinary PR or push attempt | Select affected work |
+| Rerun, manual, schedule or release | Full checkpoint |
+| PR carrying `test:full` | Full checkpoint |
+| Unknown event or unreadable required event metadata | Full checkpoint |
+
+Use `full: 'true'` to always run everything, or `full: 'false'` to request
+selection even for a manual experiment. Operational uncertainty still falls back
+to full execution. Existing explicit expressions keep their behavior; remove a
+copied standard expression to adopt the shared policy. Updating an action does
+not add missing jobs, schedules, permissions or test dependency declarations.
+GitHub reusable workflows retain the caller's event, so pass `full: 'true'` when
+the reusable invocation itself must be a checkpoint.
 
 | Planner outcome | Action behavior |
 | --- | --- |
@@ -193,8 +225,8 @@ when the README is embedded in the built package.
 The action returns a `lanes` JSON object. Expose it as a planning-job output,
 then gate each expensive job with `always() && !cancelled()` and either a true
 lane value **or a failed planning job**. This preserves tests if planning fails.
-Run the action with `full: true` for manual/release checkpoints, schedules, and
-full-test overrides. Ordinary PRs and main pushes use dependency selection.
+The default event policy handles manual/release checkpoints, schedules and
+`test:full`. Ordinary PRs and main pushes use dependency selection.
 Selected jobs retain all of their existing tests and evidence checks.
 
 

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/docs/configuration.md

@@ -54,6 +54,9 @@ runs the complete configured roots.
 
 ## Declare inputs that imports cannot describe
 
+Start with the [sidecar tutorial](tutorials/sidecar-dependencies.md) for a runnable
+fixture example, directory manifests, dependency comments, and dynamic Python inputs.
+
 For a test that reads a tracked JSON fixture, add a reader-owned comment:
 
 ```python

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/docs/selection-health.md

@@ -30,7 +30,8 @@ uv run pytest-selective audit --config .github/test-impact.json --records impact
 The recorder observes real file reads in the tests you execute. The audit can
 expose a JSON fixture, template or schema that the graph did not declare. Add an
 edge at the reader using a dependency comment or YAML sidecar, then recheck the
-route. [Declaration syntax](configuration.md#declare-inputs-that-imports-cannot-describe).
+route. [Work through the sidecar tutorial](tutorials/sidecar-dependencies.md), or consult
+[declaration syntax](configuration.md#declare-inputs-that-imports-cannot-describe).
 The audit covers observed paths; keep representative full runs for paths it has
 not seen, and explicitly model dynamic imports and external inputs.
 

{pytest_selective-0.3.0 → pytest_selective-0.4.1}/docs/tutorial.md

@@ -1,5 +1,8 @@
 # Start using pytest-selective
 
+Use the [adoption checklist](tutorials/adoption-checklist.md) to work through
+configuration, CI integration, selection health and measurement after this quickstart.
+
 ## Try your existing project
 
 Start in a Git repository whose full pytest suite passes. You need Python 3.11+,