Extract CronJob spy mock to shared test helpers

[UniquePixels]

Context

Audit ID: TEST-2

The `spyCronFrom()` helper in `scheduled-event.test.ts` is complex and file-local. It could be reused if more scheduled event tests are written.

Approach

Move to `src/core/lib/test-helpers/` alongside `assertDefined` and `createMockCommand`.

Files

• `src/core/sparks/scheduled-event.test.ts` (source)
• `src/core/lib/test-helpers/` (destination)

[coderabbitai]

Coding Plan

Summary

• Extract spyCronFrom() to a new mock-cron.ts file in test-helpers, following the existing pattern of domain-specific helper modules
• Modify the return signature to include a restore function, enabling consumers to manage spy cleanup in their own afterEach hooks
• Integrate with the barrel export and update the single existing consumer to use the shared implementation

Design Choices

Design Choice 1: How should spy cleanup be managed when the helper is shared across files?

Options Considered:

1. Return both getOnTick and a restore function from spyCronFrom(), letting consumers manage their own cleanup lifecycle
2. Export separate setup/teardown functions that consumers must wire together
3. Use a class-based approach with explicit dispose semantics

Chosen Option: 1

Rationale: Returning a restore function alongside getOnTick is the simplest approach that gives consumers full control while keeping the API minimal and consistent with existing helper patterns.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Extract Helper and Update Consumer

This phase creates the new shared helper file, integrates it with the barrel export, and updates the existing test file to consume the shared implementation.

Task 1: Create Cron Mock Helper Module

Create the shared helper file with the extracted spy logic and a cleanup-friendly return signature.

• Create src/core/lib/test-helpers/mock-cron.ts as a new module
• Implement spyCronFrom() function with imports from bun:test (spyOn, mock) and cron (CronJob)
• Return an object containing getOnTick accessor and restore function that calls mockRestore() on the spy
• Maintain the same mock implementation: capture onTick callback, return stub with stop and nextDate methods

Task 2: Export from Barrel Index

Add the new helper to the test-helpers barrel export.

• Update src/core/lib/test-helpers/index.ts to re-export spyCronFrom from ./mock-cron

Task 3: Update Scheduled Event Tests

Migrate the test file to use the shared helper while maintaining cleanup behavior.

• Update src/core/sparks/scheduled-event.test.ts to import spyCronFrom from @/core/lib/test-helpers
• Remove the local spyCronFrom() function definition
• Update the module-level tracking variable type to match the return type of the shared helper
• Adjust afterEach hook to call the restore() method from the returned helper object
• Update test call sites to assign the helper result to the tracking variable for cleanup

🤖 Prompt for AI agents

This phase extracts the `spyCronFrom()` helper from `scheduled-event.test.ts`
into a shared test-helper module and updates all related files to use the new
shared implementation.

**Task 1: Create `src/core/lib/test-helpers/mock-cron.ts`**
- Create a new file following the domain-specific module pattern used by
`mock-client.ts`, `mock-guards.ts`, etc.
- Import `spyOn` and `mock` from `bun:test`, and `CronJob` from `cron`
- Implement and export `spyCronFrom()` which:
  - Spies on `CronJob.from` to intercept calls and capture the `onTick` callback
  - Returns a stub object with `stop` and `nextDate` methods
  - Returns an object with two properties:
    - `getOnTick`: an accessor for the captured `onTick` callback
    - `restore`: a function that calls `mockRestore()` on the spy
- The internal mock implementation must remain functionally identical to the
original in `scheduled-event.test.ts`

**Task 2: Update `src/core/lib/test-helpers/index.ts`**
- Add a re-export of `spyCronFrom` from `./mock-cron`

**Task 3: Update `src/core/sparks/scheduled-event.test.ts`**
- Replace the `spyCronFrom` import source (or add import) to pull from
`@/core/lib/test-helpers`
- Delete the local `spyCronFrom()` function definition
- Update the module-level tracking variable's type to match the return type of
the shared `spyCronFrom()` (i.e., an object with `getOnTick` and `restore`)
- Update the `afterEach` hook to call `.restore()` on the tracking variable
instead of any previous cleanup approach
- Update all test call sites to assign the result of `spyCronFrom()` to the
tracking variable so `restore()` can be called during teardown

Research

The test-helpers directory follows a modular pattern where each domain has its own file (mock-client.ts, mock-guards.ts, mock-interaction.ts, mock-permissions.ts) with all exports re-exported through a barrel index.ts. All 19 test files import exclusively via the @/core/lib/test-helpers path alias. The existing spyCronFrom() function in scheduled-event.test.ts intercepts CronJob.from to capture the onTick callback, returning a getter for tests to manually trigger cron execution. It currently relies on module-level state and an afterEach hook for cleanup.

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase extracts the `spyCronFrom()` helper from `scheduled-event.test.ts`
into a shared test-helper module and updates all related files to use the new
shared implementation.

**Task 1: Create `src/core/lib/test-helpers/mock-cron.ts`**
- Create a new file following the domain-specific module pattern used by
`mock-client.ts`, `mock-guards.ts`, etc.
- Import `spyOn` and `mock` from `bun:test`, and `CronJob` from `cron`
- Implement and export `spyCronFrom()` which:
  - Spies on `CronJob.from` to intercept calls and capture the `onTick` callback
  - Returns a stub object with `stop` and `nextDate` methods
  - Returns an object with two properties:
    - `getOnTick`: an accessor for the captured `onTick` callback
    - `restore`: a function that calls `mockRestore()` on the spy
- The internal mock implementation must remain functionally identical to the
original in `scheduled-event.test.ts`

**Task 2: Update `src/core/lib/test-helpers/index.ts`**
- Add a re-export of `spyCronFrom` from `./mock-cron`

**Task 3: Update `src/core/sparks/scheduled-event.test.ts`**
- Replace the `spyCronFrom` import source (or add import) to pull from
`@/core/lib/test-helpers`
- Delete the local `spyCronFrom()` function definition
- Update the module-level tracking variable's type to match the return type of
the shared `spyCronFrom()` (i.e., an object with `getOnTick` and `restore`)
- Update the `afterEach` hook to call `.restore()` on the tracking variable
instead of any previous cleanup approach
- Update all test call sites to assign the result of `spyCronFrom()` to the
tracking variable so `restore()` can be called during teardown

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#6 - 🌈 improve(testing): consolidate test utilities [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!