skillshop 2.0.0 → 2.1.0

package/skills-content/vitest/references/core-test-api.md

@@ -0,0 +1,233 @@
+---
+name: test-api
+description: test/it function for defining tests with modifiers
+---
+
+# Test API
+
+## Basic Test
+
+```ts
+import { expect, test } from 'vitest'
+
+test('adds numbers', () => {
+  expect(1 + 1).toBe(2)
+})
+
+// Alias: it
+import { it } from 'vitest'
+
+it('works the same', () => {
+  expect(true).toBe(true)
+})
+```
+
+## Async Tests
+
+```ts
+test('async test', async () => {
+  const result = await fetchData()
+  expect(result).toBeDefined()
+})
+
+// Promises are automatically awaited
+test('returns promise', () => {
+  return fetchData().then(result => {
+    expect(result).toBeDefined()
+  })
+})
+```
+
+## Test Options
+
+```ts
+// Timeout (default: 5000ms)
+test('slow test', async () => {
+  // ...
+}, 10_000)
+
+// Or with options object
+test('with options', { timeout: 10_000, retry: 2 }, async () => {
+  // ...
+})
+```
+
+## Test Modifiers
+
+### Skip Tests
+
+```ts
+test.skip('skipped test', () => {
+  // Won't run
+})
+
+// Conditional skip
+test.skipIf(process.env.CI)('not in CI', () => {})
+test.runIf(process.env.CI)('only in CI', () => {})
+
+// Dynamic skip via context
+test('dynamic skip', ({ skip }) => {
+  skip(someCondition, 'reason')
+  // ...
+})
+```
+
+### Focus Tests
+
+```ts
+test.only('only this runs', () => {
+  // Other tests in file are skipped
+})
+```
+
+### Todo Tests
+
+```ts
+test.todo('implement later')
+
+test.todo('with body', () => {
+  // Not run, shows in report
+})
+```
+
+### Failing Tests
+
+```ts
+test.fails('expected to fail', () => {
+  expect(1).toBe(2) // Test passes because assertion fails
+})
+```
+
+### Concurrent Tests
+
+```ts
+// Run tests in parallel
+test.concurrent('test 1', async ({ expect }) => {
+  // Use context.expect for concurrent tests
+  expect(await fetch1()).toBe('result')
+})
+
+test.concurrent('test 2', async ({ expect }) => {
+  expect(await fetch2()).toBe('result')
+})
+```
+
+### Sequential Tests
+
+```ts
+// Force sequential in concurrent context
+test.sequential('must run alone', async () => {})
+```
+
+## Parameterized Tests
+
+### test.each
+
+```ts
+test.each([
+  [1, 1, 2],
+  [1, 2, 3],
+  [2, 1, 3],
+])('add(%i, %i) = %i', (a, b, expected) => {
+  expect(a + b).toBe(expected)
+})
+
+// With objects
+test.each([
+  { a: 1, b: 1, expected: 2 },
+  { a: 1, b: 2, expected: 3 },
+])('add($a, $b) = $expected', ({ a, b, expected }) => {
+  expect(a + b).toBe(expected)
+})
+
+// Template literal
+test.each`
+  a    | b    | expected
+  ${1} | ${1} | ${2}
+  ${1} | ${2} | ${3}
+`('add($a, $b) = $expected', ({ a, b, expected }) => {
+  expect(a + b).toBe(expected)
+})
+```
+
+### test.for
+
+Preferred over `.each` - doesn't spread arrays:
+
+```ts
+test.for([
+  [1, 1, 2],
+  [1, 2, 3],
+])('add(%i, %i) = %i', ([a, b, expected], { expect }) => {
+  // Second arg is TestContext
+  expect(a + b).toBe(expected)
+})
+```
+
+## Test Context
+
+First argument provides context utilities:
+
+```ts
+test('with context', ({ expect, skip, task }) => {
+  console.log(task.name)   // Test name
+  skip(someCondition)      // Skip dynamically
+  expect(1).toBe(1)        // Context-bound expect
+})
+```
+
+## Custom Test with Fixtures
+
+```ts
+import { test as base } from 'vitest'
+
+const test = base.extend({
+  db: async ({}, use) => {
+    const db = await createDb()
+    await use(db)
+    await db.close()
+  },
+})
+
+test('query', async ({ db }) => {
+  const users = await db.query('SELECT * FROM users')
+  expect(users).toBeDefined()
+})
+```
+
+## Retry Configuration
+
+```ts
+test('flaky test', { retry: 3 }, async () => {
+  // Retries up to 3 times on failure
+})
+
+// Advanced retry options
+test('with delay', {
+  retry: {
+    count: 3,
+    delay: 1000,
+    condition: /timeout/i, // Only retry on timeout errors
+  },
+}, async () => {})
+```
+
+## Tags
+
+```ts
+test('database test', { tags: ['db', 'slow'] }, async () => {})
+
+// Run with: vitest --tags db
+```
+
+## Key Points
+
+- Tests with no body are marked as `todo`
+- `test.only` throws in CI unless `allowOnly: true`
+- Use context's `expect` for concurrent tests and snapshots
+- Function name is used as test name if passed as first arg
+
+<!-- 
+Source references:
+- https://vitest.dev/api/test.html
+-->

