@dfosco/storyboard-core 3.1.2 → 3.3.0

package/scaffold/skills/vitest/references/advanced-type-testing.md

@@ -0,0 +1,237 @@
+---
+name: type-testing
+description: Test TypeScript types with expectTypeOf and assertType
+---
+
+# Type Testing
+
+Test TypeScript types without runtime execution.
+
+## Setup
+
+Type tests use `.test-d.ts` extension:
+
+```ts
+// math.test-d.ts
+import { expectTypeOf } from 'vitest'
+import { add } from './math'
+
+test('add returns number', () => {
+  expectTypeOf(add).returns.toBeNumber()
+})
+```
+
+## Configuration
+
+```ts
+defineConfig({
+  test: {
+    typecheck: {
+      enabled: true,
+      
+      // Only type check
+      only: false,
+      
+      // Checker: 'tsc' or 'vue-tsc'
+      checker: 'tsc',
+      
+      // Include patterns
+      include: ['**/*.test-d.ts'],
+      
+      // tsconfig to use
+      tsconfig: './tsconfig.json',
+    },
+  },
+})
+```
+
+## expectTypeOf API
+
+```ts
+import { expectTypeOf } from 'vitest'
+
+// Basic type checks
+expectTypeOf<string>().toBeString()
+expectTypeOf<number>().toBeNumber()
+expectTypeOf<boolean>().toBeBoolean()
+expectTypeOf<null>().toBeNull()
+expectTypeOf<undefined>().toBeUndefined()
+expectTypeOf<void>().toBeVoid()
+expectTypeOf<never>().toBeNever()
+expectTypeOf<any>().toBeAny()
+expectTypeOf<unknown>().toBeUnknown()
+expectTypeOf<object>().toBeObject()
+expectTypeOf<Function>().toBeFunction()
+expectTypeOf<[]>().toBeArray()
+expectTypeOf<symbol>().toBeSymbol()
+```
+
+## Value Type Checking
+
+```ts
+const value = 'hello'
+expectTypeOf(value).toBeString()
+
+const obj = { name: 'test', count: 42 }
+expectTypeOf(obj).toMatchTypeOf<{ name: string }>()
+expectTypeOf(obj).toHaveProperty('name')
+```
+
+## Function Types
+
+```ts
+function greet(name: string): string {
+  return `Hello, ${name}`
+}
+
+expectTypeOf(greet).toBeFunction()
+expectTypeOf(greet).parameters.toEqualTypeOf<[string]>()
+expectTypeOf(greet).returns.toBeString()
+
+// Parameter checking
+expectTypeOf(greet).parameter(0).toBeString()
+```
+
+## Object Types
+
+```ts
+interface User {
+  id: number
+  name: string
+  email?: string
+}
+
+expectTypeOf<User>().toHaveProperty('id')
+expectTypeOf<User>().toHaveProperty('name').toBeString()
+
+// Check shape
+expectTypeOf({ id: 1, name: 'test' }).toMatchTypeOf<User>()
+```
+
+## Equality vs Matching
+
+```ts
+interface A { x: number }
+interface B { x: number; y: string }
+
+// toMatchTypeOf - subset matching
+expectTypeOf<B>().toMatchTypeOf<A>()  // B extends A
+
+// toEqualTypeOf - exact match
+expectTypeOf<A>().not.toEqualTypeOf<B>()  // Not exact match
+expectTypeOf<A>().toEqualTypeOf<{ x: number }>()  // Exact match
+```
+
+## Branded Types
+
+```ts
+type UserId = number & { __brand: 'UserId' }
+type PostId = number & { __brand: 'PostId' }
+
+expectTypeOf<UserId>().not.toEqualTypeOf<PostId>()
+expectTypeOf<UserId>().not.toEqualTypeOf<number>()
+```
+
+## Generic Types
+
+```ts
+function identity<T>(value: T): T {
+  return value
+}
+
+expectTypeOf(identity<string>).returns.toBeString()
+expectTypeOf(identity<number>).returns.toBeNumber()
+```
+
+## Nullable Types
+
+```ts
+type MaybeString = string | null | undefined
+
+expectTypeOf<MaybeString>().toBeNullable()
+expectTypeOf<string>().not.toBeNullable()
+```
+
+## assertType
+
+Assert a value matches a type (no assertion at runtime):
+
+```ts
+import { assertType } from 'vitest'
+
+function getUser(): User | null {
+  return { id: 1, name: 'test' }
+}
+
+test('returns user', () => {
+  const result = getUser()
+  
+  // @ts-expect-error - should fail type check
+  assertType<string>(result)
+  
+  // Correct type
+  assertType<User | null>(result)
+})
+```
+
+## Using @ts-expect-error
+
+Test that code produces type error:
+
+```ts
+test('rejects wrong types', () => {
+  function requireString(s: string) {}
+  
+  // @ts-expect-error - number not assignable to string
+  requireString(123)
+})
+```
+
+## Running Type Tests
+
+```bash
+# Run type tests
+vitest typecheck
+
+# Run alongside unit tests
+vitest --typecheck
+
+# Type tests only
+vitest --typecheck.only
+```
+
+## Mixed Test Files
+
+Combine runtime and type tests:
+
+```ts
+// user.test.ts
+import { describe, expect, expectTypeOf, test } from 'vitest'
+import { createUser } from './user'
+
+describe('createUser', () => {
+  test('runtime: creates user', () => {
+    const user = createUser('John')
+    expect(user.name).toBe('John')
+  })
+
+  test('types: returns User type', () => {
+    expectTypeOf(createUser).returns.toMatchTypeOf<{ name: string }>()
+  })
+})
+```
+
+## Key Points
+
+- Use `.test-d.ts` for type-only tests
+- `expectTypeOf` for type assertions
+- `toMatchTypeOf` for subset matching
+- `toEqualTypeOf` for exact type matching
+- Use `@ts-expect-error` to test type errors
+- Run with `vitest typecheck` or `--typecheck`
+
+<!-- 
+Source references:
+- https://vitest.dev/guide/testing-types.html
+- https://vitest.dev/api/expect-typeof.html
+-->

