aico-cli 2.1.7 → 2.1.23

package/templates/skills/vitest/references/core-describe.md

@@ -0,0 +1,193 @@
+---
+name: describe-api
+description: describe/suite for grouping tests into logical blocks
+---
+
+# Describe API
+
+Group related tests into suites for organization and shared setup.
+
+## Basic Usage
+
+```ts
+import { describe, expect, test } from 'vitest'
+
+describe('Math', () => {
+  test('adds numbers', () => {
+    expect(1 + 1).toBe(2)
+  })
+
+  test('subtracts numbers', () => {
+    expect(3 - 1).toBe(2)
+  })
+})
+
+// Alias: suite
+import { suite } from 'vitest'
+suite('equivalent to describe', () => {})
+```
+
+## Nested Suites
+
+```ts
+describe('User', () => {
+  describe('when logged in', () => {
+    test('shows dashboard', () => {})
+    test('can update profile', () => {})
+  })
+
+  describe('when logged out', () => {
+    test('shows login page', () => {})
+  })
+})
+```
+
+## Suite Options
+
+```ts
+// All tests inherit options
+describe('slow tests', { timeout: 30_000 }, () => {
+  test('test 1', () => {}) // 30s timeout
+  test('test 2', () => {}) // 30s timeout
+})
+```
+
+## Suite Modifiers
+
+### Skip Suites
+
+```ts
+describe.skip('skipped suite', () => {
+  test('wont run', () => {})
+})
+
+// Conditional
+describe.skipIf(process.env.CI)('not in CI', () => {})
+describe.runIf(!process.env.CI)('only local', () => {})
+```
+
+### Focus Suites
+
+```ts
+describe.only('only this suite runs', () => {
+  test('runs', () => {})
+})
+```
+
+### Todo Suites
+
+```ts
+describe.todo('implement later')
+```
+
+### Concurrent Suites
+
+```ts
+// All tests run in parallel
+describe.concurrent('parallel tests', () => {
+  test('test 1', async ({ expect }) => {})
+  test('test 2', async ({ expect }) => {})
+})
+```
+
+### Sequential in Concurrent
+
+```ts
+describe.concurrent('parallel', () => {
+  test('concurrent 1', async () => {})
+  
+  describe.sequential('must be sequential', () => {
+    test('step 1', async () => {})
+    test('step 2', async () => {})
+  })
+})
+```
+
+### Shuffle Tests
+
+```ts
+describe.shuffle('random order', () => {
+  test('test 1', () => {})
+  test('test 2', () => {})
+  test('test 3', () => {})
+})
+
+// Or with option
+describe('random', { shuffle: true }, () => {})
+```
+
+## Parameterized Suites
+
+### describe.each
+
+```ts
+describe.each([
+  { name: 'Chrome', version: 100 },
+  { name: 'Firefox', version: 90 },
+])('$name browser', ({ name, version }) => {
+  test('has version', () => {
+    expect(version).toBeGreaterThan(0)
+  })
+})
+```
+
+### describe.for
+
+```ts
+describe.for([
+  ['Chrome', 100],
+  ['Firefox', 90],
+])('%s browser', ([name, version]) => {
+  test('has version', () => {
+    expect(version).toBeGreaterThan(0)
+  })
+})
+```
+
+## Hooks in Suites
+
+```ts
+describe('Database', () => {
+  let db
+
+  beforeAll(async () => {
+    db = await createDb()
+  })
+
+  afterAll(async () => {
+    await db.close()
+  })
+
+  beforeEach(async () => {
+    await db.clear()
+  })
+
+  test('insert works', async () => {
+    await db.insert({ name: 'test' })
+    expect(await db.count()).toBe(1)
+  })
+})
+```
+
+## Modifier Combinations
+
+All modifiers can be chained:
+
+```ts
+describe.skip.concurrent('skipped concurrent', () => {})
+describe.only.shuffle('only and shuffled', () => {})
+describe.concurrent.skip('equivalent', () => {})
+```
+
+## Key Points
+
+- Top-level tests belong to an implicit file suite
+- Nested suites inherit parent's options (timeout, retry, etc.)
+- Hooks are scoped to their suite and nested suites
+- Use `describe.concurrent` with context's `expect` for snapshots
+- Shuffle order depends on `sequence.seed` config
+
+<!-- 
+Source references:
+- https://vitest.dev/api/describe.html
+-->

