# Constrained Tests

> Slow-CI simulation — run unit tests on saturated CPU to reproduce CI-style flakiness locally. Suggest when new/reworked suite lean heavy on awaits (deferFulfillment, waitForConfirmation, TestClock, timeouts) or test fail only on CI. Not for every change.

- Skill: `element-hq/constrained-tests` (Agent Skill)
- Install (CLI): `npx skillmds@latest add element-hq/constrained-tests`
- Raw SKILL.md: https://api.skillmd.com/api/skills/element-hq/constrained-tests/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: element-hq (https://skillmd.com/u/element-hq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/element-hq/constrained-tests

---


# Constrained test runs

CI runners shared + slow. Background tasks starve, awaits stretch, scheduler races flake there, pass locally. `--constrained` saturate CPU with hog tasks — same conditions, local.

## When

- PR add/rework suite heavy on timing-sensitive async: `deferFulfillment`, `waitForConfirmation`, `TestClock`, `transitionValues`, timeouts.
- Test fail on CI, pass locally.
- Not routine changes, not sync suites — slow, no gain.

## How

Full unit test workflow (what CI run):

```bash
swift run tools ci unit-tests --constrained
```

One suite, iterate on new tests (prefer while developing):

```bash
swift run tools ci run-tests --scheme UnitTests --test-name MyNewTests --constrained
```

Hog count automatic (2× cores). Suite survive ~10 constrained iterations → good shape.

## Failures mean

Failure under constraint = real bug in test (sometimes code under test): assertion race async work, transient state observation missed, timeout too tight. Fix synchronisation, no blind timeout bump. Helpers in `UnitTests/Sources/TestUtilities/` (`deferFulfillment`, `deferFailure`, `waitForConfirmation`). Wait on durable state, not transient.