2025-05-23 18:30:47 +00:00
|
|
|
# SmartExpect - Project Hints
|
|
|
|
|
|
|
|
|
|
## Project Overview
|
|
|
|
|
- **Name**: @push.rocks/smartexpect
|
|
|
|
|
- **Purpose**: A minimal, promise-first assertion library for testing with TypeScript support
|
|
|
|
|
- **License**: MIT
|
|
|
|
|
- **Version**: 2.4.2
|
|
|
|
|
|
|
|
|
|
## Architecture
|
|
|
|
|
1. **Core Assertion Class** (`ts/smartexpect.classes.assertion.ts`):
|
|
|
|
|
- Central `Assertion<T, M>` class handles all assertion logic
|
|
|
|
|
- Supports sync and async execution modes
|
|
|
|
|
- Property drilling with `.property()` and `.arrayItem()`
|
|
|
|
|
- Custom matcher extension via `expect.extend()`
|
|
|
|
|
|
|
|
|
|
2. **Namespace Organization** (`ts/namespaces/`):
|
|
|
|
|
- Matchers grouped by type: string, number, array, object, boolean, function, date, type
|
|
|
|
|
- Each namespace provides type-specific assertions
|
|
|
|
|
- All namespaces extend the base Assertion class
|
|
|
|
|
|
|
|
|
|
3. **Entry Point** (`ts/index.ts`):
|
|
|
|
|
- Exports the main `expect()` function
|
|
|
|
|
- Auto-detects promises for async mode
|
|
|
|
|
- Provides `expect.any()` and `expect.anything()` utility matchers
|
|
|
|
|
|
|
|
|
|
## Key Features
|
|
|
|
|
- **Async-first**: `.resolves` and `.rejects` modifiers for promise assertions
|
|
|
|
|
- **Timeout support**: `.withTimeout(ms)` for async assertions
|
|
|
|
|
- **Negation**: `.not` modifier inverts any assertion
|
|
|
|
|
- **Property navigation**: Chain `.property()` and `.arrayItem()` for nested assertions
|
|
|
|
|
- **Custom matchers**: Extend with `expect.extend({ matcherName: fn })`
|
|
|
|
|
- **Debugging**: `.log()` method to inspect values during assertion chains
|
|
|
|
|
|
|
|
|
|
## Dependencies
|
|
|
|
|
- `@push.rocks/smartdelay`: For async timeout handling
|
|
|
|
|
- `@push.rocks/smartpromise`: For promise utilities
|
|
|
|
|
- `fast-deep-equal`: For deep equality comparisons
|
|
|
|
|
|
|
|
|
|
## Testing
|
|
|
|
|
- Tests use `@git.zone/tstest` with tap
|
|
|
|
|
- Test files import from compiled `dist_ts/` directory
|
|
|
|
|
- Test naming: `*.both.ts` (browser+node), `*.node.ts`, `*.browser.ts`
|
|
|
|
|
- Run with `pnpm test`
|
|
|
|
|
|
|
|
|
|
## Recent Changes
|
|
|
|
|
- v2.4.2: General maintenance
|
|
|
|
|
- v2.4.1: Fixed toHaveProperty alias to forward arguments correctly
|
|
|
|
|
- v2.4.0: Major improvements (details not specified)
|
|
|
|
|
|
|
|
|
|
## Common Patterns
|
|
|
|
|
1. **Basic assertions**: `expect(value).toEqual(expected)`
|
|
|
|
|
2. **Async assertions**: `expect(promise).resolves.toEqual(value)`
|
|
|
|
|
3. **Property drilling**: `expect(obj).property('nested').property('value').toEqual(x)`
|
|
|
|
|
4. **Array navigation**: `expect(arr).arrayItem(0).toEqual(firstItem)`
|
|
|
|
|
5. **Custom messages**: `expect(x).setFailMessage('Custom error').toEqual(y)`
|