package/templates/skills/vitest/references/core-expect.md

@@ -0,0 +1,219 @@
+---
+name: expect-api
+description: Assertions with matchers, asymmetric matchers, and custom matchers
+---
+
+# Expect API
+
+Vitest uses Chai assertions with Jest-compatible API.
+
+## Basic Assertions
+
+```ts
+import { expect, test } from 'vitest'
+
+test('assertions', () => {
+  // Equality
+  expect(1 + 1).toBe(2)              // Strict equality (===)
+  expect({ a: 1 }).toEqual({ a: 1 }) // Deep equality
+
+  // Truthiness
+  expect(true).toBeTruthy()
+  expect(false).toBeFalsy()
+  expect(null).toBeNull()
+  expect(undefined).toBeUndefined()
+  expect('value').toBeDefined()
+
+  // Numbers
+  expect(10).toBeGreaterThan(5)
+  expect(10).toBeGreaterThanOrEqual(10)
+  expect(5).toBeLessThan(10)
+  expect(0.1 + 0.2).toBeCloseTo(0.3, 5)
+
+  // Strings
+  expect('hello world').toMatch(/world/)
+  expect('hello').toContain('ell')
+
+  // Arrays
+  expect([1, 2, 3]).toContain(2)
+  expect([{ a: 1 }]).toContainEqual({ a: 1 })
+  expect([1, 2, 3]).toHaveLength(3)
+
+  // Objects
+  expect({ a: 1, b: 2 }).toHaveProperty('a')
+  expect({ a: 1, b: 2 }).toHaveProperty('a', 1)
+  expect({ a: { b: 1 } }).toHaveProperty('a.b', 1)
+  expect({ a: 1 }).toMatchObject({ a: 1 })
+
+  // Types
+  expect('string').toBeTypeOf('string')
+  expect(new Date()).toBeInstanceOf(Date)
+})
+```
+
+## Negation
+
+```ts
+expect(1).not.toBe(2)
+expect({ a: 1 }).not.toEqual({ a: 2 })
+```
+
+## Error Assertions
+
+```ts
+// Sync errors - wrap in function
+expect(() => throwError()).toThrow()
+expect(() => throwError()).toThrow('message')
+expect(() => throwError()).toThrow(/pattern/)
+expect(() => throwError()).toThrow(CustomError)
+
+// Async errors - use rejects
+await expect(asyncThrow()).rejects.toThrow('error')
+```
+
+## Promise Assertions
+
+```ts
+// Resolves
+await expect(Promise.resolve(1)).resolves.toBe(1)
+await expect(fetchData()).resolves.toEqual({ data: true })
+
+// Rejects
+await expect(Promise.reject('error')).rejects.toBe('error')
+await expect(failingFetch()).rejects.toThrow()
+```
+
+## Spy/Mock Assertions
+
+```ts
+const fn = vi.fn()
+fn('arg1', 'arg2')
+fn('arg3')
+
+expect(fn).toHaveBeenCalled()
+expect(fn).toHaveBeenCalledTimes(2)
+expect(fn).toHaveBeenCalledWith('arg1', 'arg2')
+expect(fn).toHaveBeenLastCalledWith('arg3')
+expect(fn).toHaveBeenNthCalledWith(1, 'arg1', 'arg2')
+
+expect(fn).toHaveReturned()
+expect(fn).toHaveReturnedWith(value)
+```
+
+## Asymmetric Matchers
+
+Use inside `toEqual`, `toHaveBeenCalledWith`, etc:
+
+```ts
+expect({ id: 1, name: 'test' }).toEqual({
+  id: expect.any(Number),
+  name: expect.any(String),
+})
+
+expect({ a: 1, b: 2, c: 3 }).toEqual(
+  expect.objectContaining({ a: 1 })
+)
+
+expect([1, 2, 3, 4]).toEqual(
+  expect.arrayContaining([1, 3])
+)
+
+expect('hello world').toEqual(
+  expect.stringContaining('world')
+)
+
+expect('hello world').toEqual(
+  expect.stringMatching(/world$/)
+)
+
+expect({ value: null }).toEqual({
+  value: expect.anything() // Matches anything except null/undefined
+})
+
+// Negate with expect.not
+expect([1, 2]).toEqual(
+  expect.not.arrayContaining([3])
+)
+```
+
+## Soft Assertions
+
+Continue test after failure:
+
+```ts
+expect.soft(1).toBe(2) // Marks test failed but continues
+expect.soft(2).toBe(3) // Also runs
+// All failures reported at end
+```
+
+## Poll Assertions
+
+Retry until passes:
+
+```ts
+await expect.poll(() => fetchStatus()).toBe('ready')
+
+await expect.poll(
+  () => document.querySelector('.element'),
+  { interval: 100, timeout: 5000 }
+).toBeTruthy()
+```
+
+## Assertion Count
+
+```ts
+test('async assertions', async () => {
+  expect.assertions(2) // Exactly 2 assertions must run
+  
+  await doAsync((data) => {
+    expect(data).toBeDefined()
+    expect(data.id).toBe(1)
+  })
+})
+
+test('at least one', () => {
+  expect.hasAssertions() // At least 1 assertion must run
+})
+```
+
+## Extending Matchers
+
+```ts
+expect.extend({
+  toBeWithinRange(received, floor, ceiling) {
+    const pass = received >= floor && received <= ceiling
+    return {
+      pass,
+      message: () => 
+        `expected ${received} to be within range ${floor} - ${ceiling}`,
+    }
+  },
+})
+
+test('custom matcher', () => {
+  expect(100).toBeWithinRange(90, 110)
+})
+```
+
+## Snapshot Assertions
+
+```ts
+expect(data).toMatchSnapshot()
+expect(data).toMatchInlineSnapshot(`{ "id": 1 }`)
+await expect(result).toMatchFileSnapshot('./expected.json')
+
+expect(() => throw new Error('fail')).toThrowErrorMatchingSnapshot()
+```
+
+## Key Points
+
+- Use `toBe` for primitives, `toEqual` for objects/arrays
+- `toStrictEqual` checks undefined properties and array sparseness
+- Always `await` async assertions (`resolves`, `rejects`, `poll`)
+- Use context's `expect` in concurrent tests for correct tracking
+- `toThrow` requires wrapping sync code in a function
+
+<!-- 
+Source references:
+- https://vitest.dev/api/expect.html
+-->

