464 lines
14 KiB
Python
464 lines
14 KiB
Python
import json
|
|
import uuid
|
|
from dataclasses import dataclass
|
|
|
|
from bs4 import BeautifulSoup, Tag
|
|
from fastcore.xml import FT, to_xml
|
|
from fasthtml.common import FastHTML
|
|
from starlette.responses import Response
|
|
from starlette.testclient import TestClient
|
|
|
|
from myfasthtml.core.commands import mount_commands
|
|
|
|
|
|
@dataclass
|
|
class MyFT:
|
|
tag: str
|
|
attrs: dict
|
|
|
|
|
|
class TestableElement:
|
|
"""
|
|
Represents an HTML element that can be interacted with in tests.
|
|
|
|
This class will be used for future interactions like clicking elements
|
|
or verifying element properties.
|
|
"""
|
|
|
|
def __init__(self, client, source):
|
|
"""
|
|
Initialize a testable element.
|
|
|
|
Args:
|
|
client: The MyTestClient instance.
|
|
ft: The FastHTML element representation.
|
|
"""
|
|
self.client = client
|
|
if isinstance(source, str):
|
|
self.html_fragment = source
|
|
tag = BeautifulSoup(source, 'html.parser').find()
|
|
self.ft = MyFT(tag.name, tag.attrs)
|
|
elif isinstance(source, Tag):
|
|
self.html_fragment = str(source)
|
|
self.ft = MyFT(source.name, source.attrs)
|
|
elif isinstance(source, FT):
|
|
self.ft = source
|
|
self.html_fragment = to_xml(source).strip()
|
|
else:
|
|
raise ValueError(f"Invalid source '{source}' for TestableElement.")
|
|
|
|
def click(self):
|
|
"""Click the element (to be implemented)."""
|
|
return self._send_htmx_request()
|
|
|
|
def matches(self, ft):
|
|
"""Check if element matches given FastHTML element (to be implemented)."""
|
|
pass
|
|
|
|
def _send_htmx_request(self, json_data: dict | None = None, data: dict | None = None) -> Response:
|
|
"""
|
|
Simulates an HTMX request in Python for unit testing.
|
|
|
|
This function reads the 'hx-*' attributes from the FastHTML object
|
|
to determine the HTTP method, URL, headers, and body of the request,
|
|
then executes it via the TestClient.
|
|
|
|
Args:
|
|
data: (Optional) A dict for form data
|
|
(sends as 'application/x-www-form-urlencoded').
|
|
json_data: (Optional) A dict for JSON data
|
|
(sends as 'application/json').
|
|
Takes precedence over 'hx_vals'.
|
|
|
|
Returns:
|
|
The Response object from the simulated request.
|
|
"""
|
|
|
|
# The essential header for FastHTML (and HTMX) to identify the request
|
|
headers = {"HX-Request": "true"}
|
|
method = "GET" # HTMX defaults to GET if not specified
|
|
url = None
|
|
|
|
verbs = {
|
|
'hx_get': 'GET',
|
|
'hx_post': 'POST',
|
|
'hx_put': 'PUT',
|
|
'hx_delete': 'DELETE',
|
|
'hx_patch': 'PATCH',
|
|
}
|
|
|
|
# .props contains the kwargs passed to the object (e.g., hx_post="/url")
|
|
element_attrs = self.ft.attrs or {}
|
|
|
|
# Build the attributes
|
|
for key, value in element_attrs.items():
|
|
|
|
# sanitize the key
|
|
key = key.lower().strip()
|
|
if key.startswith('hx-'):
|
|
key = 'hx_' + key[3:]
|
|
|
|
if key in verbs:
|
|
# Verb attribute: defines the method and URL
|
|
method = verbs[key]
|
|
url = str(value)
|
|
|
|
elif key == 'hx_vals':
|
|
# hx_vals defines the JSON body, if not already provided by the test
|
|
if json_data is None:
|
|
if isinstance(value, str):
|
|
json_data = json.loads(value)
|
|
elif isinstance(value, dict):
|
|
json_data = value
|
|
|
|
elif key.startswith('hx_'):
|
|
# Any other hx_* attribute is converted to an HTTP header
|
|
# e.g.: 'hx_target' -> 'HX-Target'
|
|
header_name = '-'.join(p.capitalize() for p in key.split('_'))
|
|
headers[header_name] = str(value)
|
|
|
|
# Sanity check
|
|
if url is None:
|
|
raise ValueError(
|
|
f"The <{self.ft.tag}> element has no HTMX verb attribute "
|
|
"(e.g., hx_get, hx_post) to define a URL."
|
|
)
|
|
|
|
# Send the request
|
|
return self.client.send_request(method, url, headers=headers, data=data, json_data=json_data)
|
|
|
|
|
|
class MyTestClient:
|
|
"""
|
|
A test client helper for FastHTML applications that provides
|
|
a more user-friendly API for testing HTML responses.
|
|
|
|
This class wraps Starlette's TestClient and provides methods
|
|
to verify page content in a way similar to NiceGui's test fixtures.
|
|
"""
|
|
|
|
def __init__(self, app: FastHTML, parent_levels: int = 1):
|
|
"""
|
|
Initialize the test client.
|
|
|
|
Args:
|
|
app: The FastHTML application to test.
|
|
parent_levels: Number of parent levels to show in error messages (default: 1).
|
|
"""
|
|
self.app = app
|
|
self.client = TestClient(app)
|
|
self._content = None
|
|
self._soup = None
|
|
self._session = str(uuid.uuid4())
|
|
self.parent_levels = parent_levels
|
|
|
|
# make sure that the commands are mounted
|
|
mount_commands(self.app)
|
|
|
|
def open(self, path: str):
|
|
"""
|
|
Open a page and store its content for subsequent assertions.
|
|
|
|
Args:
|
|
path: The URL path to request (e.g., '/home', '/api/users').
|
|
|
|
Returns:
|
|
self: Returns the client instance for method chaining.
|
|
|
|
Raises:
|
|
AssertionError: If the response status code is not 200.
|
|
"""
|
|
|
|
res = self.client.get(path)
|
|
assert res.status_code == 200, (
|
|
f"Failed to open '{path}'. "
|
|
f"status code={res.status_code} : reason='{res.text}'"
|
|
)
|
|
|
|
self.set_content(res.text)
|
|
return self
|
|
|
|
def send_request(self, method: str, url: str, headers: dict = None, data=None, json_data=None):
|
|
json_data['session'] = self._session
|
|
res = self.client.request(
|
|
method,
|
|
url,
|
|
headers=headers,
|
|
data=data, # For form data
|
|
json=json_data # For JSON bodies (e.g., from hx_vals)
|
|
)
|
|
|
|
assert res.status_code == 200, (
|
|
f"Failed to send request '{method=}', {url=}. "
|
|
f"status code={res.status_code} : reason='{res.text}'"
|
|
)
|
|
|
|
self.set_content(res.text)
|
|
return self
|
|
|
|
def should_see(self, text: str):
|
|
"""
|
|
Assert that the given text is present in the visible page content.
|
|
|
|
This method parses the HTML and searches only in the visible text,
|
|
ignoring HTML tags and attributes.
|
|
|
|
Args:
|
|
text: The text string to search for (case-sensitive).
|
|
|
|
Returns:
|
|
self: Returns the client instance for method chaining.
|
|
|
|
Raises:
|
|
AssertionError: If the text is not found in the page content.
|
|
ValueError: If no page has been opened yet.
|
|
"""
|
|
if self._content is None:
|
|
raise ValueError(
|
|
"No page content available. Call open() before should_see()."
|
|
)
|
|
|
|
visible_text = self._soup.get_text()
|
|
|
|
if text not in visible_text:
|
|
# Provide a snippet of the actual content for debugging
|
|
snippet_length = 200
|
|
content_snippet = (
|
|
visible_text[:snippet_length] + "..."
|
|
if len(visible_text) > snippet_length
|
|
else visible_text
|
|
)
|
|
raise AssertionError(
|
|
f"Expected to see '{text}' in page content but it was not found.\n"
|
|
f"Visible content (first {snippet_length} chars): {content_snippet}"
|
|
)
|
|
|
|
return self
|
|
|
|
def should_not_see(self, text: str):
|
|
"""
|
|
Assert that the given text is NOT present in the visible page content.
|
|
|
|
This method parses the HTML and searches only in the visible text,
|
|
ignoring HTML tags and attributes.
|
|
|
|
Args:
|
|
text: The text string that should not be present (case-sensitive).
|
|
|
|
Returns:
|
|
self: Returns the client instance for method chaining.
|
|
|
|
Raises:
|
|
AssertionError: If the text is found in the page content.
|
|
ValueError: If no page has been opened yet.
|
|
"""
|
|
if self._content is None:
|
|
raise ValueError(
|
|
"No page content available. Call open() before should_not_see()."
|
|
)
|
|
|
|
visible_text = self._soup.get_text()
|
|
|
|
if text in visible_text:
|
|
element = self._find_visible_text_element(self._soup, text)
|
|
|
|
if element:
|
|
context = self._format_element_with_context(element, self.parent_levels)
|
|
error_msg = (
|
|
f"Expected NOT to see '{text}' in page content but it was found.\n"
|
|
f"Found in:\n{context}"
|
|
)
|
|
else:
|
|
error_msg = (
|
|
f"Expected NOT to see '{text}' in page content but it was found.\n"
|
|
f"Unable to locate the element containing this text."
|
|
)
|
|
|
|
raise AssertionError(error_msg)
|
|
|
|
return self
|
|
|
|
def find_element(self, selector: str):
|
|
"""
|
|
Find a single HTML element using a CSS selector.
|
|
|
|
This method searches for elements matching the given CSS selector.
|
|
It expects to find exactly one matching element.
|
|
|
|
Args:
|
|
selector: A CSS selector string (e.g., '#my-id', '.my-class', 'button.primary').
|
|
|
|
Returns:
|
|
TestableElement: A testable element wrapping the HTML fragment.
|
|
|
|
Raises:
|
|
ValueError: If no page has been opened yet.
|
|
AssertionError: If no element or multiple elements match the selector.
|
|
|
|
Examples:
|
|
element = client.open('/').find_element('#login-button')
|
|
element = client.find_element('button.primary')
|
|
"""
|
|
if self._content is None:
|
|
raise ValueError(
|
|
"No page content available. Call open() before find_element()."
|
|
)
|
|
|
|
results = self._soup.select(selector)
|
|
|
|
if len(results) == 0:
|
|
raise AssertionError(
|
|
f"No element found matching selector '{selector}'."
|
|
)
|
|
elif len(results) == 1:
|
|
return TestableElement(self, results[0])
|
|
else:
|
|
raise AssertionError(
|
|
f"Found {len(results)} elements matching selector '{selector}'. Expected exactly 1."
|
|
)
|
|
|
|
def get_content(self) -> str:
|
|
"""
|
|
Get the raw HTML content of the last opened page.
|
|
|
|
Returns:
|
|
The HTML content as a string, or None if no page has been opened.
|
|
"""
|
|
return self._content
|
|
|
|
def set_content(self, content: str):
|
|
"""
|
|
Set the HTML content and parse it with BeautifulSoup.
|
|
|
|
Args:
|
|
content: The HTML content string to set.
|
|
"""
|
|
self._content = content
|
|
self._soup = BeautifulSoup(content, 'html.parser')
|
|
|
|
@staticmethod
|
|
def _find_visible_text_element(soup, text: str):
|
|
"""
|
|
Find the first element containing the visible text.
|
|
|
|
This method traverses the BeautifulSoup tree to find the first element
|
|
whose visible text content (including descendants) contains the search text.
|
|
|
|
Args:
|
|
soup: BeautifulSoup object representing the parsed HTML.
|
|
text: The text to search for.
|
|
|
|
Returns:
|
|
BeautifulSoup element containing the text, or None if not found.
|
|
"""
|
|
# Traverse all elements in the document
|
|
for element in soup.descendants:
|
|
# Skip NavigableString nodes, we want Tag elements
|
|
if not isinstance(element, Tag):
|
|
continue
|
|
|
|
# Get visible text of this element and its descendants
|
|
element_text = element.get_text()
|
|
|
|
# Check if our search text is in this element's visible text
|
|
if text in element_text:
|
|
# Found it! But we want the smallest element containing the text
|
|
# So let's check if any of its children also contain the text
|
|
found_in_child = False
|
|
|
|
for child in element.children:
|
|
if isinstance(child, Tag) and text in child.get_text():
|
|
found_in_child = True
|
|
break
|
|
|
|
# If no child contains the text, this is our target element
|
|
if not found_in_child:
|
|
return element
|
|
|
|
return None
|
|
|
|
@staticmethod
|
|
def _indent_html(html_str: str, indent: int = 2):
|
|
"""
|
|
Add indentation to HTML string.
|
|
|
|
Args:
|
|
html_str: HTML string to indent.
|
|
indent: Number of spaces for indentation.
|
|
|
|
Returns:
|
|
str: Indented HTML string.
|
|
"""
|
|
lines = html_str.split('\n')
|
|
indented_lines = [' ' * indent + line for line in lines if line.strip()]
|
|
return '\n'.join(indented_lines)
|
|
|
|
def _format_element_with_context(self, element, parent_levels: int):
|
|
"""
|
|
Format an element with its parent context for display.
|
|
|
|
Args:
|
|
element: BeautifulSoup element to format.
|
|
parent_levels: Number of parent levels to include.
|
|
|
|
Returns:
|
|
str: Formatted HTML string with indentation.
|
|
"""
|
|
# Collect the element and its parents
|
|
elements_to_show = [element]
|
|
current = element
|
|
|
|
for _ in range(parent_levels):
|
|
if current.parent and current.parent.name: # Skip NavigableString parents
|
|
elements_to_show.insert(0, current.parent)
|
|
current = current.parent
|
|
else:
|
|
break
|
|
|
|
# Format the top-level element with proper indentation
|
|
if len(elements_to_show) == 1:
|
|
return self._indent_html(str(element), indent=2)
|
|
|
|
# Build the nested structure
|
|
result = self._build_nested_context(elements_to_show, element)
|
|
return self._indent_html(result, indent=2)
|
|
|
|
def _build_nested_context(self, elements_chain, target_element):
|
|
"""
|
|
Build nested HTML context showing parents and target element.
|
|
|
|
Args:
|
|
elements_chain: List of elements from outermost parent to target.
|
|
target_element: The element that contains the searched text.
|
|
|
|
Returns:
|
|
str: Nested HTML structure.
|
|
"""
|
|
if len(elements_chain) == 1:
|
|
return str(target_element)
|
|
|
|
# Get the outermost element
|
|
outer = elements_chain[0]
|
|
|
|
# Start with opening tag
|
|
result = f"<{outer.name}"
|
|
if outer.attrs:
|
|
attrs = ' '.join(f'{k}="{v}"' if not isinstance(v, list) else f'{k}="{" ".join(v)}"'
|
|
for k, v in outer.attrs.items())
|
|
result += f" {attrs}"
|
|
result += ">\n"
|
|
|
|
# Add nested content
|
|
if len(elements_chain) == 2:
|
|
# This is the target element
|
|
result += self._indent_html(str(target_element), indent=2) + "\n"
|
|
else:
|
|
# Recursive call for deeper nesting
|
|
nested = self._build_nested_context(elements_chain[1:], target_element)
|
|
result += self._indent_html(nested, indent=2) + "\n"
|
|
|
|
# Closing tag
|
|
result += f"</{outer.name}>"
|
|
|
|
return result
|