package/scaffold/skills/vitest/references/advanced-vi.md

@@ -0,0 +1,249 @@
+---
+name: vi-utilities
+description: vi helper for mocking, timers, utilities
+---
+
+# Vi Utilities
+
+The `vi` helper provides mocking and utility functions.
+
+```ts
+import { vi } from 'vitest'
+```
+
+## Mock Functions
+
+```ts
+// Create mock
+const fn = vi.fn()
+const fnWithImpl = vi.fn((x) => x * 2)
+
+// Check if mock
+vi.isMockFunction(fn) // true
+
+// Mock methods
+fn.mockReturnValue(42)
+fn.mockReturnValueOnce(1)
+fn.mockResolvedValue(data)
+fn.mockRejectedValue(error)
+fn.mockImplementation(() => 'result')
+fn.mockImplementationOnce(() => 'once')
+
+// Clear/reset
+fn.mockClear()    // Clear call history
+fn.mockReset()    // Clear history + implementation
+fn.mockRestore()  // Restore original (for spies)
+```
+
+## Spying
+
+```ts
+const obj = { method: () => 'original' }
+
+const spy = vi.spyOn(obj, 'method')
+obj.method()
+
+expect(spy).toHaveBeenCalled()
+
+// Mock implementation
+spy.mockReturnValue('mocked')
+
+// Spy on getter/setter
+vi.spyOn(obj, 'prop', 'get').mockReturnValue('value')
+```
+
+## Module Mocking
+
+```ts
+// Hoisted to top of file
+vi.mock('./module', () => ({
+  fn: vi.fn(),
+}))
+
+// Partial mock
+vi.mock('./module', async (importOriginal) => ({
+  ...(await importOriginal()),
+  specificFn: vi.fn(),
+}))
+
+// Spy mode - keep implementation
+vi.mock('./module', { spy: true })
+
+// Import actual module inside mock
+const actual = await vi.importActual('./module')
+
+// Import as mock
+const mocked = await vi.importMock('./module')
+```
+
+## Dynamic Mocking
+
+```ts
+// Not hoisted - use with dynamic imports
+vi.doMock('./config', () => ({ key: 'value' }))
+const config = await import('./config')
+
+// Unmock
+vi.doUnmock('./config')
+vi.unmock('./module') // Hoisted
+```
+
+## Reset Modules
+
+```ts
+// Clear module cache
+vi.resetModules()
+
+// Wait for dynamic imports
+await vi.dynamicImportSettled()
+```
+
+## Fake Timers
+
+```ts
+vi.useFakeTimers()
+
+setTimeout(() => console.log('done'), 1000)
+
+// Advance time
+vi.advanceTimersByTime(1000)
+vi.advanceTimersByTimeAsync(1000)  // For async callbacks
+vi.advanceTimersToNextTimer()
+vi.advanceTimersToNextFrame()      // requestAnimationFrame
+
+// Run all timers
+vi.runAllTimers()
+vi.runAllTimersAsync()
+vi.runOnlyPendingTimers()
+
+// Clear timers
+vi.clearAllTimers()
+
+// Check state
+vi.getTimerCount()
+vi.isFakeTimers()
+
+// Restore
+vi.useRealTimers()
+```
+
+## Mock Date/Time
+
+```ts
+vi.setSystemTime(new Date('2024-01-01'))
+expect(new Date().getFullYear()).toBe(2024)
+
+vi.getMockedSystemTime()  // Get mocked date
+vi.getRealSystemTime()    // Get real time (ms)
+```
+
+## Global/Env Mocking
+
+```ts
+// Stub global
+vi.stubGlobal('fetch', vi.fn())
+vi.unstubAllGlobals()
+
+// Stub environment
+vi.stubEnv('API_KEY', 'test')
+vi.stubEnv('NODE_ENV', 'test')
+vi.unstubAllEnvs()
+```
+
+## Hoisted Code
+
+Run code before imports:
+
+```ts
+const mock = vi.hoisted(() => vi.fn())
+
+vi.mock('./module', () => ({
+  fn: mock, // Can reference hoisted variable
+}))
+```
+
+## Waiting Utilities
+
+```ts
+// Wait for callback to succeed
+await vi.waitFor(async () => {
+  const el = document.querySelector('.loaded')
+  expect(el).toBeTruthy()
+}, { timeout: 5000, interval: 100 })
+
+// Wait for truthy value
+const element = await vi.waitUntil(
+  () => document.querySelector('.loaded'),
+  { timeout: 5000 }
+)
+```
+
+## Mock Object
+
+Mock all methods of an object:
+
+```ts
+const original = {
+  method: () => 'real',
+  nested: { fn: () => 'nested' },
+}
+
+const mocked = vi.mockObject(original)
+mocked.method()  // undefined (mocked)
+mocked.method.mockReturnValue('mocked')
+
+// Spy mode
+const spied = vi.mockObject(original, { spy: true })
+spied.method()  // 'real'
+expect(spied.method).toHaveBeenCalled()
+```
+
+## Test Configuration
+
+```ts
+vi.setConfig({
+  testTimeout: 10_000,
+  hookTimeout: 10_000,
+})
+
+vi.resetConfig()
+```
+
+## Global Mock Management
+
+```ts
+vi.clearAllMocks()   // Clear all mock call history
+vi.resetAllMocks()   // Reset + clear implementation
+vi.restoreAllMocks() // Restore originals (spies)
+```
+
+## vi.mocked Type Helper
+
+TypeScript helper for mocked values:
+
+```ts
+import { myFn } from './module'
+vi.mock('./module')
+
+// Type as mock
+vi.mocked(myFn).mockReturnValue('typed')
+
+// Deep mocking
+vi.mocked(myModule, { deep: true })
+
+// Partial mock typing
+vi.mocked(fn, { partial: true }).mockResolvedValue({ ok: true })
+```
+
+## Key Points
+
+- `vi.mock` is hoisted - use `vi.doMock` for dynamic mocking
+- `vi.hoisted` lets you reference variables in mock factories
+- Use `vi.spyOn` to spy on existing methods
+- Fake timers require explicit setup and teardown
+- `vi.waitFor` retries until assertion passes
+
+<!-- 
+Source references:
+- https://vitest.dev/api/vi.html
+-->

