feat(testing): publish shared test helpers + fixtures via ./testing

README.md

@@ -25,7 +25,7 @@ npm install @doist/cli-core
 | `options`            | `ViewOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Type contract for `{ json?, ndjson? }` per-command options that machine-output gates derive from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `spinner`            | `createSpinner`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Loading spinner factory wrapping `yocto-spinner` with disable gates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `terminal`           | `isCI`, `isStderrTTY`, `isStdinTTY`, `isStdoutTTY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | TTY / CI detection helpers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `testing` (subpath)  | `describeEmptyMachineOutput`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Vitest helpers reusable by consuming CLIs (e.g. parametrised empty-state suite covering `--json` / `--ndjson` / human modes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `testing` (subpath)  | `describeEmptyMachineOutput`, `createTestProgram`, `captureConsole`, `captureStream`, `buildTokenStore`, `buildSingleEntryStore`, `ingenEntries`, `alanGrant` / `ellieSattler` / `ianMalcolm`, `TestAccount` / `StoreEntry` / `TokenStoreHarness` / `MatchAccount` types                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Vitest helpers + fixtures reusable by consuming CLIs: a parametrised empty-state suite (`--json` / `--ndjson` / human modes); a Commander test-program builder (`createTestProgram`; the whole subpath **requires** `commander` since the barrel re-exports it); console / stdout-stderr spies that silence + auto-restore (`captureConsole` / `captureStream`, call inside a test or `beforeEach`); and a canonical stateful in-memory `TokenStore` mock plus shared account fixtures (`buildTokenStore` / `buildSingleEntryStore`) modelling `createKeyringTokenStore`'s default-selection contract — pass `matchAccount` to mirror a consumer's own ref-matching (numeric-id / case-insensitive label).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 ## Usage
 
@@ -55,6 +55,48 @@ if (tasks.length === 0) {
 }
 ```
 
+### Testing helpers (subpath)
+
+Reuse the shared vitest scaffolding instead of hand-rolling it per CLI:
+
+```ts
+import { attachStatusCommand } from '@doist/cli-core/auth'
+import {
+    alanGrant,
+    buildSingleEntryStore,
+    captureConsole,
+    createTestProgram,
+} from '@doist/cli-core/testing'
+
+it('greets the active account', async () => {
+    const logSpy = captureConsole() // silences console.log, auto-restores
+    const { store } = buildSingleEntryStore({ token: 'tok', account: alanGrant })
+    const program = createTestProgram((p) =>
+        attachStatusCommand(p, { store, renderText: (ctx) => `Signed in as ${ctx.account.email}` }),
+    )
+    await program.parseAsync(['node', 'cli', 'status'])
+    expect(logSpy).toHaveBeenCalledWith('Signed in as alan@ingen.com')
+})
+```
+
+`buildTokenStore` is a stateful in-memory `TokenStore` mock. For a CLI whose store matches refs
+differently from the default id/email/label rule, pass `matchAccount` so the mock resolves refs exactly
+like production:
+
+```ts
+import { buildTokenStore } from '@doist/cli-core/testing'
+import { matchTwistAccount } from './lib/auth-provider.js'
+
+const { store } = buildTokenStore<TwistAccount>({
+    entries: [{ account: ACCOUNT_ALAN, isDefault: true }],
+    matchAccount: matchTwistAccount,
+})
+```
+
+The whole `@doist/cli-core/testing` entrypoint links `commander` (the barrel re-exports
+`createTestProgram`) and `vitest` at import time, so install both — consuming CLIs already have them —
+and only import this subpath from test files.
+
 ### Markdown rendering (optional subpath)
 
 Install the peer-deps in the consuming CLI:

package.json

@@ -23,8 +23,8 @@
             "import": "./dist/markdown.js"
         },
         "./testing": {
-            "types": "./dist/testing.d.ts",
-            "import": "./dist/testing.js"
+            "types": "./dist/testing/index.d.ts",
+            "import": "./dist/testing/index.js"
         }
     },
     "scripts": {

src/auth/account.test.ts

@@ -3,14 +3,14 @@ import { describe, expect, it, vi } from 'vitest'
 
 import { CliError } from '../errors.js'
 import { formatJson, formatNdjson } from '../json.js'
+import { buildProgram, installCapturedConsole } from '../test-support/cli-harness.js'
 import {
     type TestAccount as Account,
     alanGrant,
     buildTokenStore,
     ellieSattler,
     ingenEntries,
-} from '../test-support/accounts.js'
-import { buildProgram, installConsoleLogSpy } from '../test-support/cli-harness.js'
+} from '../testing/accounts.js'
 import {
     type AttachAccountCurrentCommandOptions,
     type AttachAccountListCommandOptions,
@@ -76,7 +76,7 @@ function buildRemove(
 }
 
 describe('attachAccountListCommand', () => {
-    const logSpy = installConsoleLogSpy()
+    const logSpy = installCapturedConsole()
 
     it('renders default human lines with a (default) marker only on the default entry', async () => {
         const { program } = buildList()
@@ -309,7 +309,7 @@ describe('attachAccountListCommand', () => {
 })
 
 describe('attachAccountUseCommand', () => {
-    const logSpy = installConsoleLogSpy()
+    const logSpy = installCapturedConsole()
 
     it('calls setDefault and echoes the raw ref in the human success line', async () => {
         const built = buildTokenStore()
@@ -425,7 +425,7 @@ describe('attachAccountUseCommand', () => {
 })
 
 describe('attachAccountCurrentCommand', () => {
-    const logSpy = installConsoleLogSpy()
+    const logSpy = installCapturedConsole()
 
     it('renders the default human line with a (default) marker for the active account', async () => {
         const { program } = buildCurrent()
@@ -566,7 +566,7 @@ describe('attachAccountCurrentCommand', () => {
 })
 
 describe('attachAccountRemoveCommand', () => {
-    const logSpy = installConsoleLogSpy()
+    const logSpy = installCapturedConsole()
 
     it('removes the matched account by ref and marks it as the former default', async () => {
         const built = buildTokenStore()

src/auth/flow.test.ts

@@ -26,7 +26,7 @@ import {
     alanGrant,
     buildTokenStore,
     ellieSattler,
-} from '../test-support/accounts.js'
+} from '../testing/accounts.js'
 import { type RunOAuthFlowOptions, runOAuthFlow } from './flow.js'
 import type { AuthProvider, TokenBundle, TokenStore } from './types.js'
 

src/auth/login.test.ts

@@ -2,8 +2,8 @@ import type { Command } from 'commander'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { CliError } from '../errors.js'
-import { type TestAccount as Account, alanGrant } from '../test-support/accounts.js'
 import { buildProgram } from '../test-support/cli-harness.js'
+import { type TestAccount as Account, alanGrant } from '../testing/accounts.js'
 import { attachLoginCommand } from './login.js'
 import type { AuthProvider, TokenStore } from './types.js'
 

src/auth/logout.test.ts

@@ -3,13 +3,13 @@ import { describe, expect, it, vi } from 'vitest'
 
 import { CliError } from '../errors.js'
 import { formatJson } from '../json.js'
+import { buildProgram, installCapturedConsole } from '../test-support/cli-harness.js'
 import {
     type TestAccount as Account,
     type TokenStoreHarness,
     alanGrant,
     buildSingleEntryStore,
-} from '../test-support/accounts.js'
-import { buildProgram, installConsoleLogSpy } from '../test-support/cli-harness.js'
+} from '../testing/accounts.js'
 import { attachLogoutCommand } from './logout.js'
 import type { TokenStore } from './types.js'
 
@@ -44,7 +44,7 @@ function build(
 }
 
 describe('attachLogoutCommand', () => {
-    const logSpy = installConsoleLogSpy()
+    const logSpy = installCapturedConsole()
 
     it('clears the store and emits the human success line in plain mode', async () => {
         const built = buildStore()

src/auth/persist.test.ts

@@ -1,11 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 
 import { CliError } from '../errors.js'
-import {
-    type TestAccount as Account,
-    buildTokenStore,
-    ianMalcolm,
-} from '../test-support/accounts.js'
+import { type TestAccount as Account, buildTokenStore, ianMalcolm } from '../testing/accounts.js'
 import { persistBundle } from './persist.js'
 import type { TokenBundle, TokenStore } from './types.js'
 

src/auth/providers/pkce.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
-import { type TestAccount as Account, alanGrant } from '../../test-support/accounts.js'
+import { type TestAccount as Account, alanGrant } from '../../testing/accounts.js'
 import { createPkceProvider } from './pkce.js'
 
 const respond = (body: unknown, status = 200): Response =>

src/auth/refresh.test.ts

@@ -10,7 +10,7 @@ import {
     type TokenStoreHarness,
     buildTokenStore,
     ianMalcolm,
-} from '../test-support/accounts.js'
+} from '../testing/accounts.js'
 import { refreshAccessToken } from './refresh.js'
 import type {
     ActiveBundleSnapshot,

src/auth/status.test.ts

@@ -3,13 +3,13 @@ import { describe, expect, it, vi } from 'vitest'
 
 import { CliError } from '../errors.js'
 import { formatJson, formatNdjson } from '../json.js'
+import { buildProgram, installCapturedConsole } from '../test-support/cli-harness.js'
 import {
     type TestAccount as Account,
     type TokenStoreHarness,
     alanGrant,
     buildSingleEntryStore,
-} from '../test-support/accounts.js'
-import { buildProgram, installConsoleLogSpy } from '../test-support/cli-harness.js'
+} from '../testing/accounts.js'
 import { attachStatusCommand } from './status.js'
 import type { TokenStore } from './types.js'
 
@@ -43,7 +43,7 @@ function build(
 }
 
 describe('attachStatusCommand', () => {
-    const logSpy = installConsoleLogSpy()
+    const logSpy = installCapturedConsole()
 
     it('emits renderText output in plain mode', async () => {
         const { program, renderText } = build()

src/auth/token-view.test.ts

@@ -1,13 +1,13 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { CliError } from '../errors.js'
+import { buildProgram, installCapturedStream } from '../test-support/cli-harness.js'
 import {
     type TestAccount as Account,
     type TokenStoreHarness,
     alanGrant,
     buildSingleEntryStore,
-} from '../test-support/accounts.js'
-import { buildProgram, installStdoutSpy } from '../test-support/cli-harness.js'
+} from '../testing/accounts.js'
 import { attachTokenViewCommand } from './token-view.js'
 
 const account = alanGrant
@@ -19,7 +19,7 @@ function buildStore(
 }
 
 describe('attachTokenViewCommand', () => {
-    const stdoutSpy = installStdoutSpy()
+    const stdoutSpy = installCapturedStream()
 
     afterEach(() => {
         vi.unstubAllEnvs()