test-coverage

Files (6)

• SKILL.md
• fallow-integration.md · references/
• web-realness.md · references/
• coverage-metrics.js · scripts/lib/
• prioritize-refactor-risk.js · scripts/
• summarize-coverage.js · scripts/

SKILL.md (first lines)

# Tests, coverage, and refactor risk

Canonical reference: **`work/realness`** (`@realness.online/web`). Run every
command below from that directory.

Match `tests/**/*.spec.js` there. Do not introduce Jest, React Testing Library, TypeScript test files, or co-located `*.test.ts`.

Two jobs:

1. **Write specs** - patterns below; detail in [references/web-realness.md](references/web-realness.md)
2. **Prioritize** - `npm run test:risk` before refactors; not a blind chase for 100%

## Stack

| Piece | What we use |
| --- | --- |
| Runner | Vite Plus - `vp test`, `import ... from 'vite-plus/test'` |
| Engine | Vitest (`vite-plus-test` alias) |
| DOM | `happy-dom` |
| Vue | `@vue/test-utils` - prefer `shallowMount` |
| Language | JavaScript + JSDoc |
| Coverage | V8, 80% global, `all: true` |

## Commands

```bash
vp test run --reporter=dot          # npm run test
vp test watch                       # npm run test:watch
vp test run --coverage              # npm run test:coverage
vp test run --bail=1 --reporter=dot # npm run test:fail-fast
npm run test:risk                   # coverage + fallow + risk report
```

Pre-commit: `vp check --fix && vp run type && vp test run`.

## Writing specs

### Layout

- All specs in `tests/**/*.spec.js` mirroring `src/` (not co-located)
- `describe('@/utils/itemid', ...)` or view/component name
- `@/` -> `src/`; `@@/` -> `tests/mocks/`
- Config: `vite.config.js` -> `test` block; setup: `tests/setup.js`, `tests/mocks/`

### Skeleton

```javascript
import { describe, it, expect, vi, beforeEach } from 'vite-plus/test'
import { fn_under_test } from '@/utils/example'

describe('@/utils/example', () => {
  beforeEach(() => {
    vi.clearAllMocks()
  })

  it('describes behavior in plain language', () => {
    expect(fn_under_test('input')).toBe('output')
  })
})
```

Test behavior, not internals (JS style: AGENTS.md).

### Key patterns

| Pattern | Approach | Reference spec |
| --- | --- | --- |
| Pure utils | Input/output, nested `describe` | `tests/utils/itemid.spec.js` |
| Module mocks | Top-level `vi.mock()`; `vi.clearAllMocks()` in `beforeEach` | `tests/utils/itemid.spec.js` |
| Vue components | `shallowMount`, stubs, semantic queries | `tests/components/account/as-notifications.spec.js` |
| Composable mocks | `vi.hoisted()` refs for `vi.mock` closures | `tests/views/Account.spec.js` |
| Composables | `with_setup()` + `mount(defineComponent(...))` | `tests/use/poster.spec.js` |
| Async errors | `await expect(...).rejects.toThrow()` | `tests/utils/itemid.spec.js` |

**Hoisted mocks** (reset `.value` in `beforeEach`):

```javascript
const { mock_status, mock_enable } = vi.hoisted(() => {
  const create_ref = value => ({ value, __v_isRef: true })
  return {
    mock_status: create_ref('off'),
    mock_enable: vi.fn().mockResolvedValue(true)
  }
})

vi.mock('@/use/push', () => ({
  use_push: () => ({ status: mock_status, enable: mock_enable })
}))
```

Global mocks: `tests/mocks/default.js`, `tests/mocks/browser/*`. Per-spec mocks only when behavior differs.

`mockReset: false` in config - mocks keep implementations; clear call history each test.

### What we do not do

| Avoid | Use instead |
| --- | --- |
| Jest / React Testing Library | `vite-plus/test` + `@vue/test-utils` |
| TypeScript test files | `.spec.js` + JSDoc |
| `@faker-js/faker` | Domain fixtures (item IDs, directories) |
| supertest / live DB | Mock `idb-keyval`, `serverless` |
| `data-testid` | Semantic DOM queries |
| 100% coverage | 80% gate + risk report |

Full patterns, templates, file map: [references/web-realness.md](references/web-realness.md)

## Coverage workflow

### 1. Risk report (start here)

```bash
npm run test:risk
# or, if reports already exist:
npm run test:risk:report
```

Runs `scripts/prioritize-refactor-risk.js`.

From scott-fryxell/brayness, MIT.

More from scott-fryxell/brayness