Skip to content

[Assertions] Set foundation for deterministic assertions #26

@priyanshus

Description

@priyanshus

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No fields configured for Feature.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions