# Cratis Specifications Typescript

> Use when adding or restructuring Cratis framework TypeScript specifications, given contexts or BDD folders. Not for C# tests, application React scenario selection or deciding production behavior.

- Skill: `cratis/cratis-specifications-typescript-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add cratis/cratis-specifications-typescript-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cratis/cratis-specifications-typescript-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: Cratis (https://skillmd.com/u/cratis)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/cratis/cratis-specifications-typescript-2

---


# Cratis TypeScript specifications

Specifications describe behavior, not implementation. The `given()` helper and
its context class are the TypeScript counterpart of the C# `Specification`
base: setup is separated from the action, and each `it()` verifies one outcome.

## Verified product sources

Helper and setup patterns come from Fundamentals
(`for_JsonSerializer/given/given.ts`, `vitest.setup.ts`) and Arc
(`Source/JavaScript/Arc/given.ts`). The execution stack is:

| Framework | Role |
| --- | --- |
| Vitest | Test runner (`yarn test` from the package root) |
| Mocha-style structure | `describe`, `it`, `beforeEach`, `afterEach` |
| Chai | Assertions, always through the `.should` fluent interface |
| Sinon | Stubbing and call verification |

`given()` is a small **local file** inside the package under specification, not
a published package export. Import it with a relative path to that file; create
it if absent. Fundamentals constructs a parameterless context; Arc passes the
Mocha `Suite` to the context constructor and binds the callback's `this` to it.
Match the owning package's helper signature rather than assuming one import path.

Configure Vitest to load a setup file that calls `chai.should()` and registers
`sinon-chai` and `chai-as-promised`; otherwise `.should` is undefined or plugin
assertions are unavailable. Load the reflection polyfill when specifying
metadata-dependent code (Fundamentals' setup imports its local `reflection`
entry). The Specifications repository publishes no TypeScript helper.

## Route near misses

- The specification is C#: use `cratis-specifications-csharp` instead.
- The subject is an application view model or React component rather than a
  Cratis TypeScript package: the plain `describe`/`beforeEach` frontend style
  applies, not the `given()` helper in this skill.
- The question is what the code under specification *should do*: resolve the
  behavior first; this skill only specifies already decided behavior.

## Step 1 — Create the folder structure

Specifications live alongside the source they describe:

```
for_<ClassName>/
├── given/
│   └── a_<system_under_test>.ts   ← reusable context class
├── when_<behavior>/               ← a behavior with multiple outcomes
│   ├── with_<condition>.ts
│   ├── without_<condition>.ts
│   └── and_<condition>.ts
└── when_<simple_behavior>.ts      ← a single outcome is a single file
```

Paths read as English sentences. Allowed outcome prefixes are `and_`, `with_`,
`without_`, `having_`, and `given_`.

**`when` belongs only in a `when_<behavior>` folder name.** A specification file
or non-`when_` folder must never contain the word `when`. Fold the context into
the `when_` folder name and use preposition files for the outcomes. Add a
sub-folder under `when_` only when that condition has its own multiple outcomes.

## Step 2 — Write a reusable context class

```ts
// for_<ClassName>/given/a_<system_under_test>.ts
import sinon from 'sinon';
import { <ClassName> } from '../../../<ClassName>';

export class a_<system_under_test> {
    <collaborator>: sinon.StubbedInstance<<CollaboratorType>>;
    <sut>: <ClassName>;

    constructor() {
        this.<collaborator> = sinon.createStubInstance(<CollaboratorClass>);
        this.<collaborator>.<method>.returns(<default>);
        this.<sut> = new <ClassName>(this.<collaborator>);
    }
}
```

Context properties are **public** — the specification reads them through the
`context` parameter. This differs from C#, where `given/` fields are
`protected`. Name the class `a_` or `an_` so it reads as "given a service, when
registering".

A context captures the world as it exists *before* the action. Never put the
action under specification in a context.

## Step 3 — Write the specification

```ts
// for_<ClassName>/when_<behavior>/with_<condition>.ts
import { a_<system_under_test> } from '../given/a_<system_under_test>';
import { given } from '../../given';

describe('when <behavior> with <condition>', given(a_<system_under_test>, context => {
    let result: <ResultType>;

    beforeEach(async () => {
        result = await context.<sut>.<action>(<input>);
    });

    it('should <expected outcome>', () => {
        result.should.equal(<expected>);
    });

    it('should <other expected outcome>', () => {
        context.<collaborator>.<method>.calledOnce.should.be.true;
    });
}));
```

`given()` constructs the context class **once per `describe`** and hands that
instance to the suite — it does not re-create it per `it()`. Isolation therefore
comes from the spec's shape: `beforeEach` performs the single action under
specification, and each `it()` only asserts one outcome of it. Never put a second
action in an `it()`; the stubs it would disturb are shared with the sibling
`it()` blocks.

## Step 4 — Skip the context when nothing is shared

A behavior with no shared setup needs no context class:

```ts
describe('when <behavior>', () => {
    let result: <ResultType>;

    beforeEach(() => {
        result = <TypeUnderSpecification>.<action>(<input>);
    });

    it('should <expected outcome>', () => {
        result.<property>.should.equal(<expected>);
    });
});
```

## Step 5 — Assert with the `.should` fluent interface

**Always use `.should`. Never use `expect()`.** The fluent style reads as a
sentence and matches the rest of the corpus.

```ts
value.should.equal(<expected>);
value.should.deep.equal(<expectedObject>);
flag.should.be.true;
value.should.be.null;
value.should.not.be.undefined;
items.should.contain(<expected>);
items.should.have.lengthOf(<count>);
items.should.be.empty;
value.should.be.instanceOf(<Type>);
(() => <throwingCall>()).should.throw(<ErrorType>);
```

Read [typescript-patterns.md](references/typescript-patterns.md) when choosing detailed assertions, configuring or restoring Sinon stubs, or arranging asynchronous specifications.

## Step 6 — Apply the naming conventions

| Element | Convention | Example |
| --- | --- | --- |
| `describe()` text | Natural-language sentence | `'when registering with a valid name'` |
| `it()` text | Starts with "should", **uses spaces** | `'should append an event'` |
| Context class | `a_` or `an_` prefix | `an_author_service` |
| Specification file | Preposition prefix | `with_valid_name.ts` |

Use spaces in `it()` descriptions, never underscores — they appear in runner
output as human-readable sentences. This is the deliberate difference from the C#
`should_` method naming.

## Step 7 — Keep one behavior per file

Do not mix orthogonal behaviors in one specification. Separate folders per
behavior keep failures precise:

```
when_items_are_added_as_delta/and_item_is_identified_by_a_guid.ts
when_items_are_removed_as_delta/and_item_is_identified_by_a_guid.ts
```

A single file validating both add-delta and remove-delta behavior tangles
unrelated outcomes and hides which one broke.

## What not to specify

- Simple property getters and setters.
- Properties that return a constructor parameter directly.
- Trivial delegation.
- Anything a `describe` beginning "when getting" or "when returning" would
  describe — that is a getter, not a behavior.

## Verify

- Each specification file states one `describe`, one action in `beforeEach`, and
  one or more single-outcome `it()` assertions.
- No path contains `when` outside a `when_<behavior>` folder name.
- Outcome files use an allowed preposition prefix.
- Context classes carry public properties, are named `a_`/`an_`, and contain no
  action under specification.
- Every assertion uses `.should`; no `expect()` appears.
- `it()` descriptions start with "should" and use spaces.
- Stubs are restored between specifications where Sinon state would otherwise
  leak.
- Nothing trivial is specified.
- `yarn test` passes from the package root.

