docs: add assertion best practices to Playwright guide (#10663)

## Summary

Document custom expect messages and soft assertions as Playwright best
practices.

## Changes

- **What**: Added "Assertion Best Practices" section to
`docs/guidance/playwright.md` covering custom messages, `expect.soft()`,
and guidelines for when to use each.

## Review Focus

Documentation-only change — no code impact.

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-10663-docs-add-assertion-best-practices-to-Playwright-guide-3316d73d365081309d83f95bb9b86fe1)
by [Unito](https://www.unito.io)

---------

Co-authored-by: GitHub Action <action@github.com>

docs/guidance/playwright.md

@@ -75,6 +75,30 @@ await page.evaluate(() => {
 // Keep app.extensionManager typed as ExtensionManager, not WorkspaceStore
 ```
 
+## Assertion Best Practices
+
+When a test depends on an invariant unrelated to what it's actually testing (e.g. asserting a node has 4 widgets before testing node movement), always assert that invariant explicitly — don't leave it unchecked. Use a custom message or `expect.soft()` rather than a bare `expect`, so failures point to the broken assumption instead of producing a confusing error downstream.
+
+```typescript
+// ✅ Custom message on an unrelated precondition — clear signal when the invariant breaks
+expect(node.widgets, 'Widget count changed — update test fixture').toHaveLength(
+  4
+)
+await node.move(100, 200)
+
+// ✅ Soft assertion — verifies multiple invariants without stopping the test early
+expect.soft(menuItem1).toBeVisible()
+expect.soft(menuItem2).toBeVisible()
+expect.soft(menuItem3).toBeVisible()
+
+// ❌ Bare expect on a precondition — no context when it fails
+expect(node.widgets).toHaveLength(4)
+```
+
+- Use custom messages (`expect(x, 'reason')`) for precondition checks unrelated to the test's purpose
+- Use `expect.soft()` when you want to verify multiple invariants without aborting on the first failure
+- Prefer Playwright's built-in message parameter over custom error classes
+
 ## Test Tags
 
 Tags are respected by config: