smartexpect/readme.hints.md

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)