55 lines
2.3 KiB
Markdown
55 lines
2.3 KiB
Markdown
# Plan for Improving @push.rocks/smartexpect API
|
||
|
||
This document captures the roadmap for evolving the `expect` / `expectAsync` API.
|
||
|
||
## Phase 1: Unify Sync + Async
|
||
- [x] Consolidate `expect` and `expectAsync` into a single `expect()` entry point.
|
||
- [x] Introduce `.resolves` and `.rejects` chainable helpers for Promises.
|
||
- [x] Deprecate `expectAsync`, provide migration guidance.
|
||
|
||
## Phase 2: Timeout Helper
|
||
- [x] Rename or wrap the existing `.timeout(ms)` to a more intuitive `.withTimeout(ms)`.
|
||
|
||
## Phase 3: Custom Matchers
|
||
- [x] Implement `expect.extend()` API for user-defined matchers.
|
||
|
||
## Phase 4: TypeScript Typings
|
||
- [ ] Enhance generic matcher types to infer narrow types after `.property()` / `.arrayItem()`.
|
||
- [ ] Provide matcher overloads for primitive categories (string, number, array, etc.).
|
||
|
||
## Phase 5: Namespaced Matchers
|
||
- [ ] Group matchers under `.string`, `.array`, `.number`, etc. for discoverability.
|
||
|
||
## Phase 6: Jest-Style Convenience
|
||
- [x] Add `expect.any()` and `expect.anything()` matchers for use in `.toMatchObject()` patterns
|
||
(Snapshot matchers still TBD)
|
||
|
||
The next items to tackle:
|
||
|
||
3. Improve negation (`.not`) messaging
|
||
- Today `.not` simply flips pass/fail, but the failure message isn’t very descriptive. We should capture positive/negative message templates so e.g.
|
||
> expect(5).not.toBeGreaterThan(3)
|
||
emits:
|
||
"Expected 5 not to be greater than 3"
|
||
|
||
4. Richer error output for objects/arrays
|
||
- Integrate a diff library (or extend `fast-deep-equal`) to show unified diffs between expected and actual values
|
||
|
||
5. More built-in matchers
|
||
- toBeNaN(), toBeFinite()
|
||
- toBeWithinRange(min, max)
|
||
- toHaveKeys(...), toHaveOwnKeys(...)
|
||
- toThrowErrorMatching(/regex/), toThrowErrorWithMessage('…')
|
||
- string/array: toBeEmpty() alias
|
||
- object: toHaveOwnProperty() shorthand
|
||
|
||
6. TypeScript-friendliness
|
||
- Enhance `.d.ts` so editors autocomplete namespace methods (e.g. `expect(x).string.`)
|
||
- Statically type matcher arguments to catch wrong types at compile time
|
||
|
||
7. Async assertions and timeouts improvements
|
||
- Support `.not.resolves`, `.rejects.toThrow()`
|
||
- Provide clearer timeout errors (e.g. "Expected promise to resolve within …")
|
||
|
||
8. Plugin/extension API
|
||
- Formalize `Assertion.extend()` plugin API for shipping matcher bundles |