Skip to content

Commit 93e2a07

Browse files
committed
docs(expect): replace Next Steps with Error Output and Best Practices
- Add Error Output Example section with List reporter format - Add Best Practices section with 5 recommendations: - Use specific assertions for better error messages - Chain related assertions for readability - Use .not for negative assertions - Validate structure before values - Use toHaveDataMatching for partial validation
1 parent 97c104f commit 93e2a07

1 file changed

Lines changed: 144 additions & 4 deletions

File tree

docs/expect.md

Lines changed: 144 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)