package/skills-content/vitest/references/features-concurrency.md

@@ -0,0 +1,250 @@
+---
+name: concurrency-parallelism
+description: Concurrent tests, parallel execution, and sharding
+---
+
+# Concurrency & Parallelism
+
+## File Parallelism
+
+By default, Vitest runs test files in parallel across workers:
+
+```ts
+defineConfig({
+  test: {
+    // Run files in parallel (default: true)
+    fileParallelism: true,
+    
+    // Number of worker threads
+    maxWorkers: 4,
+    minWorkers: 1,
+    
+    // Pool type: 'threads', 'forks', 'vmThreads'
+    pool: 'threads',
+  },
+})
+```
+
+## Concurrent Tests
+
+Run tests within a file in parallel:
+
+```ts
+// Individual concurrent tests
+test.concurrent('test 1', async ({ expect }) => {
+  expect(await fetch1()).toBe('result')
+})
+
+test.concurrent('test 2', async ({ expect }) => {
+  expect(await fetch2()).toBe('result')
+})
+
+// All tests in suite concurrent
+describe.concurrent('parallel suite', () => {
+  test('test 1', async ({ expect }) => {})
+  test('test 2', async ({ expect }) => {})
+})
+```
+
+**Important:** Use `{ expect }` from context for concurrent tests.
+
+## Sequential in Concurrent Context
+
+Force sequential execution:
+
+```ts
+describe.concurrent('mostly parallel', () => {
+  test('parallel 1', async () => {})
+  test('parallel 2', async () => {})
+  
+  test.sequential('must run alone 1', async () => {})
+  test.sequential('must run alone 2', async () => {})
+})
+
+// Or entire suite
+describe.sequential('sequential suite', () => {
+  test('first', () => {})
+  test('second', () => {})
+})
+```
+
+## Max Concurrency
+
+Limit concurrent tests:
+
+```ts
+defineConfig({
+  test: {
+    maxConcurrency: 5, // Max concurrent tests per file
+  },
+})
+```
+
+## Isolation
+
+Each file runs in isolated environment by default:
+
+```ts
+defineConfig({
+  test: {
+    // Disable isolation for faster runs (less safe)
+    isolate: false,
+  },
+})
+```
+
+## Sharding
+
+Split tests across machines:
+
+```bash
+# Machine 1
+vitest run --shard=1/3
+
+# Machine 2
+vitest run --shard=2/3
+
+# Machine 3
+vitest run --shard=3/3
+```
+
+### CI Example (GitHub Actions)
+
+```yaml
+jobs:
+  test:
+    strategy:
+      matrix:
+        shard: [1, 2, 3]
+    steps:
+      - run: vitest run --shard=${{ matrix.shard }}/3 --reporter=blob
+      
+  merge:
+    needs: test
+    steps:
+      - run: vitest --merge-reports --reporter=junit
+```
+
+### Merge Reports
+
+```bash
+# Each shard outputs blob
+vitest run --shard=1/3 --reporter=blob --coverage
+vitest run --shard=2/3 --reporter=blob --coverage
+
+# Merge all blobs
+vitest --merge-reports --reporter=json --coverage
+```
+
+## Test Sequence
+
+Control test order:
+
+```ts
+defineConfig({
+  test: {
+    sequence: {
+      // Run tests in random order
+      shuffle: true,
+      
+      // Seed for reproducible shuffle
+      seed: 12345,
+      
+      // Hook execution order
+      hooks: 'stack', // 'stack', 'list', 'parallel'
+      
+      // All tests concurrent by default
+      concurrent: true,
+    },
+  },
+})
+```
+
+## Shuffle Tests
+
+Randomize to catch hidden dependencies:
+
+```ts
+// Via CLI
+vitest --sequence.shuffle
+
+// Per suite
+describe.shuffle('random order', () => {
+  test('test 1', () => {})
+  test('test 2', () => {})
+  test('test 3', () => {})
+})
+```
+
+## Pool Options
+
+### Threads (Default)
+
+```ts
+defineConfig({
+  test: {
+    pool: 'threads',
+    poolOptions: {
+      threads: {
+        maxThreads: 8,
+        minThreads: 2,
+        isolate: true,
+      },
+    },
+  },
+})
+```
+
+### Forks
+
+Better isolation, slower:
+
+```ts
+defineConfig({
+  test: {
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        maxForks: 4,
+        isolate: true,
+      },
+    },
+  },
+})
+```
+
+### VM Threads
+
+Full VM isolation per file:
+
+```ts
+defineConfig({
+  test: {
+    pool: 'vmThreads',
+  },
+})
+```
+
+## Bail on Failure
+
+Stop after first failure:
+
+```bash
+vitest --bail 1    # Stop after 1 failure
+vitest --bail      # Stop on first failure (same as --bail 1)
+```
+
+## Key Points
+
+- Files run in parallel by default
+- Use `.concurrent` for parallel tests within file
+- Always use context's `expect` in concurrent tests
+- Sharding splits tests across CI machines
+- Use `--merge-reports` to combine sharded results
+- Shuffle tests to find hidden dependencies
+
+<!-- 
+Source references:
+- https://vitest.dev/guide/features.html#running-tests-concurrently
+- https://vitest.dev/guide/improving-performance.html
+-->

