Installation

Install

npm install --save-dev @gfargo/git-scenarios simple-git
# or
yarn add --dev @gfargo/git-scenarios simple-git
# or
pnpm add --save-dev @gfargo/git-scenarios simple-git

simple-git is a peer dependency — installed alongside so your project picks the version compatible with both this package and any other simple-git consumer you have.

Requirements

• Node.js: ^22.22.2 || ^24.15.0 || >=26.0.0
• Git: Any modern version (2.25+ recommended for sparse checkout support)

Note

The ./mocks subpath (@gfargo/git-scenarios/mocks) does not require simple-git as a peer dependency. It uses simple-git’s type definitions only (import type) and has zero runtime dependencies. You can install and use the mock factories without having simple-git in your project.

Module format

The package ships both CJS and ESM. Use import or require — both work:

// ESM
import { spinUpScenario } from '@gfargo/git-scenarios'

// CJS
const { spinUpScenario } = require('@gfargo/git-scenarios')

Package exports

Subpath	What it provides
@gfargo/git-scenarios	Main API: spinUpScenario, fromScenario, createTempGitRepo, assertRepo, snapshotRepo, all atoms, all scenarios, registry
@gfargo/git-scenarios/atoms	Atom layer only (tree-shakeable)
@gfargo/git-scenarios/scenarios	Scenario registry only
@gfargo/git-scenarios/tempGitRepo	Low-level createTempGitRepo only
@gfargo/git-scenarios/matchers	Jest/Vitest expect(...) matchers (toBeMidMerge, toHaveConflictIn, …)
@gfargo/git-scenarios/capture	Programmatic capture helpers (gatherRepoState, renderScenarioModule, …)
@gfargo/git-scenarios/jest	Jest framework adapter (describeWithScenario)
@gfargo/git-scenarios/vitest	Vitest framework adapter (same shape as Jest)
@gfargo/git-scenarios/node-test	Node.js native test runner adapter (node:test)
@gfargo/git-scenarios/mocha	Mocha framework adapter
@gfargo/git-scenarios/ava	AVA framework adapter (withScenario handle pattern)
@gfargo/git-scenarios/playwright	Playwright fixture (test.extend) for E2E tests
@gfargo/git-scenarios/cypress	Cypress task helper for E2E tests
@gfargo/git-scenarios/mocks	Mock factories for simple-git types (StatusResult, LogResult, BranchSummary, DiffResult) — zero runtime deps
@gfargo/git-scenarios/mcp	Model Context Protocol server (programmatic access)

TypeScript

The package is TypeScript-first — all public APIs ship with full type declarations and source maps. No additional @types/ package needed.