Testing Layout

.claude/commands/unit-tester.md

@@ -199,7 +199,91 @@ class TestControlRender:
 
 **Note:** This organization applies **only to controls** (components with rendering capabilities). For other classes (core logic, utilities, etc.), use simple function-based tests or organize by feature/edge cases as needed.
 
-### UTR-11: Test Workflow
+### UTR-11: Required Reading for Control Render Tests
+
+**Before writing ANY render tests for Controls, you MUST:**
+
+1. **Read the matcher documentation**: `docs/testing_rendered_components.md`
+2. **Understand the key concepts**:
+   - How `matches()` and `find()` work
+   - When to use predicates (Contains, StartsWith, AnyValue, etc.)
+   - How to test only what matters (not every detail)
+   - How to read error messages with `^^^` markers
+3. **Apply the best practices**:
+   - Test only important structural elements and attributes
+   - Use predicates for dynamic/generated values
+   - Don't over-specify tests with irrelevant details
+   - Structure tests in layers (overall structure, then details)
+
+**Mandatory render test rules:**
+
+1. **Test naming**: Use descriptive names like `test_empty_layout_is_rendered()` not `test_layout_renders_with_all_sections()`
+2. **Documentation format**: Every render test MUST have a docstring with:
+   - First line: Brief description of what is being tested
+   - Blank line
+   - "Why these elements matter:" or "Why this test matters:" section
+   - List of important elements/attributes being tested with explanations (in English)
+3. **No inline comments**: Do NOT add comments on each line of the expected structure
+4. **Icon testing**: Use `Div(NotStr(name="icon_name"))` to test SVG icons
+   - Use the exact icon name from the import (e.g., `name="panel_right_expand20_regular"`)
+   - Use `name=""` (empty string) if the import is not explicit
+   - NEVER use `name="svg"` - it will cause test failures
+5. **Component testing**: Use `TestObject(ComponentClass)` to test presence of components
+6. **Explanation focus**: In "Why these elements matter", refer to the logical element (e.g., "Svg") not the technical implementation (e.g., "Div(NotStr(...))")
+
+**Example of proper render test:**
+```python
+from myfasthtml.test.matcher import matches, find, Contains, NotStr, TestObject
+from fasthtml.common import Div, Header, Button
+
+class TestControlRender:
+    def test_empty_control_is_rendered(self, root_instance):
+        """Test that control renders with main structural sections.
+
+        Why these elements matter:
+        - 3 children: Verifies header, body, and footer are all rendered
+        - _id: Essential for HTMX targeting and component identification
+        - cls="control-wrapper": Root CSS class for styling
+        """
+        control = MyControl(root_instance)
+
+        expected = Div(
+            Header(),
+            Div(),
+            Div(),
+            _id=control._id,
+            cls="control-wrapper"
+        )
+
+        assert matches(control.render(), expected)
+
+    def test_header_with_icon_is_rendered(self, root_instance):
+        """Test that header renders with action icon.
+
+        Why these elements matter:
+        - Svg: Action icon is essential for user interaction
+        - TestObject(ActionButton): ActionButton component must be present
+        - cls="header-bar": Required CSS class for header styling
+        """
+        control = MyControl(root_instance)
+        header = control._mk_header()
+
+        expected = Header(
+            Div(NotStr(name="action_icon_20_regular")),
+            TestObject(ActionButton),
+            cls="header-bar"
+        )
+
+        assert matches(header, expected)
+```
+
+**When proposing render tests:**
+- Reference specific patterns from the documentation
+- Explain why you chose to test certain elements and not others
+- Justify the use of predicates vs exact values
+- Always include "Why these elements matter" documentation
+
+### UTR-12: Test Workflow
 
 1. **Receive code to test** - User provides file path or code section
 2. **Check existing tests** - Look for corresponding test file and read it if it exists