mocha-to-jest-migration

Files (13)

• .skill-eval.yaml
• SKILL.md
• evals.json · evals/
• mixed-patterns.spec.js · evals/fixtures/
• mock-lifecycle.spec.js · evals/fixtures/
• proxyquire-module.spec.js · evals/fixtures/
• sinon-args.spec.js · evals/fixtures/
• sinon-sandbox.spec.js · evals/fixtures/
• sinon-stubs.spec.js · evals/fixtures/
• sinon-timers.spec.js · evals/fixtures/
• trigger-queries.json · evals/
• assertion-mapping.md · references/
• mock-mapping.md · references/

SKILL.md (first lines)

# Mocha to Jest migration

## Use this skill when

- The suite still uses Mocha, Chai, or Sinon and needs a staged migration to Jest.
- You find `describe`/`it` tests using Chai assertions or Sinon stubs that need Jest equivalents.
- The work includes runner config, setup files, fake timers, spies, or snapshots.

## Do not use this skill when

- The test suite already uses Jest — the task is not a migration.
- The ask is to add new tests to an existing Mocha suite without converting it.

## Inputs to gather

**Required before editing**
- The existing Mocha, Chai, and Sinon versions and test bootstrap configuration.
- The repository's current or planned Jest configuration and conventions.

**Helpful if present**
- Any test utilities, global setup, environment assumptions, or module mocking patterns.
- The subset of tests to migrate first and the commands used to run them.

**Only investigate if encountered**
- Non-standard Chai plugins (e.g., `chai-as-promised`, `chai-http`) that need separate handling.

## First move

Inventory what needs to migrate before touching any test files:

```sh
grep -r "require('chai')\|from 'chai'\|require('sinon')\|from 'sinon'" --include="*.ts" --include="*.js" -l
grep -r "require('mocha')\|\.mocharc" --include="*.ts" --include="*.js" --include="*.json" -l
```

Then convert a **single small representative file** first, run it under Jest, and confirm the project's Jest setup works before migrating more files.
Consult [`references/assertion-mapping.md`](references/assertion-mapping.md) and [`references/mock-mapping.md`](references/mock-mapping.md) before rewriting patterns.

## Workflow

1. Identify all Mocha, Chai, and Sinon patterns in use.
2. Convert a small representative file first and verify the project's Jest setup.
3. Replace assertion styles with idiomatic Jest expectations using the assertion mapping reference.
4. Replace mocks, spies, and stubs with Jest equivalents using the mock mapping reference.
5. Convert shared setup and teardown patterns carefully (`before`/`after` → `beforeAll`/`afterAll`, `beforeEach`/`afterEach` stay the same).
6. Update test utilities, config, or setup files only where required for parity.
7. Migrate incrementally and run the relevant tests after each batch.

## Worked migration slice

Use this as the shape for one end-to-end file before scaling out:

```js
// Mocha + Chai + Sinon
describe("retries", () => {
  let clock;

  beforeEach(() => {
    clock = sinon.useFakeTimers();
  });

  afterEach(() => {
    clock.restore();
    sinon.restore();
  });

  it("waits and retries once", async () => {
    const request = sinon.stub(api, "request").rejects(new Error("nope"));
    const retry = sinon.stub(api, "retry").resolves({ ok: true });

    const run = service.run();
    await clock.tickAsync(1000);
    await run;

    expect(request.calledOnce).to.equal(true);
    expect(retry.calledOnce).to.equal(true);
    expect(retry.firstCall.args[0]).to.deep.equal({ delay: 1000 });
  });
});
```

```js
// Jest
describe("retries", () => {
  beforeEach(() => {
    jest.useFakeTimers();
    jest.spyOn(api, "request").mockRejectedValue(new Error("nope"));
    jest.spyOn(api, "retry").mockResolvedValue({ ok: true });
  });

  afterEach(() => {
    jest.useRealTimers();
    jest.restoreAllMocks();
  });

  it("waits and retries once", async () => {
    const run = service.run();
    await jest.advanceTimersByTimeAsync(1000);
    await run;

    expect(api.request).toHaveBeenCalledTimes(1);
    expect(api.retry).toHaveBeenCalledTimes(1);
    expect(api.retry).toHaveBeenCalledWith({ delay: 1000 });
  });
});
```

## Outputs

- Test files and config updated to Jest (imports, lifecycle, matchers, runners).
- Evidence that the suite runs under Jest with equivalent or improved coverage.

## Guardrails

- **Must** preserve async behavior, timer behavior, and module mocking semantics explicitly.
- **Must** use `await jest.advanceTimersByTimeAsync(n)` — not `jest.advanceTimersByTime(n)` — when the original test used `clock.tickAsync()` inside an async body. Using the synchronous variant silently breaks async ordering.
- **Must not** do bulk mechanical rewrites without validation — migrate in small batches.
- **Should** keep test names and intent stable unless the user asks for broader cleanup.
- **Should** watch for memory or environment differences in CI after migration.

From matt-riley/agent-skills, GPL-3.0.

More from matt-riley/agent-skills