package/templates/skills/vitest/references/core-hooks.md

@@ -0,0 +1,244 @@
+---
+name: lifecycle-hooks
+description: beforeEach, afterEach, beforeAll, afterAll, and around hooks
+---
+
+# Lifecycle Hooks
+
+## Basic Hooks
+
+```ts
+import { afterAll, afterEach, beforeAll, beforeEach, test } from 'vitest'
+
+beforeAll(async () => {
+  // Runs once before all tests in file/suite
+  await setupDatabase()
+})
+
+afterAll(async () => {
+  // Runs once after all tests in file/suite
+  await teardownDatabase()
+})
+
+beforeEach(async () => {
+  // Runs before each test
+  await clearTestData()
+})
+
+afterEach(async () => {
+  // Runs after each test
+  await cleanupMocks()
+})
+```
+
+## Cleanup Return Pattern
+
+Return cleanup function from `before*` hooks:
+
+```ts
+beforeAll(async () => {
+  const server = await startServer()
+  
+  // Returned function runs as afterAll
+  return async () => {
+    await server.close()
+  }
+})
+
+beforeEach(async () => {
+  const connection = await connect()
+  
+  // Runs as afterEach
+  return () => connection.close()
+})
+```
+
+## Scoped Hooks
+
+Hooks apply to current suite and nested suites:
+
+```ts
+describe('outer', () => {
+  beforeEach(() => console.log('outer before'))
+  
+  test('test 1', () => {}) // outer before → test
+  
+  describe('inner', () => {
+    beforeEach(() => console.log('inner before'))
+    
+    test('test 2', () => {}) // outer before → inner before → test
+  })
+})
+```
+
+## Hook Timeout
+
+```ts
+beforeAll(async () => {
+  await slowSetup()
+}, 30_000) // 30 second timeout
+```
+
+## Around Hooks
+
+Wrap tests with setup/teardown context:
+
+```ts
+import { aroundEach, test } from 'vitest'
+
+// Wrap each test in database transaction
+aroundEach(async (runTest) => {
+  await db.beginTransaction()
+  await runTest() // Must be called!
+  await db.rollback()
+})
+
+test('insert user', async () => {
+  await db.insert({ name: 'Alice' })
+  // Automatically rolled back after test
+})
+```
+
+### aroundAll
+
+Wrap entire suite:
+
+```ts
+import { aroundAll, test } from 'vitest'
+
+aroundAll(async (runSuite) => {
+  console.log('before all tests')
+  await runSuite() // Must be called!
+  console.log('after all tests')
+})
+```
+
+### Multiple Around Hooks
+
+Nested like onion layers:
+
+```ts
+aroundEach(async (runTest) => {
+  console.log('outer before')
+  await runTest()
+  console.log('outer after')
+})
+
+aroundEach(async (runTest) => {
+  console.log('inner before')
+  await runTest()
+  console.log('inner after')
+})
+
+// Order: outer before → inner before → test → inner after → outer after
+```
+
+## Test Hooks
+
+Inside test body:
+
+```ts
+import { onTestFailed, onTestFinished, test } from 'vitest'
+
+test('with cleanup', () => {
+  const db = connect()
+  
+  // Runs after test finishes (pass or fail)
+  onTestFinished(() => db.close())
+  
+  // Only runs if test fails
+  onTestFailed(({ task }) => {
+    console.log('Failed:', task.result?.errors)
+  })
+  
+  db.query('SELECT * FROM users')
+})
+```
+
+### Reusable Cleanup Pattern
+
+```ts
+function useTestDb() {
+  const db = connect()
+  onTestFinished(() => db.close())
+  return db
+}
+
+test('query users', () => {
+  const db = useTestDb()
+  expect(db.query('SELECT * FROM users')).toBeDefined()
+})
+
+test('query orders', () => {
+  const db = useTestDb() // Fresh connection, auto-closed
+  expect(db.query('SELECT * FROM orders')).toBeDefined()
+})
+```
+
+## Concurrent Test Hooks
+
+For concurrent tests, use context's hooks:
+
+```ts
+test.concurrent('concurrent', ({ onTestFinished }) => {
+  const resource = allocate()
+  onTestFinished(() => resource.release())
+})
+```
+
+## Extended Test Hooks
+
+With `test.extend`, hooks are type-aware:
+
+```ts
+const test = base.extend<{ db: Database }>({
+  db: async ({}, use) => {
+    const db = await createDb()
+    await use(db)
+    await db.close()
+  },
+})
+
+// These hooks know about `db` fixture
+test.beforeEach(({ db }) => {
+  db.seed()
+})
+
+test.afterEach(({ db }) => {
+  db.clear()
+})
+```
+
+## Hook Execution Order
+
+Default order (stack):
+1. `beforeAll` (in order)
+2. `beforeEach` (in order)
+3. Test
+4. `afterEach` (reverse order)
+5. `afterAll` (reverse order)
+
+Configure with `sequence.hooks`:
+
+```ts
+defineConfig({
+  test: {
+    sequence: {
+      hooks: 'list', // 'stack' (default), 'list', 'parallel'
+    },
+  },
+})
+```
+
+## Key Points
+
+- Hooks are not called during type checking
+- Return cleanup function from `before*` to avoid `after*` duplication
+- `aroundEach`/`aroundAll` must call `runTest()`/`runSuite()`
+- `onTestFinished` always runs, even if test fails
+- Use context hooks for concurrent tests
+
+<!-- 
+Source references:
+- https://vitest.dev/api/hooks.html
+-->