Summary
Establish the expect() API as the entry point for all deterministic assertions. This feature request is about the foundation only — the builder pattern, the result contract, the error model, and the execution behaviour. No assertions are shipped in this request except one reference implementation to validate the design.
Motivation
Before building any assertions we need a stable foundation that all future assertions can build on. Getting the foundation right means every assertion added later is consistent, testable, and follows the same contract without additional architectural decisions.
Proposed API
// basic usage
expect(value).toContain('30 days');
// with custom message (optional) — shown in report when assertion fails
expect(value, 'Response should mention return window')
.toContain('30 days');
Acceptance Criteria
- toContain implemented as reference assertion
- failed assertion throws DeterministicAssertionError
- DeterministicAssertionError caught by engine and recorded
- message appears in console output when assertion fails
- message appears in JSON report
- result shape matches DeterministicAssertionResult
- no async anywhere in this feature
Describe the solution you'd like
Result Contract
interface DeterministicAssertionResult {
passed: boolean
score: 0 | 1
reason: string // generated by the assertion
message: string | undefined // provided by the user
assertionName: string
type: 'deterministic'
durationMs: number
}
AssertionError:
Response should mention return window
toContain failed
Expected to contain:
"30 days"
Received:
"You can return items within one month."
Describe alternatives you've considered
No response
Additional context
No response
Summary
Establish the expect() API as the entry point for all deterministic assertions. This feature request is about the foundation only — the builder pattern, the result contract, the error model, and the execution behaviour. No assertions are shipped in this request except one reference implementation to validate the design.
Motivation
Before building any assertions we need a stable foundation that all future assertions can build on. Getting the foundation right means every assertion added later is consistent, testable, and follows the same contract without additional architectural decisions.
Proposed API
// basic usage
expect(value).toContain('30 days');
// with custom message (optional) — shown in report when assertion fails
expect(value, 'Response should mention return window')
.toContain('30 days');
Acceptance Criteria
Describe the solution you'd like
Result Contract
interface DeterministicAssertionResult {
passed: boolean
score: 0 | 1
reason: string // generated by the assertion
message: string | undefined // provided by the user
assertionName: string
type: 'deterministic'
durationMs: number
}
AssertionError:
Response should mention return window
toContain failed
Expected to contain:
"30 days"
Received:
"You can return items within one month."
Describe alternatives you've considered
No response
Additional context
No response