Skip to content

test(execution): demonstrate pause and continue through public APIs - #481

Draft
roschaefer wants to merge 2 commits into
mainfrom
test/pause-continue-scenarios
Draft

roschaefer wants to merge 2 commits into
mainfrom
test/pause-continue-scenarios

Conversation

@roschaefer

@roschaefer roschaefer commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

The retained execution APIs can pause and continue in one process, but readers need small examples that expose the Git state at each checkpoint. Add two public API scenarios and a walkthrough with diagrams checked against actual refs and file contents.

Pull pauses after download while HEAD and local contents remain unchanged, then continues to merge. Push pauses with a prepared commit while the upstream remains unchanged, then publishes that exact commit. Both scenarios verify that continuing a completed operation returns Complete(0) without changing the result.

Reuse the isolated child-process harness merged in #489. Each scenario has its own working directory and Git configuration. Continuation retains the same Rust execution value; repository inputs must remain unchanged while paused.

Replay: cargo test --test pause_continue -- --nocapture.

Validation after rebasing onto main: both pause/continue scenarios, the push observer test, workspace Clippy with warnings denied, formatting and diff checks pass. The resulting files are unchanged by the rebase. Previous validation also passed workspace tests, inherited Git overrides with a symlinked TMPDIR, the contributing documentation's four Scrut cases, and the documentation production build and link validation.

@coderabbitai

coderabbitai Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The pull request adds a development guide link and a walkthrough for in-memory pull and push continuation. Integration tests check pause events, repository state at each checkpoint, and completion after continuation.

Changes: In-memory pause and continue

Layer / File(s) Summary
Pull continuation test setup and coverage
tests/pause_continue.rs
Adds temporary repository fixtures and tests that check pull state after fetch, merge, and completion.
Push continuation coverage
tests/pause_continue.rs
Tests that the prepared commit is not published at AfterRebuild, then checks publication and completion.
Walkthrough and development guide link
docs/10-contributing/03-pause-and-continue.md, docs/10-contributing/01-development.md
Documents pull and push continuation scenarios, repository checks, constraints, and limitations. The development guide links to the walkthrough.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Possibly related PRs

Merge Risk: Minimal · up to 8132a

This change adds a walkthrough and tests for pausing and continuing pull and push operations. It does not change runtime behavior, and no merge-blocking risk was identified.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the change: tests that demonstrate pause and continue for pull and push through public APIs. The changeset adds tests/pause_continue.rs with pull and push scenarios, plus documentation…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description states that the retained execution APIs can pause and continue in one process and that the PR adds two public API pull/push pause-and-continue scenarios, a walkthrough with diagrams, a…
Full details: Title check

Explanation

The title names the change: tests that demonstrate pause and continue for pull and push through public APIs. The changeset adds tests/pause_continue.rs with pull and push scenarios, plus documentation. The title follows the conventional commit style and matches the main change.

Full details: Description check

Explanation

The description states that the retained execution APIs can pause and continue in one process and that the PR adds two public API pull/push pause-and-continue scenarios, a walkthrough with diagrams, and an isolated test harness. It also lists validation steps and a replay command. This is directly related to the changeset (tests/pause_continue.rs and docs/10-contributing/03-pause-and-continue.md), so it is not off-topic and not vague.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 5d219f54-750e-4d00-ac45-4227eb08cfc6
Commits

Reviewing files that changed from the base of the PR and between 194ff6d and 8132ae3.

Files selected for processing: 3

  • docs/10-contributing/01-development.md
  • docs/10-contributing/03-pause-and-continue.md
  • tests/pause_continue.rs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

roschaefer added a commit that referenced this pull request Nov 12, 2026
Repository tests currently change the parent test process's working
directory and serialize through a global mutex. That leaves other test
threads exposed to the changed directory, and command code can still
read the developer's Git configuration. Run repository scenarios in
separate processes so their directories, environment and process-wide
library state cannot interfere.

Branched from current main (`657525c`), independently of #478–#481.
Production command behavior and the library API are unchanged.

```text
cargo test (parallel test threads; original directory/environment)
    |
    +-- exact repository test A
    |     temporary home + fresh repository A
    |     library calls and assertions run here
    |
    +-- exact repository test B
          temporary home + fresh repository B
          library calls and assertions run here
```

The existing `with_repository` helper reruns its named test in the same
test executable, filtered with `--exact`. The selected child executes
the scenario closure directly against the library. Each fixture has a
fresh repository on main with a local Git identity; the child has its
own HOME/XDG configuration directory, disables global/system Git
configuration and removes inherited Git repository/configuration
overrides. There is no directory mutex.

The parent owns cleanup and receives child stdout/stderr and failures.
Normal test filtering and diagram output with `--nocapture` remain
available:

```sh
cargo test --lib fetch::tests:: -- --nocapture --test-threads=8
```

Keep setup and assertions inside the fixture closure because the named
test is re-entered in the child. Pure unit tests run directly in the
parent harness. This isolates tests; concurrent library operations in
one process still need a separate production refactor to use explicit
repository paths.

Regression tests check:
- The fixture's PID differs from its parent's, with its own home and
repository; the parent's directory/home remain unchanged.
- Inherited GIT_DIR, index and configuration overrides do not affect the
fixture.
- An intentional assertion failure inside a repository scenario fails
its parent test and preserves the diagnostic.

The development guide explains the fixture contract and how to replay
tests.

Validation: all 62 workspace Rust tests pass with eight test threads,
including the three isolation regressions. Workspace clippy with
warnings denied, formatting and diff checks pass. All implementation
changes are under cfg(test); the CLI integration suite was not rerun.
Base automatically changed from feat/pull-pause to main November 12, 2026 20:24
@roschaefer
roschaefer force-pushed the test/pause-continue-scenarios branch 2 times, most recently from 8132ae3 to c2c9c7e Compare November 16, 2026 16:24
@roschaefer
roschaefer changed the base branch from main to test/shared-scenario-fixtures November 16, 2026 16:24
@roschaefer
roschaefer force-pushed the test/pause-continue-scenarios branch from c2c9c7e to 45fc0b2 Compare November 16, 2026 17:36
@roschaefer
roschaefer force-pushed the test/shared-scenario-fixtures branch from 1189ba4 to 2e2baca Compare November 16, 2026 17:36
Base automatically changed from test/shared-scenario-fixtures to main November 16, 2026 17:46
roschaefer added a commit that referenced this pull request Nov 16, 2026
Separate Rust fixture histories can drift from the scenarios exercised
by Bats and Scrut. Reuse the existing push-ahead recipe through Bash
while keeping both setup and library execution inside the isolated test
child. Its parent owns temporary files, including nested Git setup
directories.

Keep the push-specific fixture beside its scenario so other integration
test crates can reuse the process harness without unused setup helpers.
Forward child output so public API walkthroughs remain visible with
`--nocapture`.

Rebased onto main after #488 merged. #481 reuses this harness for
pause/continue scenarios.

Validation: the external push test, formatting and diff checks pass
after rebasing. The previous full validation also passed workspace
tests, Clippy, and inherited Git overrides with a symlinked TMPDIR.
Make the in-memory continuation boundaries visible with one-splice pull and push scenarios. Compare repository diagrams against actual refs and contents so readers can see what has happened when each call returns and what continuation changes.
Run library operations in child processes so inherited Git settings and working directory changes cannot leak between public API scenarios.
@roschaefer
roschaefer force-pushed the test/pause-continue-scenarios branch from 45fc0b2 to 2a674f7 Compare November 16, 2026 17:47

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant