logseq/docs/agent-guide/053-logseq-cli-async-test-isolation.md

# Logseq CLI and db-worker-node Async Test Isolation Plan

Goal: Audit all CLI-related async test cases and ensure every mocked function, overridden global binding, and shared test state is reset after each test case so no test leaks state into later tests.

Architecture: Prefer per-test scoped mocking (`with-redefs` / `p/with-redefs`) and explicit `:each` fixtures for mutable globals, while keeping real process/server lifecycle cleanup in `p/finally` so async resources are always released.

Tech Stack: ClojureScript, `cljs.test`, `promesa`, Node.js-based test runtime.

Related: Builds on `docs/agent-guide/001-logseq-cli.md`, `docs/agent-guide/003-db-worker-node-cli-orchestration.md`, `docs/agent-guide/015-logseq-cli-db-worker-node-housekeeping.md`, and `docs/agent-guide/035-logseq-cli-db-worker-deps-cli-decoupling.md`.

## Problem statement

Current CLI-related async tests rely heavily on mutating namespace vars and process globals with `set!`, then restoring them manually in `p/finally` blocks.

That pattern works only if every async branch reaches cleanup. It is easy to miss one restore path, and a failed or aborted test can leave mutated globals behind for later tests.

The most leak-prone coverage today is concentrated in these files:

- `src/test/logseq/cli/command/sync_test.cljs` — many async tests mutate `cli-server/ensure-server!`, `transport/invoke`, and `cli-config/update-config!` with `set!`.
- `src/test/logseq/cli/commands_test.cljs` — many async command execution tests mutate `cli-server/*`, `transport/invoke`, and add-command resolver vars.
- `src/test/logseq/cli/server_test.cljs` — async tests mutate daemon fns plus process globals like `js/process.kill` and `child_process.spawn`.
- `src/test/logseq/cli/command/doctor_test.cljs` and `src/test/logseq/cli/command/graph_test.cljs` — smaller but repeated manual global override patterns.
- `src/test/logseq/cli/integration_test.cljs` — a mix of safe `p/with-redefs` usage and unsafe direct `set!` of `cli-server/ensure-server!`, `transport/invoke`, and `process.stderr.write` interception.
- `src/test/logseq/cli/transport_test.cljs` — mutates `url.parse` and depends on manual restoration around async flows.
- `src/test/frontend/worker/db_worker_node_test.cljs` — async tests mutate platform/db-core/db-lock vars and also interact with module-level `defonce` atoms such as `*sse-clients`, `*ready?`, `*lock-info`, and `*file-handler` in `src/main/frontend/worker/db_worker_node.cljs`.

The risk is not theoretical: these tests are asynchronous, share a single Node process, and run against real namespace vars or process objects. Any missing reset can change behavior of unrelated tests that run later in the same suite.

## Current leak vectors

### 1. Manual `set!` / restore in async tests

The dominant pattern is:

1. capture original var value,
2. `set!` the var to a mock,
3. run async code,
4. restore in `p/finally`.

This appears throughout `sync_test.cljs`, `commands_test.cljs`, `server_test.cljs`, `doctor_test.cljs`, `graph_test.cljs`, and parts of `integration_test.cljs`.

This pattern is brittle because cleanup is duplicated in every test and can drift over time.

### 2. Process-global overrides

Some tests override Node globals directly, for example:

- `child_process.spawn` in `src/test/logseq/cli/server_test.cljs`
- `js/process.kill` in `src/test/logseq/cli/server_test.cljs`
- `js/process.stderr.write` via `capture-stderr!` in `src/test/logseq/cli/integration_test.cljs`
- `url.parse` in `src/test/logseq/cli/transport_test.cljs`

These are more dangerous than namespace-local mocks because they affect any code running in the same process while the override is active.

### 3. Module-level mutable atoms in db-worker-node

`src/main/frontend/worker/db_worker_node.cljs` keeps daemon state in `defonce` atoms:

- `*ready?`
- `*sse-clients`
- `*lock-info`
- `*file-handler`

`db_worker_node_test.cljs` already has one `:each` fixture for print suppression, but the file still contains tests that interact with or depend on mutable daemon state. Some tests locally save and restore `*sse-clients`; others rely on daemon stop paths to reset internals.

This should be normalized into a single fixture-backed reset strategy so every test starts from a known baseline even if a previous test fails unexpectedly.

### 4. Mixed mocking styles across files

Some tests already use safer scoped mocking:

- `p/with-redefs` in `src/test/logseq/cli/integration_test.cljs`
- `with-redefs` in targeted synchronous tests

But many nearby tests still use raw `set!`. The inconsistency makes future maintenance error-prone and makes it harder to know which tests are safely isolated.

## Scope

This plan covers async tests for current `logseq-cli` and `db-worker-node` behavior.

In scope:

- `src/test/logseq/cli/*.cljs`
- `src/test/logseq/cli/command/*.cljs`
- `src/test/frontend/worker/db_worker_node_test.cljs`
- `src/test/frontend/worker/db_worker_node_lock_test.cljs` if follow-up cleanup is needed for consistency

Out of scope:

- Non-CLI frontend async tests unless a reusable helper extracted here is intentionally shared
- Refactoring production runtime logic unless needed only to expose test-reset hooks for daemon state
- Rewriting all sync tests that already use safe scoped mocks

## Desired end state

After this work:

- every async test that mocks a namespace var uses scoped mocking or a standardized helper that guarantees restoration;
- every process-global override has one canonical helper with guaranteed teardown;
- every db-worker-node mutable singleton used by tests is reset in an `:each` fixture;
- no CLI-related async test relies on state left behind by a previous test;
- the suite can run target namespaces together, repeatedly, and in different orders without order-dependent failures.

## Testing Plan

I will first lock in the current risk surface by inventorying every CLI-related async test that uses `set!`, process-global mutation, or mutable singleton state.

I will convert one representative file in each category to a safer reset pattern before touching the rest, so the approach is proven incrementally.

I will run targeted test namespaces repeatedly and in grouped combinations to detect order-dependent leakage.

NOTE: I will write or adjust tests/helpers before broad refactors where possible, and any unexpected async failure will be debugged before continuing wide mechanical conversion.

## Implementation plan

1. Create an audit checklist of all CLI-related async tests that currently use `set!`, process-global mutation, manual restore logic, or mutable singleton state.

2. Group those findings by leak type:
   - namespace-var overrides,
   - Node process/global overrides,
   - db-worker-node singleton atoms,
   - real server/daemon lifecycle cleanup.

3. Add a small shared test helper namespace for CLI async isolation, e.g. `src/test/logseq/cli/test_helper.cljs`, to centralize patterns that should no longer be repeated inline.

4. In that helper, add wrappers/macros/functions for scoped async mocking around Promesa flows so tests can replace repeated `orig-*` / `set!` / `p/finally restore` boilerplate.

5. Prefer `p/with-redefs` for namespace vars that are only needed during the async body, especially in:
   - `src/test/logseq/cli/command/sync_test.cljs`
   - `src/test/logseq/cli/commands_test.cljs`
   - `src/test/logseq/cli/command/doctor_test.cljs`
   - `src/test/logseq/cli/command/graph_test.cljs`
   - targeted sections of `src/test/logseq/cli/integration_test.cljs`

6. Convert low-risk files first (`graph_test.cljs`, `doctor_test.cljs`, `main_test.cljs` if needed) to establish the preferred style with minimal surface area.

7. Convert `src/test/logseq/cli/command/sync_test.cljs` from repeated manual `set!` restoration to scoped mocks. This file should become the reference pattern for async command tests.

8. Convert `src/test/logseq/cli/commands_test.cljs` in batches, prioritizing the async sections that currently mutate `cli-server/list-graphs`, `cli-server/ensure-server!`, `transport/invoke`, and add-command resolution vars.

9. For `src/test/logseq/cli/server_test.cljs`, separate two concerns:
   - keep real filesystem/server cleanup in `p/finally`,
   - move mock restoration for functions/globals into scoped helper wrappers wherever possible.

10. For process-global overrides that cannot use ordinary `with-redefs` (for example `child_process.spawn`, `js/process.kill`, `process.stderr.write`, `url.parse`), add dedicated helper functions that use `try`/`finally` or Promesa-aware wrappers so restoration is guaranteed from one place.

11. Refactor `src/test/logseq/cli/integration_test.cljs` to replace the remaining direct `set!` mocks with `p/with-redefs` where possible, since that file already demonstrates the safer pattern in other tests.

12. Add or reuse an `:each` fixture in `src/test/frontend/worker/db_worker_node_test.cljs` to reset db-worker-node mutable singleton atoms before and after every test:
    - `*ready?`
    - `*sse-clients`
    - `*lock-info`
    - `*file-handler`

13. Keep the existing quiet-print fixture in `db_worker_node_test.cljs`, but merge or compose it with the new daemon-state reset fixture so both print behavior and daemon singletons are normalized per test.

14. Review tests in `db_worker_node_test.cljs` that directly save/restore individual atoms (for example `*sse-clients`) and simplify them once the shared fixture guarantees a clean baseline.

15. If a daemon stop path is currently relied on for cleanup, keep asserting `stop!` behavior but do not rely on it as the only test isolation mechanism.

16. Add comments in the helper or fixture code documenting the rule: mock restoration belongs in scoped helpers/fixtures, while resource cleanup (servers, files, daemons) belongs in `p/finally`.

17. Update any contributor-facing guidance near the modified tests if a recurring pattern should be preserved, especially when replacing repetitive manual restore code with helper abstractions.

18. Run targeted namespaces individually after each batch of refactors:
    - `logseq.cli.command.graph-test`
    - `logseq.cli.command.doctor-test`
    - `logseq.cli.command.sync-test`
    - `logseq.cli.server-test`
    - `logseq.cli.transport-test`
    - `logseq.cli.commands-test`
    - `logseq.cli.integration-test`
    - `frontend.worker.db-worker-node-test`

19. Run grouped combinations of the above namespaces multiple times in the same process to catch order-dependent leaks.

20. Finish with `bb dev:lint-and-test` if the changed surface is stable enough and runtime permits.

## Verification strategy

Use three levels of verification.

### A. Static inventory verification

Re-scan CLI-related test files and confirm that leak-prone raw patterns are either gone or intentionally wrapped:

- direct `set!` to namespace vars in async tests should be eliminated or heavily reduced;
- any remaining direct process-global mutation must be routed through a dedicated helper with centralized restore logic;
- db-worker-node singleton atoms should be covered by fixtures rather than ad hoc local resets.

### B. Repetition and order verification

Run the target namespaces repeatedly and in different orders.

At minimum:

- run each namespace alone;
- run `sync-test`, `commands-test`, and `integration-test` together;
- run `server-test`, `transport-test`, and `db_worker_node_test` together;
- re-run the same grouped command at least twice to catch leaked state from the previous run.

### C. Behavioral smoke verification

Confirm that tests still validate real async behavior rather than only helper abstractions:

- server startup/shutdown tests still exercise real server lifecycle paths;
- integration tests still verify CLI flow outputs;
- db-worker-node tests still verify daemon and HTTP behavior;
- helper conversion does not weaken assertions or skip cleanup-sensitive paths.

## Proposed helper patterns

### Pattern 1: Scoped Promesa var redefs

For ordinary vars such as `cli-server/ensure-server!`, `transport/invoke`, `cli-config/update-config!`, and `db-lock/update-lock!`, prefer `p/with-redefs` around the async body.

This should replace bespoke `orig-*` capture and restoration in most test files.

### Pattern 2: Process-global guard helpers

For globals like `process.stderr.write`, `process.kill`, or JS module properties such as `child_process.spawn` and `url.parse`, create helper wrappers such as:

- `with-stderr-write-capture`
- `with-process-kill-mock`
- `with-child-process-spawn-mock`
- `with-js-property-override`

These helpers should always restore the original value in a single `finally` path.

### Pattern 3: db-worker-node state reset fixture

Create a fixture that snapshots and resets db-worker-node singleton atoms around each test. The fixture should not depend on individual tests remembering which atoms they touched.

If some atoms contain resources such as handlers or open references, the fixture should also null them out after test completion.

## Edge cases to validate during implementation

If an async test fails before reaching the happy path, mock restoration must still happen.

If a mocked function is rebound inside nested async calls, the outer helper should still restore the original after the Promise chain settles.

If real daemon startup fails, fixture teardown must not throw while resetting singleton atoms.

If `capture-stderr!` or similar helpers are used concurrently in the future, helper APIs should make nesting/ownership behavior explicit.

If a test still needs local save/restore of atom contents for assertion purposes, that local logic should compose safely with the global fixture baseline.

## Expected file touch points

Primary expected edits:

- `src/test/logseq/cli/command/graph_test.cljs`
- `src/test/logseq/cli/command/doctor_test.cljs`
- `src/test/logseq/cli/command/sync_test.cljs`
- `src/test/logseq/cli/commands_test.cljs`
- `src/test/logseq/cli/server_test.cljs`
- `src/test/logseq/cli/transport_test.cljs`
- `src/test/logseq/cli/integration_test.cljs`
- `src/test/frontend/worker/db_worker_node_test.cljs`
- `src/test/logseq/cli/test_helper.cljs` or similar new helper namespace

Possible follow-up edits:

- `src/test/frontend/worker/db_worker_node_lock_test.cljs` if helper reuse or fixture alignment is beneficial
- any nearby docs/comments that explain the approved async mocking pattern

## Non-goals

This plan does not require rewriting working synchronous tests just to match style.

This plan does not require changing production APIs unless a tiny testability hook is necessary for deterministic reset behavior.

This plan does not require introducing a new test framework; it should stay within current `cljs.test` and `promesa` patterns.

## Decision

Do not add a new lint rule or automated check for this work.

Enforce the no-leaky-mocks rule by convention, shared helpers, and fixtures only.

Adopt a two-layer strategy:

1. use scoped redefs/helpers for mocked functions and process globals;
2. use `:each` fixtures for mutable singleton state owned by `db-worker-node`.

This keeps the rollout focused on improving test isolation directly, avoids adding maintenance burden for a custom check, and still addresses both function mocking leaks and shared-state leaks.

---