package/scaffold/skills/vitest/references/core-cli.md

@@ -0,0 +1,166 @@
+---
+name: vitest-cli
+description: Command line interface commands and options
+---
+
+# Command Line Interface
+
+## Commands
+
+### `vitest`
+
+Start Vitest in watch mode (dev) or run mode (CI):
+
+```bash
+vitest                    # Watch mode in dev, run mode in CI
+vitest foobar             # Run tests containing "foobar" in path
+vitest basic/foo.test.ts:10  # Run specific test by file and line number
+```
+
+### `vitest run`
+
+Run tests once without watch mode:
+
+```bash
+vitest run
+vitest run --coverage
+```
+
+### `vitest watch`
+
+Explicitly start watch mode:
+
+```bash
+vitest watch
+```
+
+### `vitest related`
+
+Run tests that import specific files (useful with lint-staged):
+
+```bash
+vitest related src/index.ts src/utils.ts --run
+```
+
+### `vitest bench`
+
+Run only benchmark tests:
+
+```bash
+vitest bench
+```
+
+### `vitest list`
+
+List all matching tests without running them:
+
+```bash
+vitest list                    # List test names
+vitest list --json             # Output as JSON
+vitest list --filesOnly        # List only test files
+```
+
+### `vitest init`
+
+Initialize project setup:
+
+```bash
+vitest init browser            # Set up browser testing
+```
+
+## Common Options
+
+```bash
+# Configuration
+--config <path>           # Path to config file
+--project <name>          # Run specific project
+
+# Filtering
+--testNamePattern, -t     # Run tests matching pattern
+--changed                 # Run tests for changed files
+--changed HEAD~1          # Tests for last commit changes
+
+# Reporters
+--reporter <name>         # default, verbose, dot, json, html
+--reporter=html --outputFile=report.html
+
+# Coverage
+--coverage                # Enable coverage
+--coverage.provider v8    # Use v8 provider
+--coverage.reporter text,html
+
+# Execution
+--shard <index>/<count>   # Split tests across machines
+--bail <n>                # Stop after n failures
+--retry <n>               # Retry failed tests n times
+--sequence.shuffle        # Randomize test order
+
+# Watch mode
+--no-watch                # Disable watch mode
+--standalone              # Start without running tests
+
+# Environment
+--environment <env>       # jsdom, happy-dom, node
+--globals                 # Enable global APIs
+
+# Debugging
+--inspect                 # Enable Node inspector
+--inspect-brk             # Break on start
+
+# Output
+--silent                  # Suppress console output
+--no-color                # Disable colors
+```
+
+## Package.json Scripts
+
+```json
+{
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:ui": "vitest --ui",
+    "coverage": "vitest run --coverage"
+  }
+}
+```
+
+## Sharding for CI
+
+Split tests across multiple machines:
+
+```bash
+# Machine 1
+vitest run --shard=1/3 --reporter=blob
+
+# Machine 2
+vitest run --shard=2/3 --reporter=blob
+
+# Machine 3
+vitest run --shard=3/3 --reporter=blob
+
+# Merge reports
+vitest --merge-reports --reporter=junit
+```
+
+## Watch Mode Keyboard Shortcuts
+
+In watch mode, press:
+- `a` - Run all tests
+- `f` - Run only failed tests
+- `u` - Update snapshots
+- `p` - Filter by filename pattern
+- `t` - Filter by test name pattern
+- `q` - Quit
+
+## Key Points
+
+- Watch mode is default in dev, run mode in CI (when `process.env.CI` is set)
+- Use `--run` flag to ensure single run (important for lint-staged)
+- Both camelCase (`--testTimeout`) and kebab-case (`--test-timeout`) work
+- Boolean options can be negated with `--no-` prefix
+
+<!-- 
+Source references:
+- https://vitest.dev/guide/cli.html
+-->