package/skills-content/vitest/references/features-context.md

@@ -0,0 +1,238 @@
+---
+name: test-context-fixtures
+description: Test context, custom fixtures with test.extend
+---
+
+# Test Context & Fixtures
+
+## Built-in Context
+
+Every test receives context as first argument:
+
+```ts
+test('context', ({ task, expect, skip }) => {
+  console.log(task.name)  // Test name
+  expect(1).toBe(1)       // Context-bound expect
+  skip()                  // Skip test dynamically
+})
+```
+
+### Context Properties
+
+- `task` - Test metadata (name, file, etc.)
+- `expect` - Expect bound to this test (important for concurrent tests)
+- `skip(condition?, message?)` - Skip the test
+- `onTestFinished(fn)` - Cleanup after test
+- `onTestFailed(fn)` - Run on failure only
+
+## Custom Fixtures with test.extend
+
+Create reusable test utilities:
+
+```ts
+import { test as base } from 'vitest'
+
+// Define fixture types
+interface Fixtures {
+  db: Database
+  user: User
+}
+
+// Create extended test
+export const test = base.extend<Fixtures>({
+  // Fixture with setup/teardown
+  db: async ({}, use) => {
+    const db = await createDatabase()
+    await use(db)           // Provide to test
+    await db.close()        // Cleanup
+  },
+  
+  // Fixture depending on another fixture
+  user: async ({ db }, use) => {
+    const user = await db.createUser({ name: 'Test' })
+    await use(user)
+    await db.deleteUser(user.id)
+  },
+})
+```
+
+Using fixtures:
+
+```ts
+test('query user', async ({ db, user }) => {
+  const found = await db.findUser(user.id)
+  expect(found).toEqual(user)
+})
+```
+
+## Fixture Initialization
+
+Fixtures only initialize when accessed:
+
+```ts
+const test = base.extend({
+  expensive: async ({}, use) => {
+    console.log('initializing')  // Only runs if test uses it
+    await use('value')
+  },
+})
+
+test('no fixture', () => {})           // expensive not called
+test('uses fixture', ({ expensive }) => {}) // expensive called
+```
+
+## Auto Fixtures
+
+Run fixture for every test:
+
+```ts
+const test = base.extend({
+  setup: [
+    async ({}, use) => {
+      await globalSetup()
+      await use()
+      await globalTeardown()
+    },
+    { auto: true }  // Always run
+  ],
+})
+```
+
+## Scoped Fixtures
+
+### File Scope
+
+Initialize once per file:
+
+```ts
+const test = base.extend({
+  connection: [
+    async ({}, use) => {
+      const conn = await connect()
+      await use(conn)
+      await conn.close()
+    },
+    { scope: 'file' }
+  ],
+})
+```
+
+### Worker Scope
+
+Initialize once per worker:
+
+```ts
+const test = base.extend({
+  sharedResource: [
+    async ({}, use) => {
+      await use(globalResource)
+    },
+    { scope: 'worker' }
+  ],
+})
+```
+
+## Injected Fixtures (from Config)
+
+Override fixtures per project:
+
+```ts
+// test file
+const test = base.extend({
+  apiUrl: ['/default', { injected: true }],
+})
+
+// vitest.config.ts
+defineConfig({
+  test: {
+    projects: [
+      {
+        test: {
+          name: 'prod',
+          provide: { apiUrl: 'https://api.prod.com' },
+        },
+      },
+    ],
+  },
+})
+```
+
+## Scoped Values per Suite
+
+Override fixture for specific suite:
+
+```ts
+const test = base.extend({
+  environment: 'development',
+})
+
+describe('production tests', () => {
+  test.scoped({ environment: 'production' })
+  
+  test('uses production', ({ environment }) => {
+    expect(environment).toBe('production')
+  })
+})
+
+test('uses default', ({ environment }) => {
+  expect(environment).toBe('development')
+})
+```
+
+## Extended Test Hooks
+
+Type-aware hooks with fixtures:
+
+```ts
+const test = base.extend<{ db: Database }>({
+  db: async ({}, use) => {
+    const db = await createDb()
+    await use(db)
+    await db.close()
+  },
+})
+
+// Hooks know about fixtures
+test.beforeEach(({ db }) => {
+  db.seed()
+})
+
+test.afterEach(({ db }) => {
+  db.clear()
+})
+```
+
+## Composing Fixtures
+
+Extend from another extended test:
+
+```ts
+// base-test.ts
+export const test = base.extend<{ db: Database }>({
+  db: async ({}, use) => { /* ... */ },
+})
+
+// admin-test.ts
+import { test as dbTest } from './base-test'
+
+export const test = dbTest.extend<{ admin: User }>({
+  admin: async ({ db }, use) => {
+    const admin = await db.createAdmin()
+    await use(admin)
+  },
+})
+```
+
+## Key Points
+
+- Use `{ }` destructuring to access fixtures
+- Fixtures are lazy - only initialize when accessed
+- Return cleanup function from fixtures
+- Use `{ auto: true }` for setup fixtures
+- Use `{ scope: 'file' }` for expensive shared resources
+- Fixtures compose - extend from extended tests
+
+<!-- 
+Source references:
+- https://vitest.dev/guide/test-context.html
+-->