vitest-bdd-3layer

Original：🇨🇳 Chinese

Translated

Three-layer Vitest-BDD Skill for DashPlayer. Use this when developers want business-readable BDD scenarios without coupling scenario writing to code implementation details. Trigger keywords: "Three-layer BDD", "Behavioral Testing Layering", "Given-When-Then", "Vitest BDD", "Avoid writing implementations in scenarios".

1installs

Sourcesolidspoon/dashplayer

Added on2026-02-23

NPX Install

npx skill4agent add solidspoon/dashplayer vitest-bdd-3layer

SKILL.md Content (Chinese)

View Translation Comparison →

Purpose

Write BDD tests in DashPlayer using Vitest + Three-layer Model to decouple "scenario writing" from "implementation details".

Target Outcomes:

Scenario layer only contains business sentences (Given/When/Then)
Step layer maintains a dictionary of business actions
Implementation layer centralizes mocks / fixtures / adapters

Scope of Application

Modules with clear business rules that require readable acceptance scenarios
Contract verification for service + IPC + renderer
Modules expected to be extended to more business domains later (settings / ai-trans / watch-history)

Not Applicable:

Pure algorithm utility functions (regular unit tests are more efficient)
Highly volatile, easily flaky strong timing use cases

Mandatory Three-layer Directory Structure

Take

settings

as an example:

Scenario Layer

src/backend/application/services/__tests__/Xxx.bdd.test.ts

Only write
```
given/when/then
```
business statements
Direct use of
```
new Service
```
,
```
vi.spyOn
```
,
```
store.set/get
```
is prohibited

Step Dictionary Layer
- ```
src/backend/application/services/__tests__/bdd/xxx.steps.ts
```
- Organize capabilities with English method names:
```
given* / when* / then*
```
- Scenario layer only calls methods from the step layer
Fixture/Adapter Layer
- ```
src/backend/application/services/__tests__/bdd/xxx.fixture.ts
```
- Unified management of mocks, fixtures, dependency injection and underlying calls

Utility Class Conventions

Reuse:

src/test/bdd.ts

Recommended import method (to avoid ESM

then

named export pitfalls):

ts

import bdd from '@/test/bdd'
const { scenario, given, when, then } = bdd

Standard Implementation Process

1) First write the scenario list (business sentences)

Each scenario must follow the structure:

Given <precondition>, When <trigger action>, Then <business result>

2) Define step dictionary methods

Use English naming, examples:

```
givenInvalidProviderValues()
```
```
whenQueryEngineSelection()
```
```
thenProvidersNormalizedToNone()
```

Rules:

```
given*
```
only prepares preconditions
```
when*
```
only triggers actions
```
then*
```
only asserts business results

3) Complete fixtures in the implementation layer

The implementation layer is responsible for:

Service instance creation
Store/mock initialization
Spy management (e.g.,
```
fs.existsSync
```
)
Data read/write helpers (
```
setValue/getValue
```
)

4) Scenario layer only orchestrates, does not implement

Example of scenario layer:

ts

scenario('Settings: Engine Selection Behavior', () => {
  it('Given invalid provider values, when querying engine selection, then should normalize to none', async () => {
    await given('Given: invalid provider values', () => steps.givenInvalidProviderValues())
    await when('When: query engine selection', () => steps.whenQueryEngineSelection())
    await then('Then: should normalize to none', () => steps.thenProvidersNormalizedToNone())
  })
})

Review Checklist (8 Items)

Scenario names follow the "Given-When-Then" sentence structure
No technical details in the scenario layer (no mock/new/spyOn)
Step method names uniformly use the
```
given/when/then
```
prefix
Step layer does not stack complex mock logic
Implementation layer centrally manages dependencies and test doubles
Then assertions focus on business results, not private implementations
State isolation between scenarios (reset via beforeEach)
Passes when running
```
yarn test:bdd
```

Common Misuses (Must Avoid)

Directly writing mocks or accessing the store in the scenario layer
Mixing Chinese and English in step method names (triggers naming rule alerts)
One scenario covers multiple business commitments
Only asserting internal call counts, not business results
Step layer directly contains a large amount of underlying construction logic (should be delegated to the implementation layer)

Run Commands

bash

yarn test:bdd
yarn test:bdd:watch

Extension Suggestions

Create new business domains following the same three-layer structure:
- ```
xxx.bdd.test.ts
```
- ```
bdd/xxx.steps.ts
```
- ```
bdd/xxx.fixture.ts
```
Prioritize reusing
```
src/test/bdd.ts
```
, do not reinvent the DSL.