diff --git a/.claude/skills/unit-tester/SKILL.md b/.claude/skills/unit-tester/SKILL.md
index 5468dfe..0ca7078 100644
--- a/.claude/skills/unit-tester/SKILL.md
+++ b/.claude/skills/unit-tester/SKILL.md
@@ -8,11 +8,13 @@ disable-model-invocation: false
# Unit Tester Mode
-You are now in **Unit Tester Mode** - specialized mode for writing unit tests for existing code in the MyFastHtml project.
+You are now in **Unit Tester Mode** - specialized mode for writing unit tests for existing code in the MyFastHtml
+project.
## Primary Objective
Write comprehensive unit tests for existing code by:
+
1. Analyzing the code to understand its behavior
2. Identifying test cases (success paths and edge cases)
3. Proposing test plan for validation
@@ -20,86 +22,147 @@ Write comprehensive unit tests for existing code by:
## Unit Test Rules (UTR)
-### UTR-1: Test Analysis Before Implementation
+### UTR-1: Communication Language
+
+- **Conversations**: French or English (match user's language)
+- **Code, documentation, comments**: English only
+- Before writing tests, **list all planned tests with explanations**
+- Wait for validation before implementing tests
+
+
+### UTR-2: Test Analysis Before Implementation
Before writing any tests:
-1. **Check for existing tests first** - Look for corresponding test file (e.g., `src/foo/bar.py` → `tests/foo/test_bar.py`)
+
+1. **Check for existing tests first** - Look for corresponding test file (e.g., `src/foo/bar.py` →
+ `tests/foo/test_bar.py`)
2. **Analyze the code thoroughly** - Read and understand the implementation
3. **If tests exist**: Identify what's already covered and what's missing
4. **If tests don't exist**: Identify all test scenarios (success and failure cases)
5. **Present test plan** - Describe what each test will verify (new tests only if file exists)
6. **Wait for validation** - Only proceed after explicit approval
-### UTR-2: Test Naming Conventions
+### UTR-3: Ask Questions One at a Time
+
+**Ask questions to clarify understanding:**
+
+- Ask questions **one at a time**
+- Wait for complete answer before asking the next question
+- Indicate progress: "Question 1/5" if multiple questions are needed
+- Never assume behavior - always verify understanding
+
+### UTR-4: Code Standards
+
+**Follow PEP 8** conventions strictly:
+
+- Variable and function names: `snake_case`
+- Explicit, descriptive naming
+- **No emojis in code**
+
+**Documentation**:
+
+- Use Google or NumPy docstring format
+- Every test should have a clear docstring explaining what it verifies
+- Include type hints where applicable
+
+### UTR-5: Test Naming Conventions
- **Passing tests**: `test_i_can_xxx` - Tests that should succeed
- **Failing tests**: `test_i_cannot_xxx` - Edge cases that should raise errors/exceptions
**Example:**
+
```python
def test_i_can_create_command_with_valid_name():
- """Test that a command can be created with a valid name."""
- cmd = Command("valid_name", "description", lambda: None)
- assert cmd.name == "valid_name"
+ """Test that a command can be created with a valid name."""
+ cmd = Command("valid_name", "description", lambda: None)
+ assert cmd.name == "valid_name"
+
def test_i_cannot_create_command_with_empty_name():
- """Test that creating a command with empty name raises ValueError."""
- with pytest.raises(ValueError):
- Command("", "description", lambda: None)
+ """Test that creating a command with empty name raises ValueError."""
+ with pytest.raises(ValueError):
+ Command("", "description", lambda: None)
```
-### UTR-3: Use Functions, Not Classes (Default)
+### UTR-6: Test File Organization
-- Use **functions** for tests by default
-- Only use classes when inheritance or grouping is required (see UTR-10)
-- Before writing tests, **list all planned tests with explanations**
-- Wait for validation before implementing tests
+**File paths:**
-### UTR-4: Do NOT Test Python Built-ins
+- Always specify the full file path when creating test files
+- Mirror source structure: `src/myfasthtml/core/commands.py` → `tests/core/test_commands.py`
+
+### UTR-7: What to choose, functions or classes during tests?
+
+- Use **functions** when tests are validating the same concern
+- Use **classes** when grouping is required, for example
+ - behavior tests and rendering tests can be grouped into TestControlBehaviour and TestControlRender classes
+ - CRUD operation can be grouped into TestCreate, TestRead, TestUpdate, TestDelete classes
+ - When code documentation in the class to test explicitly shows the concerns
+example
+```python
+ # ------------------------------------------------------------------
+ # Data initialisation
+ # ------------------------------------------------------------------
+```
+or
+```python
+ # ------------------------------------------------------------------
+ # Formula management
+ # ------------------------------------------------------------------
+```
+
+- Never mix functions and classes in the same test file
+
+### UTR-8: Do NOT Test Python Built-ins
**Do NOT test Python's built-in functionality.**
❌ **Bad example - Testing Python list behavior:**
+
```python
def test_i_can_add_child_to_node(self):
- """Test that we can add a child ID to the children list."""
- parent_node = TreeNode(label="Parent", type="folder")
- child_id = "child_123"
-
- parent_node.children.append(child_id) # Just testing list.append()
-
- assert child_id in parent_node.children # Just testing list membership
+ """Test that we can add a child ID to the children list."""
+ parent_node = TreeNode(label="Parent", type="folder")
+ child_id = "child_123"
+
+ parent_node.children.append(child_id) # Just testing list.append()
+
+ assert child_id in parent_node.children # Just testing list membership
```
This test validates that Python's `list.append()` works correctly, which is not our responsibility.
✅ **Good example - Testing business logic:**
+
```python
def test_i_can_add_child_node(self, root_instance):
- """Test adding a child node to a parent."""
- tree_view = TreeView(root_instance)
- parent = TreeNode(label="Parent", type="folder")
- child = TreeNode(label="Child", type="file")
-
- tree_view.add_node(parent)
- tree_view.add_node(child, parent_id=parent.id) # Testing OUR method
-
- assert child.id in tree_view._state.items # Verify state updated
- assert child.id in parent.children # Verify relationship established
- assert child.parent == parent.id # Verify bidirectional link
+ """Test adding a child node to a parent."""
+ tree_view = TreeView(root_instance)
+ parent = TreeNode(label="Parent", type="folder")
+ child = TreeNode(label="Child", type="file")
+
+ tree_view.add_node(parent)
+ tree_view.add_node(child, parent_id=parent.id) # Testing OUR method
+
+ assert child.id in tree_view._state.items # Verify state updated
+ assert child.id in parent.children # Verify relationship established
+ assert child.parent == parent.id # Verify bidirectional link
```
This test validates the `add_node()` method's logic: state management, relationship creation, bidirectional linking.
**Other examples of what NOT to test:**
+
- Setting/getting attributes: `obj.value = 5; assert obj.value == 5`
- Dictionary operations: `d["key"] = "value"; assert "key" in d`
- String concatenation: `result = "hello" + "world"; assert result == "helloworld"`
- Type checking: `assert isinstance(obj, MyClass)` (unless type validation is part of your logic)
-### UTR-5: Test Business Logic Only
+### UTR-9: Test Business Logic Only
**What TO test:**
+
- Your business logic and algorithms
- Your validation rules
- Your state transformations
@@ -107,65 +170,35 @@ This test validates the `add_node()` method's logic: state management, relations
- Your error handling for invalid inputs
- Your side effects (database updates, command registration, etc.)
-### UTR-6: Test Coverage Requirements
+### UTR-10: Test Coverage Requirements
For each code element, consider testing:
**Functions/Methods:**
+
- Valid inputs (typical use cases)
- Edge cases (empty values, None, boundaries)
- Error conditions (invalid inputs, exceptions)
- Return values and side effects
**Classes:**
+
- Initialization (default values, custom values)
- State management (attributes, properties)
- Methods (all public methods)
- Integration (interactions with other classes)
**Components (Controls):**
+
- Creation and initialization
- State changes
- Commands and their effects
- Rendering (if applicable)
- Edge cases and error conditions
-### UTR-7: Ask Questions One at a Time
+---
-**Ask questions to clarify understanding:**
-- Ask questions **one at a time**
-- Wait for complete answer before asking the next question
-- Indicate progress: "Question 1/5" if multiple questions are needed
-- Never assume behavior - always verify understanding
-
-### UTR-8: Communication Language
-
-**Conversations**: French or English (match user's language)
-**Code, documentation, comments**: English only
-
-### UTR-9: Code Standards
-
-**Follow PEP 8** conventions strictly:
-- Variable and function names: `snake_case`
-- Explicit, descriptive naming
-- **No emojis in code**
-
-**Documentation**:
-- Use Google or NumPy docstring format
-- Every test should have a clear docstring explaining what it verifies
-- Include type hints where applicable
-
-### UTR-10: Test File Organization
-
-**File paths:**
-- Always specify the full file path when creating test files
-- Mirror source structure: `src/myfasthtml/core/commands.py` → `tests/core/test_commands.py`
-
-**Example:**
-```
-✅ Creating: tests/core/test_new_feature.py
-✅ Modifying: tests/controls/test_treeview.py
-```
+### UTR-11: IMPORTANT ! Required Reading for Control Render Tests
**Test organization for Controls:**
@@ -173,43 +206,42 @@ Controls are classes with `__ft__()` and `render()` methods. For these component
```python
class TestControlBehaviour:
- """Tests for control behavior and logic."""
+ """Tests for control behavior and logic."""
+
+ def test_i_can_create_control(self, root_instance):
+ """Test basic control creation."""
+ control = MyControl(root_instance)
+ assert control is not None
+
+ def test_i_can_update_state(self, root_instance):
+ """Test state management."""
+ # Test state changes, data updates, etc.
+ pass
- def test_i_can_create_control(self, root_instance):
- """Test basic control creation."""
- control = MyControl(root_instance)
- assert control is not None
-
- def test_i_can_update_state(self, root_instance):
- """Test state management."""
- # Test state changes, data updates, etc.
- pass
class TestControlRender:
- """Tests for control HTML rendering."""
-
- def test_control_renders_correctly(self, root_instance):
- """Test that control generates correct HTML structure."""
- # Test HTML output, attributes, classes, etc.
- pass
-
- def test_control_renders_with_custom_config(self, root_instance):
- """Test rendering with custom configuration."""
- # Test different rendering scenarios
- pass
+ """Tests for control HTML rendering."""
+
+ def test_control_renders_correctly(self, root_instance):
+ """Test that control generates correct HTML structure."""
+ # Test HTML output, attributes, classes, etc.
+ pass
+
+ def test_control_renders_with_custom_config(self, root_instance):
+ """Test rendering with custom configuration."""
+ # Test different rendering scenarios
+ pass
```
**Why separate behaviour and render tests:**
+
- **Behaviour tests**: Focus on logic, state management, commands, and interactions
- **Render tests**: Focus on HTML structure, attributes, and visual representation
- **Clarity**: Makes it clear what aspect of the control is being tested
- **Maintenance**: Easier to locate and update tests when behaviour or rendering changes
-**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: Required Reading for Control Render Tests
-
----
+**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.0: Read the matcher documentation (MANDATORY PREREQUISITE)**
@@ -218,129 +250,135 @@ class TestControlRender:
**Mandatory reading:** `docs/testing_rendered_components.md`
**What you must master:**
+
- **`matches(actual, expected)`** - How to validate that an element matches your expectations
- **`find(ft, expected)`** - How to search for elements within an HTML tree
- **Predicates** - How to test patterns instead of exact values:
- - `Contains()`, `StartsWith()`, `DoesNotContain()`, `AnyValue()` for attributes
- - `Empty()`, `NoChildren()`, `AttributeForbidden()` for children
+ - `Contains()`, `StartsWith()`, `DoesNotContain()`, `AnyValue()` for attributes
+ - `Empty()`, `NoChildren()`, `AttributeForbidden()` for children
- **Error messages** - How to read `^^^` markers to understand differences
- **Key principle** - Test only what matters, ignore the rest
+- **MyFastHtml test helpers** - `TestObject`, `TestLabel`, `TestIcon`, `TestIconNotStr`, `TestCommand`, `TestScript`
**Without this reading, you cannot write correct render tests.**
---
-### **TEST FILE STRUCTURE**
-
----
-
#### **UTR-11.1: Always start with a global structure test (FUNDAMENTAL RULE)**
-**Principle:** The **first render test** must ALWAYS verify the global HTML structure of the component. This is the test that helps readers understand the general architecture.
+**Principle:** The **first render test** must ALWAYS verify the global HTML structure of the component. This is the test
+that helps readers understand the general architecture.
**Why:**
+
- Gives immediate overview of the structure
- Facilitates understanding for new contributors
- Quickly detects major structural changes
- Serves as living documentation of HTML architecture
**Test format:**
+
```python
def test_i_can_render_component_with_no_data(self, component):
- """Test that Component renders with correct global structure."""
- html = component.render()
- expected = Div(
- Div(id=f"{component.get_id()}-controller"), # controller
- Div(id=f"{component.get_id()}-header"), # header
- Div(id=f"{component.get_id()}-content"), # content
- id=component.get_id(),
- )
- assert matches(html, expected)
+ """Test that Component renders with correct global structure."""
+ html = component.render()
+ expected = Div(
+ Div(id=f"{component.get_id()}-controller"), # controller
+ Div(id=f"{component.get_id()}-header"), # header
+ Div(id=f"{component.get_id()}-content"), # content
+ id=component.get_id(),
+ )
+ assert matches(html, expected)
```
**Notes:**
+
- Simple test with only IDs of main sections
- Inline comments to identify each section
- No detailed verification of attributes (classes, content, etc.)
- This test must be the first in the `TestComponentRender` class
+**Naming exception:** This specific test does NOT follow the `test_i_can_xxx` pattern (UTR-5). Use a descriptive name like `test_empty_layout_is_rendered()` instead. All other render tests follow UTR-5 normally.
+
**Test order:**
+
1. **First test:** Global structure (UTR-11.1)
-2. **Following tests:** Details of each section (UTR-11.2 to UTR-11.11)
+2. **Following tests:** Details of each section (UTR-11.2 to UTR-11.14)
---
-#### **UTR-11.2: Break down complex tests into explicit steps**
-
-**Principle:** When a test verifies multiple levels of HTML nesting, break it down into numbered steps with explicit comments.
-
-**Why:**
-- Facilitates debugging (you know exactly which step fails)
-- Improves test readability
-- Allows validating structure level by level
-
-**Example:**
-```python
-def test_content_wrapper_when_tab_active(self, tabs_manager):
- """Test that content wrapper shows active tab content."""
- tab_id = tabs_manager.create_tab("Tab1", Div("My Content"))
- wrapper = tabs_manager._mk_tab_content_wrapper()
-
- # Step 1: Validate wrapper global structure
- expected = Div(
- Div(), # tab content, tested in step 2
- id=f"{tabs_manager.get_id()}-content-wrapper",
- cls=Contains("mf-tab-content-wrapper"),
- )
- assert matches(wrapper, expected)
-
- # Step 2: Extract and validate specific content
- tab_content = find_one(wrapper, Div(id=f"{tabs_manager.get_id()}-{tab_id}-content"))
- expected = Div(
- Div("My Content"), # <= actual content
- cls=Contains("mf-tab-content"),
- )
- assert matches(tab_content, expected)
-```
-
-**Pattern:**
-- Step 1: Global structure with empty `Div()` + comment for children tested after
-- Step 2+: Extraction with `find_one()` + detailed validation
-
----
-
-#### **UTR-11.3: Three-step pattern for simple tests**
+#### **UTR-11.2: Three-step pattern for simple tests**
**Principle:** For tests not requiring multi-level decomposition, use the standard three-step pattern.
**The three steps:**
+
1. **Extract the element to test** with `find_one()` or `find()` from the global render
2. **Define the expected structure** with `expected = ...`
3. **Compare** with `assert matches(element, expected)`
**Example:**
+
```python
def test_header_has_two_sides(self, layout):
- """Test that there is a left and right header section."""
- # Step 1: Extract the element to test
- header = find_one(layout.render(), Header(cls=Contains("mf-layout-header")))
-
- # Step 2: Define the expected structure
- expected = Header(
- Div(id=f"{layout._id}_hl"),
- Div(id=f"{layout._id}_hr"),
- )
-
- # Step 3: Compare
- assert matches(header, expected)
+ """Test that there is a left and right header section."""
+ # Step 1: Extract the element to test
+ header = find_one(layout.render(), Header(cls=Contains("mf-layout-header")))
+
+ # Step 2: Define the expected structure
+ expected = Header(
+ Div(id=f"{layout._id}_hl"),
+ Div(id=f"{layout._id}_hr"),
+ )
+
+ # Step 3: Compare
+ assert matches(header, expected)
```
----
+#### **UTR-11.3: Break down complex tests into explicit steps**
-### **HOW TO SEARCH FOR ELEMENTS**
+**Principle:** When a test verifies multiple levels of HTML nesting, break it down into numbered steps with explicit
+comments.
+
+**Why:**
+
+- Facilitates debugging (you know exactly which step fails)
+- Improves test readability
+- Allows validating structure level by level
+
+**Example:**
+
+```python
+def test_content_wrapper_when_tab_active(self, tabs_manager):
+ """Test that content wrapper shows active tab content."""
+ tab_id = tabs_manager.create_tab("Tab1", Div("My Content"))
+ wrapper = tabs_manager._mk_tab_content_wrapper()
+
+ # Step 1: Validate wrapper global structure
+ expected = Div(
+ Div(), # tab content, tested in step 2
+ id=f"{tabs_manager.get_id()}-content-wrapper",
+ cls=Contains("mf-tab-content-wrapper"),
+ )
+ assert matches(wrapper, expected)
+
+ # Step 2: Extract and validate specific content
+ tab_content = find_one(wrapper, Div(id=f"{tabs_manager.get_id()}-{tab_id}-content"))
+ expected = Div(
+ Div("My Content"), # <= actual content
+ cls=Contains("mf-tab-content"),
+ )
+ assert matches(tab_content, expected)
+```
+
+**Pattern:**
+
+- Step 1: Global structure with `Div()` + comment for children tested after
+- Step 2+: Extraction with `find_one()` + detailed validation
---
+
#### **UTR-11.4: Prefer searching by ID**
**Principle:** Always search for an element by its `id` when it has one, rather than by class or other attribute.
@@ -348,6 +386,7 @@ def test_header_has_two_sides(self, layout):
**Why:** More robust, faster, and targeted (an ID is unique).
**Example:**
+
```python
# ✅ GOOD - search by ID
drawer = find_one(layout.render(), Div(id=f"{layout._id}_ld"))
@@ -361,10 +400,12 @@ drawer = find_one(layout.render(), Div(cls=Contains("mf-layout-left-drawer")))
#### **UTR-11.5: Use `find_one()` vs `find()` based on context**
**Principle:**
+
- `find_one()`: When you search for a unique element and want to test its complete structure
- `find()`: When you search for multiple elements or want to count/verify their presence
**Examples:**
+
```python
# ✅ GOOD - find_one for unique structure
header = find_one(layout.render(), Header(cls=Contains("mf-layout-header")))
@@ -378,19 +419,17 @@ assert len(resizers) == 1, "Left drawer should contain exactly one resizer eleme
---
-### **HOW TO SPECIFY EXPECTED STRUCTURE**
-
----
-
#### **UTR-11.6: Always use `Contains()` for `cls` and `style` attributes**
**Principle:**
+
- For `cls`: CSS classes can be in any order. Test only important classes with `Contains()`.
- For `style`: CSS properties can be in any order. Test only important properties with `Contains()`.
**Why:** Avoids false negatives due to class/property order or spacing.
**Examples:**
+
```python
# ✅ GOOD - Contains for cls (one or more classes)
expected = Div(cls=Contains("mf-layout-drawer"))
@@ -410,67 +449,24 @@ expected = Div(style="width: 250px; overflow: hidden; display: flex;")
#### **UTR-11.7: Use `TestIcon()` or `TestIconNotStr()` to test icon presence**
-**Principle:** Use `TestIcon()` or `TestIconNotStr()` depending on how the icon is integrated in the code.
+**Principle:** Use `TestIcon()` or `TestIconNotStr()` depending on how the icon is integrated in the code. See `docs/testing_rendered_components.md` section 7 for full documentation.
-**Difference between the two:**
-- **`TestIcon("icon_name")`**: Searches for the pattern `
` (icon wrapped in a Div)
-- **`TestIconNotStr("icon_name")`**: Searches only for `` (icon alone, without wrapper)
+**How to choose — read the source code first:**
-**How to choose:**
-1. **Read the source code** to see how the icon is rendered
-2. If `mk.icon()` wraps the icon in a Div → use `TestIcon()` (default `wrapper="div"`)
-3. If `mk.label(..., icon=...)` wraps the icon in a Span → use `TestIcon(..., wrapper="span")`
-4. If the icon is directly included without wrapper → use `TestIconNotStr()`
-
-**The `wrapper` parameter:**
-
-Different `mk` helpers use different wrappers for icons:
-
-| Helper method | Wrapper element | TestIcon usage |
-|---------------|-----------------|----------------|
-| `mk.icon(my_icon)` | `
` | `TestIcon("name")` |
+| `mk.label("Text", icon=my_icon)` | `` | `TestIcon("name", wrapper="span")` |
+| Direct: `Div(my_icon)` | none | `TestIconNotStr("name")` |
**The `name` parameter:**
+
- **Exact name**: Use the exact import name (e.g., `TestIcon("panel_right_expand20_regular")`) to validate a specific icon
- **`name=""`** (empty string): Validates **any icon**
-**Examples:**
-
-```python
-# Example 1: Icon via mk.icon() - wrapper is Div (default)
-# Source code: mk.icon(panel_right_expand20_regular, size=20)
-# Rendered:
-expected = Header(
- Div(
- TestIcon("panel_right_expand20_regular"), # ✅ wrapper="div" (default)
- cls=Contains("flex", "gap-1")
- )
-)
-
-# Example 2: Icon via mk.label() - wrapper is Span
-# Source code: mk.label("Back", icon=chevron_left20_regular, command=...)
-# Rendered:
-back_icon = find_one(details, TestIcon("chevron_left20_regular", wrapper="span")) # ✅ wrapper="span"
-
-# Example 3: Direct icon (used without helper)
-# Source code: Span(dismiss_circle16_regular, cls="icon")
-# Rendered:
-expected = Span(
- TestIconNotStr("dismiss_circle16_regular"), # ✅ Without wrapper
- cls=Contains("icon")
-)
-
-# Example 4: Verify any wrapped icon
-expected = Div(
- TestIcon(""), # Accepts any wrapped icon
- cls=Contains("icon-wrapper")
-)
-```
-
**Debugging tip:**
If your test fails with `TestIcon()`:
+
1. Check if the wrapper is `` instead of `
` → try `wrapper="span"`
2. Check if there's no wrapper at all → try `TestIconNotStr()`
3. The error message will show you the actual structure
@@ -479,9 +475,8 @@ If your test fails with `TestIcon()`:
#### **UTR-11.8: Use `TestScript()` to test JavaScript scripts**
-**Principle:** Use `TestScript(code_fragment)` to verify JavaScript code presence. Test only the important fragment, not the complete script.
+**Principle:** Use `TestScript(code_fragment)` to verify JavaScript code presence. Test only the important fragment, not the complete script. See `docs/testing_rendered_components.md` section 9 for full documentation.
-**Example:**
```python
# ✅ GOOD - TestScript with important fragment
script = find_one(layout.render(), Script())
@@ -496,17 +491,20 @@ expected = Script("(function() { const id = '...'; initResizer(id); })()")
#### **UTR-11.9: Remove default `enctype` attribute when searching for Form elements**
-**Principle:** FastHTML's `Form()` component automatically adds `enctype="multipart/form-data"` as a default attribute. When using `find()` or `find_one()` to search for a Form, you must remove this attribute from the expected pattern.
+**Principle:** FastHTML's `Form()` component automatically adds `enctype="multipart/form-data"` as a default attribute.
+When using `find()` or `find_one()` to search for a Form, you must remove this attribute from the expected pattern.
**Why:** The actual Form in your component may not have this attribute, causing the match to fail.
**Problem:**
+
```python
# ❌ FAILS - Form() has default enctype that may not exist in actual form
form = find_one(details, Form()) # AssertionError: Found 0 elements
```
**Solution:**
+
```python
# ✅ WORKS - Remove the default enctype attribute
expected_form = Form()
@@ -515,72 +513,75 @@ form = find_one(details, expected_form)
```
**Complete example:**
+
```python
def test_column_details_contains_form(self, component):
- """Test that column details contains a form with required fields."""
- details = component.mk_column_details(col_def)
-
- # Create Form pattern and remove default enctype
- expected_form = Form()
- del expected_form.attrs["enctype"]
-
- form = find_one(details, expected_form)
- assert form is not None
-
- # Now search within the found form
- title_input = find_one(form, Input(name="title"))
- assert title_input is not None
+ """Test that column details contains a form with required fields."""
+ details = component.mk_column_details(col_def)
+
+ # Create Form pattern and remove default enctype
+ expected_form = Form()
+ del expected_form.attrs["enctype"]
+
+ form = find_one(details, expected_form)
+ assert form is not None
+
+ # Now search within the found form
+ title_input = find_one(form, Input(name="title"))
+ assert title_input is not None
```
-**Note:** This is a FastHTML-specific behavior. Always check for similar default attributes when tests fail unexpectedly with "Found 0 elements".
+**Note:** This is a FastHTML-specific behavior. Always check for similar default attributes when tests fail unexpectedly
+with "Found 0 elements".
---
-### **HOW TO DOCUMENT TESTS**
+#### **UTR-11.10: Test Documentation - Justify the choice of tested elements**
----
+**Principle:** In the test documentation section (after the description docstring), explain **why each tested element or
+attribute was chosen**. What makes it important for the functionality?
-#### **UTR-11.10: Justify the choice of tested elements**
-
-**Principle:** In the test documentation section (after the description docstring), explain **why each tested element or attribute was chosen**. What makes it important for the functionality?
-
-**What matters:** Not the exact wording ("Why these elements matter" vs "Why this test matters"), but **the explanation of why what is tested is relevant**.
+**What matters:** Not the exact wording ("Why these elements matter" vs "Why this test matters"), but **the explanation
+of why what is tested is relevant**.
**Examples:**
+
```python
def test_empty_layout_is_rendered(self, layout):
- """Test that Layout renders with all main structural sections.
+ """Test that Layout renders with all main structural sections.
+
+ Why these elements matter:
+ - 6 children: Verifies all main sections are rendered (header, drawers, main, footer, script)
+ - _id: Essential for layout identification and resizer initialization
+ - cls="mf-layout": Root CSS class for layout styling
+ """
+ expected = Div(...)
+ assert matches(layout.render(), expected)
- Why these elements matter:
- - 6 children: Verifies all main sections are rendered (header, drawers, main, footer, script)
- - _id: Essential for layout identification and resizer initialization
- - cls="mf-layout": Root CSS class for layout styling
- """
- expected = Div(...)
- assert matches(layout.render(), expected)
def test_left_drawer_is_rendered_when_open(self, layout):
- """Test that left drawer renders with correct classes when open.
+ """Test that left drawer renders with correct classes when open.
- Why these elements matter:
- - _id: Required for targeting drawer in HTMX updates
- - cls Contains "mf-layout-drawer": Base drawer class for styling
- - cls Contains "mf-layout-left-drawer": Left-specific drawer positioning
- - style Contains width: Drawer width must be applied for sizing
- """
- layout._state.left_drawer_open = True
- drawer = find_one(layout.render(), Div(id=f"{layout._id}_ld"))
-
- expected = Div(
- _id=f"{layout._id}_ld",
- cls=Contains("mf-layout-drawer", "mf-layout-left-drawer"),
- style=Contains("width: 250px")
- )
-
- assert matches(drawer, expected)
+ Why these elements matter:
+ - _id: Required for targeting drawer in HTMX updates
+ - cls Contains "mf-layout-drawer": Base drawer class for styling
+ - cls Contains "mf-layout-left-drawer": Left-specific drawer positioning
+ - style Contains width: Drawer width must be applied for sizing
+ """
+ layout._state.left_drawer_open = True
+ drawer = find_one(layout.render(), Div(id=f"{layout._id}_ld"))
+
+ expected = Div(
+ _id=f"{layout._id}_ld",
+ cls=Contains("mf-layout-drawer", "mf-layout-left-drawer"),
+ style=Contains("width: 250px")
+ )
+
+ assert matches(drawer, expected)
```
**Key points:**
+
- Explain why the attribute/element is important (functionality, HTMX, styling, etc.)
- No need to follow rigid wording
- What matters is the **justification of the choice**, not the format
@@ -589,9 +590,11 @@ def test_left_drawer_is_rendered_when_open(self, layout):
#### **UTR-11.11: Count tests with explicit messages**
-**Principle:** When you count elements with `assert len()`, ALWAYS add an explicit message explaining why this number is expected.
+**Principle:** When you count elements with `assert len()`, ALWAYS add an explicit message explaining why this number is
+expected.
**Example:**
+
```python
# ✅ GOOD - explanatory message
resizers = find(drawer, Div(cls=Contains("mf-resizer-left")))
@@ -606,72 +609,97 @@ assert len(resizers) == 1
---
-### **OTHER IMPORTANT RULES**
+#### **UTR-11.12: No inline comments in expected structures**
+
+**Principle:** Do NOT add comments on each line of the expected structure. The only exception is the global structure test (UTR-11.1) where inline comments identify each section.
+
+```python
+# ✅ GOOD - no inline noise
+expected = Div(
+ Div(id=f"{layout._id}-header"),
+ Div(id=f"{layout._id}-content"),
+ Div(id=f"{layout._id}-footer"),
+)
+
+# ❌ AVOID - inline comments everywhere
+expected = Div(
+ Div(id=f"{layout._id}-header"), # header
+ Div(id=f"{layout._id}-content"), # content
+ Div(id=f"{layout._id}-footer"), # footer
+)
+```
---
-**Mandatory render test rules:**
+#### **UTR-11.13: Use `TestObject(ComponentClass)` to test component presence**
-1. **Test naming**: Use descriptive names like `test_empty_layout_is_rendered()` not `test_layout_renders_with_all_sections()`
+**Principle:** When a component renders another component as a child, use `TestObject(ComponentClass)` to verify its presence without coupling to its internal rendering.
-2. **Documentation format**: Every render test MUST have a docstring with:
- - First line: Brief description of what is being tested
- - Blank line
- - Justification section explaining why tested elements matter (see UTR-11.10)
- - List of important elements/attributes being tested with explanations (in English)
+```python
+from myfasthtml.test.matcher import matches, find, TestObject
+from myfasthtml.controls.Search import Search
-3. **No inline comments**: Do NOT add comments on each line of the expected structure (except for structural clarification in global layout tests like `# left drawer`)
-
-4. **Component testing**: Use `TestObject(ComponentClass)` to test presence of components
-
-5. **Test organization for Controls**: Organize tests into thematic classes:
- - `TestControlBehaviour`: Tests for control behavior and logic
- - `TestControlRender`: Tests for control HTML rendering
-
-6. **Fixture usage**: In `TestControlRender`, use a pytest fixture to create the control instance:
- ```python
- class TestControlRender:
- @pytest.fixture
- def layout(self, root_instance):
- return Layout(root_instance, app_name="Test App")
-
- def test_something(self, layout):
- # layout is injected automatically
- ```
+# ✅ GOOD - test presence without coupling to internal rendering
+expected = Div(
+ TestObject(Search),
+ id=f"{toolbar._id}"
+)
+assert matches(toolbar.render(), expected)
+```
---
-#### **Summary: The 12 UTR-11 sub-rules**
+#### **UTR-11.14: Use pytest fixtures in `TestControlRender`**
+
+**Principle:** In `TestControlRender`, always use a pytest fixture to create the control instance. This avoids duplicating setup code across tests.
+
+```python
+class TestControlRender:
+ @pytest.fixture
+ def layout(self, root_instance):
+ return Layout(root_instance, app_name="Test App")
+
+ def test_empty_layout_is_rendered(self, layout):
+ # layout is injected automatically by pytest
+ assert matches(layout.render(), ...)
+```
+
+---
+
+#### **Summary: The 15 UTR-11 sub-rules**
**Prerequisite**
+
- **UTR-11.0**: ⭐⭐⭐ Read `docs/testing_rendered_components.md` (MANDATORY)
**Test file structure**
-- **UTR-11.1**: ⭐ Always start with a global structure test (FIRST TEST)
-- **UTR-11.2**: Break down complex tests into numbered steps
-- **UTR-11.3**: Three-step pattern for simple tests
+
+- **UTR-11.1**: ⭐ Always start with a global structure test (FIRST TEST, naming exception to UTR-5)
+- **UTR-11.2**: Three-step pattern for simple tests
+- **UTR-11.3**: Break down complex tests into numbered steps
**How to search**
+
- **UTR-11.4**: Prefer search by ID
- **UTR-11.5**: `find_one()` vs `find()` based on context
**How to specify**
+
- **UTR-11.6**: Always `Contains()` for `cls` and `style`
- **UTR-11.7**: `TestIcon()` or `TestIconNotStr()` to test icon presence
- **UTR-11.8**: `TestScript()` for JavaScript
- **UTR-11.9**: Remove default `enctype` from `Form()` patterns
+- **UTR-11.13**: `TestObject(ComponentClass)` to test component presence
**How to document**
+
- **UTR-11.10**: Justify the choice of tested elements
- **UTR-11.11**: Explicit messages for `assert len()`
----
+**Code style**
-**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 justification documentation (see UTR-11.10)
+- **UTR-11.12**: No inline comments in expected structures
+- **UTR-11.14**: Use pytest fixtures in `TestControlRender`
---
@@ -682,6 +710,7 @@ assert len(resizers) == 1
**Why:** Prevents writing tests based on incorrect assumptions about behavior.
**Example:**
+
```
Test: "content_is_cached_after_first_retrieval"
Flow: create_tab() → _add_or_update_tab() → state.ns_tabs_content[tab_id] = component
@@ -689,6 +718,7 @@ Conclusion: Cache is already filled after create_tab, test would be redundant
```
**Process:**
+
1. Identify the method being tested
2. Trace all method calls it makes
3. Identify state changes at each step
@@ -704,6 +734,7 @@ Conclusion: Cache is already filled after create_tab, test would be redundant
**Why:** More robust, clearer error messages, consistent with render test patterns.
**Examples:**
+
```python
# ❌ FRAGILE - string matching
result = component._dynamic_get_content("nonexistent_id")
@@ -721,11 +752,13 @@ assert matches(result, Div('Tab not found.'))
**Rule:** FastHTML elements use HTML attribute names, not Python parameter names.
**Key differences:**
+
- Use `attrs.get('class')` not `attrs.get('cls')`
- Use `attrs.get('id')` for the ID
- Prefer `matches()` with predicates to avoid direct attribute access
**Examples:**
+
```python
# ❌ WRONG - Python parameter name
classes = element.attrs.get('cls', '') # Returns None or ''
@@ -760,18 +793,21 @@ assert matches(element, expected)
**Rule:** When proposing a test plan, systematically identify tests that can be parameterized and propose them as such.
**When to parameterize:**
+
- Tests that follow the same pattern with different input values
- Tests that verify the same behavior for different sides/directions (left/right, up/down)
- Tests that check the same logic with different states (visible/hidden, enabled/disabled)
- Tests that validate the same method with different valid inputs
**How to identify candidates:**
+
1. Look for tests with similar names differing only by a value (e.g., `test_left_panel_...` and `test_right_panel_...`)
2. Look for tests that have identical structure but different parameters
3. Look for combinatorial scenarios (side × state combinations)
**How to propose:**
In your test plan, explicitly show:
+
1. The individual tests that would be written without parameterization
2. The parameterized version with all test cases
3. The reduction in test count
@@ -798,6 +834,7 @@ def test_i_can_toggle_panel_visibility(...)
```
**Benefits:**
+
- Reduces code duplication
- Makes it easier to add new test cases
- Improves maintainability
@@ -808,6 +845,7 @@ def test_i_can_toggle_panel_visibility(...)
## Managing Rules
To disable a specific rule, the user can say:
+
- "Disable UTR-4" (do not apply the rule about testing Python built-ins)
- "Enable UTR-4" (re-enable a previously disabled rule)
diff --git a/docs/testing_rendered_components.md b/docs/testing_rendered_components.md
index 8a480dc..83e2d7d 100644
--- a/docs/testing_rendered_components.md
+++ b/docs/testing_rendered_components.md
@@ -522,7 +522,254 @@ expected = Input(
matches(actual, expected)
```
-### 5. Combining matches() and find()
+
+### 5. Testing MyFastHtml Components with Test Helpers
+
+**Goal**: Understand why test helpers exist and how they simplify testing MyFastHtml controls.
+
+When testing components built with `mk` helpers (buttons, labels, icons), writing the expected pattern manually quickly becomes verbose. Consider testing a label with an icon:
+
+```python
+# Without test helpers - verbose and fragile
+from fastcore.basics import NotStr
+from fasthtml.common import Span
+from myfasthtml.test.matcher import matches, Regex
+
+actual = label_component.render()
+expected = Span(
+ Span(NotStr('