@@ -335,8 +335,148 @@ export default scenario("Error Example")
335335 .build ();
336336```
337337
338- ## Next Steps
338+ ### Error Output Example
339339
340- - [ Overview] ( /docs/ ) - Get started with Probitas
341- - [ Scenario Guide] ( /docs/scenario/ ) - Learn how to write scenarios
342- - [ Client API] ( /docs/client/ ) - Detailed reference for each client
340+ When an assertion fails, the List reporter displays detailed error information:
341+
342+ ```
343+ T┆ ✗ User API Test > Check user response (user.probitas.ts:15) [12.34ms]
344+ ┆ └ Expected status to be 200, but got 404
345+
346+ Failed Tests
347+ T┆ ✗ User API Test > Check user response (user.probitas.ts:15) [12.34ms]
348+ ┆
349+ ┆ Expected status to be 200, but got 404
350+ ┆
351+ ┆ Diff (-Actual / +Expected):
352+ ┆
353+ ┆ - 404
354+ ┆ + 200
355+ ┆
356+ ┆ Subject
357+ ┆
358+ ┆ {
359+ ┆ ok: false,
360+ ┆ status: 404,
361+ ┆ statusText: "Not Found"
362+ ┆ }
363+ ┆
364+ ┆ Stack trace
365+ ┆
366+ ┆ at file:///path/to/user.probitas.ts:15:12
367+ ```
368+
369+ ** Output components:**
370+
371+ | Component | Description |
372+ | -------------- | ------------------------------------------------- |
373+ | ` T┆ ` | Step type indicator (T=step, s=setup, r=resource) |
374+ | ` ✗ ` | Failure icon (red) |
375+ | ` (file.ts:15) ` | Source location |
376+ | ` [12.34ms] ` | Execution duration |
377+ | ` Diff ` | Shows difference between actual and expected |
378+ | ` Subject ` | The object being tested |
379+ | ` Stack trace ` | Call stack for debugging |
380+
381+ ## Best Practices
382+
383+ ### Use Specific Assertions
384+
385+ Prefer specific assertions over generic ones for better error messages:
386+
387+ ``` typescript
388+ import { client , expect } from " jsr:@probitas/probitas" ;
389+
390+ const http = client .http .createHttpClient ({ url: " http://localhost:8080" });
391+ const res = await http .get (" /users/1" );
392+
393+ // Good: Clear, descriptive error message on failure
394+ // "Expected status to be 200, but got 404"
395+ expect (res ).toHaveStatus (200 );
396+
397+ // Good: Shows diff of expected vs actual data
398+ expect (res ).toHaveDataMatching ({ id: 1 });
399+
400+ // Less ideal: Generic message "Expected 200 but received 404"
401+ expect (res .status ).toBe (200 );
402+ ```
403+
404+ ### Chain Related Assertions
405+
406+ Group related assertions in a single chain for readability:
407+
408+ ``` typescript
409+ import { client , expect } from " jsr:@probitas/probitas" ;
410+
411+ const http = client .http .createHttpClient ({ url: " http://localhost:8080" });
412+ const res = await http .get (" /users/1" );
413+
414+ // Good: Single chain for related checks
415+ expect (res )
416+ .toBeOk ()
417+ .toHaveStatus (200 )
418+ .toHaveDataMatching ({ id: 1 , name: " Alice" });
419+
420+ // Less ideal: Separate expect calls
421+ expect (res ).toBeOk ();
422+ expect (res ).toHaveStatus (200 );
423+ expect (res ).toHaveDataMatching ({ id: 1 , name: " Alice" });
424+ ```
425+
426+ ### Use ` .not ` for Negative Assertions
427+
428+ Use ` .not ` to explicitly check for absence or negative conditions:
429+
430+ ``` typescript
431+ import { client , expect } from " jsr:@probitas/probitas" ;
432+
433+ const http = client .http .createHttpClient ({ url: " http://localhost:8080" });
434+ const res = await http .get (" /users/1" );
435+
436+ // Check error responses are NOT returned
437+ expect (res )
438+ .not .toHaveStatus (404 )
439+ .not .toHaveStatus (500 )
440+ .toBeOk ();
441+
442+ // Verify data does NOT contain sensitive fields
443+ expect (res ).not .toHaveDataProperty (" password" );
444+ ```
445+
446+ ### Validate Structure Before Values
447+
448+ Check structure exists before asserting on specific values:
449+
450+ ``` typescript
451+ import { client , expect } from " jsr:@probitas/probitas" ;
452+
453+ const http = client .http .createHttpClient ({ url: " http://localhost:8080" });
454+ const res = await http .get (" /users/1" );
455+
456+ // Good: Validates structure progressively
457+ expect (res )
458+ .toBeOk ()
459+ .toHaveDataProperty (" user" )
460+ .toHaveDataMatching ({
461+ user: { id: 1 , email: " alice@example.com" },
462+ });
463+ ```
464+
465+ ### Use ` toHaveDataMatching ` for Partial Validation
466+
467+ When you only care about specific fields, use partial matching:
468+
469+ ``` typescript
470+ import { client , expect } from " jsr:@probitas/probitas" ;
471+
472+ const http = client .http .createHttpClient ({ url: " http://localhost:8080" });
473+ const res = await http .get (" /users/1" );
474+
475+ // Good: Only validates relevant fields
476+ expect (res ).toHaveDataMatching ({
477+ id: 1 ,
478+ status: " active" ,
479+ });
480+
481+ // This ignores other fields like createdAt, updatedAt, etc.
482+ ```
0 commit comments