Nodes and forms¶
Result set¶
-
class
ftw.testbrowser.nodes.
Nodes
(*args, **kwargs)¶ Bases:
list
A list of HTML nodes. This is used as result set when doing queries (css / xpath) on the HTML document. It acts as a list.
-
css
(*args, **kwargs)¶ Find nodes by a css expression which are within one of the nodes in this result set. The resulting nodes are merged into a new result set.
Parameters: css_selector (string) – The CSS selector. Returns: Object containg matches. Return type: ftw.testbrowser.nodes.Nodes
-
find
(*args, **kwargs)¶ Find a elements by text. The elements are searched within each node of the current result set.
The method looks for: - a link with this text (normalized, including subelements’ texts) - a field which has a label with this text - a button which has a label with this text
Parameters: text (string) – The text to be looked for. Returns: A list of the parent of each node in the current result set. Return type: ftw.testbrowser.nodes.Nodes
-
first
¶ The first element of the list.
Raises: ftw.testbrowser.exceptions.NoElementFound
-
first_or_none
¶ The first element of the list or
None
if the list is empty.
-
getparents
()¶ Returns a list of each node’s parent.
Returns: The parent of each node of the current result set. Return type: ftw.testbrowser.nodes.Nodes
-
raw_text
¶ A list of all
raw_text
properties of this result set.Returns: A list of raw text Return type: list of string
-
text
¶ A list of all
text
properties of this result set.Returns: A list of text Return type: list of string
-
text_content
()¶ Returns a list with the text content of each node of this result set.
Returns: A list of the text_content of each node. Return type: list
-
xpath
(*args, **kwargs)¶ Find nodes by an xpath expression which are within one of the nodes in this result set. The resulting nodes are merged into a new result set.
Parameters: xpath_selector (string) – The xpath selector. Returns: Object containg matches. Return type: ftw.testbrowser.nodes.Nodes
-
Node wrappers¶
Node wrappers wrap the standard lxml elements and extend them with some useful methods so that it is nicely integrated in the ftw.testbrowser behavior.
-
class
ftw.testbrowser.nodes.
NodeWrapper
(node, browser)¶ Bases:
object
NodeWrapper is the default wrapper class in which each element will be wrapped for use in ftw.testbrowser. It wraps the elements returned by lxml and redirects calls if it does not overload them.
There are more specific node wrapper classes for some elements.
-
browser
¶ The current browser instance.
-
classes
¶ A list of css-classes of this element.
-
contains
(other)¶ Test whether the passed other node is contained in the current node.
Parameters: other ( ftw.testbrowser.nodes.NodeWrapper
) – The other node.Returns: True when other is within self. Return type: boolean
-
css
(*args, **kwargs)¶ Find nodes within this node by a css selector.
Parameters: css_selector (string) – The CSS selector. Returns: Object containg matches. Return type: ftw.testbrowser.nodes.Nodes
-
find
(text)¶ Find an element by text within the current node.
The method looks for: - a link with this text (normalized, including subelements’ texts) - a field which has a label with this text - a button which has a label with this text
Parameters: - text (string) – The text to be looked for.
- within (
ftw.testbrowser.nodes.NodeWrapper
.) – A node object for limiting the scope of the search.
Returns: A single node object or None if nothing matches.
Return type:
-
innerHTML
¶ The unmodified HTML content of the current node. The HTML-Tag of the current node is not included.
Returns: HTML Return type: unicode
-
iterlinks
(*args, **kwargs)¶ Iterate over all links in this node. Each link is represented as a tuple with node, attribute, link, pos.
-
normalized_innerHTML
¶ The whitespace-normalized HTML content of the current node. The HTML-Tag of the current node is not included. All series of whitespaces (including non-breaking spaces) are replaced with a single space.
Returns: HTML Return type: unicode
-
normalized_outerHTML
¶ The whitespace-normalized HTML of the current node and its children. The HTML-Tag of the current node is included. All series of whitespaces (including non-breaking spaces) are replaced with a single space.
Returns: HTML Return type: unicode
-
outerHTML
¶ The whitespace-normalized HTML of the current node and its children. The HTML-Tag of the current node is included.
Returns: HTML Return type: unicode
-
parent
(css=None, xpath=None)¶ Find the nearest parent which (optionally) does match a css or xpath selector.
If parent is called without an argument the first parent is returned.
Examples:
browser.css('.foo > .bar').first.parent('#content') # equals browser.css('.foo > .bar').first.parent(xpath='*[@id="content"]')
Parameters: - css (string) – The css selector.
- xpath (string) – The xpath selector.
Returns: The parent node.
Return type:
-
raw_text
¶ The original lxml raw text of this node.
Returns: Original lxml raw text. Return type: unicode
-
text
¶ Returns the whitespace-normalized text of the current node. This includes the text of each node within this node recursively. All whitespaces are reduced to a single space each, including newlines within the text.
HTML line breaks (<br />) are turned into a single newlineand paragraphs (<p></p>) and with two newlines, although the end of the string is stripped.
For having the original lxml raw text, use
raw_text
. .. seealso::ftw.testbrowser.nodes.NodeWrapper.raw_text()
Returns: The whitespace normalized text content. Return type: unicode
-
text_content
()¶ Returns the text content of the current node, including the text content of each containing node recursively.
Returns: The text content. Return type: unicode
-
within
(container)¶ Test whether the passed other node contains the current node.
Parameters: other ( ftw.testbrowser.nodes.NodeWrapper
) – The other node.Returns: True when self is within other. Return type: boolean
-
xpath
(*args, **kwargs)¶ Find nodes within this node by a css selector.
Parameters: css_selector (string) – The CSS selector. Returns: Object containg matches. Return type: ftw.testbrowser.nodes.Nodes
-
-
class
ftw.testbrowser.nodes.
LinkNode
(node, browser)¶ Bases:
ftw.testbrowser.nodes.NodeWrapper
Wrapps an <a> node.
-
click
()¶ Clicks on the link, which opens the target in the current browser.
-
-
class
ftw.testbrowser.nodes.
DefinitionListNode
(node, browser)¶ Bases:
ftw.testbrowser.nodes.NodeWrapper
Wrapps a <dl> node.
-
definitions
¶ Returns the normalized text of each <dd>-tag of this definition list.
Returns: A list of text of each <dd>-node. Return type: list of unicode
-
items
()¶ Returns a mapping (list with tuples) from <dt>-tags to <dd>-tags of this definition list.
Returns: a dict where the key is the <dt>-node and the value is the <dd>-node. Return type: dict
-
items_text
()¶ Returns a terms (<dt>) to definition (<dd>) mapping as list with tuples, each as normalized text.
Returns: key is the text of the <dt>-node, value is the text of the <dd>-node. Return type: dict
-
keys
()¶ Returns all <dt>-tags which are direct children of this definition list.
Returns: A list of <dt>-tags. Return type: ftw.testbrowser.nodes.Nodes
-
terms
¶ Returns the normalized text of each <dt>-tag of this definition list.
Returns: A list of text of each <dt>-node. Return type: list of unicode
-
text_to_nodes
()¶ Returns a dict with a mapping of text-terms to <dd>-nodes.
Returns: key is the text of the <dt>-node, value is the <dd>-node. Return type: dict
-
values
()¶ Returns all <dd>-tags which are direct children of this definition list.
Returns: A list of <dd>-tags. Return type: ftw.testbrowser.nodes.Nodes
-
Forms, fields and widgets¶
-
class
ftw.testbrowser.form.
Form
(node, browser)¶ Bases:
ftw.testbrowser.nodes.NodeWrapper
-
action_url
¶ The full qualified URL to send the form to. This should imitate normal browser behavior:
If the action is full qualified, use it as it is. If the action is relative, make it absolute by joining it with the page’s base URL. If there is no action, the action is the current page URL.
The page’s base URL can be set in the HTML document with a
<base>
-tag, otherwise the page URL is used.
-
field_label_to_name
(label)¶ Accepts a field label (or a field name) and returns the field name of the field.
Parameters: label (string) – The label of the field. Returns: The field name of the field. Return type: string
-
field_labels
¶ A list of label texts and field names of each field in this form.
The list contains the whitespace normalized label text of each field. If there is no label or it has an empty text, the fieldname is used instead.
Returns: A list of label texts (and field names). Return type: list of strings
-
field_labels_to_names
(values)¶ Accepts a dict and converts its field labels (keys) to field names.
Parameters: - values (dict) – A dict of values where the keys are field labels.
- values – A dict of values where the keys are field names.
Return type:
-
fill
(values)¶ Accepts a dict, where the key is the name or the label of a field and the value is its new value and fills the form with theese values.
Parameters: values (dict) – The key is the label or input-name and the value is the value to set. Returns: The form node. Return type: ftw.testbrowser.form.Form
Finds a button of with a specific label in this form.
Parameters: label (string) – The label of the button. Returns: The button node Return type: ftw.testbrowser.nodes.NodeWrapper
-
find_field
(*args, **kwargs)¶ Finds and returns a field by label or name.
Parameters: label_or_name (string) – The label or the name of the field. Returns: The field node Return type: ftw.testbrowser.nodes.NodeWrapper
Returns all submit buttons of this form.
Returns: a list of submit buttons Return type: ftw.testbrowser.nodes.Nodes
offtw.testbrowser.form.SubmitButton
of
-
find_widget
(label)¶ Finds a Plone widget (div.field) in a form.
Parameters: label (string) – The label of the widget. Returns: Returns the field node or None. Return type: ftw.testbrowser.nodes.NodeWrapper
-
inputs
¶ Returns a list of all input nodes of this form.
Returns: All input nodes Return type: ftw.testbrowser.nodes.Nodes
-
save
()¶ Clicks on the “Save” button in this form.
-
submit
(button=None)¶ Submits this form by clicking on the first submit button. The behavior of click the first submit button is what browser usually do and may not get the expected results.
It might be more save to click the primary button specificall:
browser.find('Save').click() # or form.save()
See also
-
values
¶ Returns the lxml FieldsDict of this form.
Returns: lxml fields dict Return type: lxml.html.FieldsDict
-
-
class
ftw.testbrowser.form.
TextAreaField
(node, browser)¶ Bases:
ftw.testbrowser.nodes.NodeWrapper
The TextAreaField node wrapper wraps a text area field and makes sure that the TinyMCE widget finds its label, since the markup of the TinyMCE widget is not standard.
-
class
ftw.testbrowser.form.
SubmitButton
(node, browser)¶ Bases:
ftw.testbrowser.nodes.NodeWrapper
Wraps a submit button and makes it clickable.
-
click
()¶ Click on this submit button, which makes the form submit with this button.
-
form
¶ Returns the form of which this button is parent. It returns the first form node if it is a nested form.
Returns: the form node Return type: ftw.testbrowser.form.Form
-
Tables¶
-
class
ftw.testbrowser.table.
Table
(node, browser)¶ Bases:
ftw.testbrowser.nodes.NodeWrapper
Represents a
table
tag.-
body_rows
¶ All body rows of this table. Body rows are those rows which are neither heading rows nor footer rows.
Returns: A list of body rows which are part of this table. Return type: ftw.testbrowser.nodes.Nodes
-
cells
¶ All cells of this table.
Returns: A list of cells which are part of this table. Return type: ftw.testbrowser.nodes.Nodes
-
column
(index_or_titles, head=True, body=True, foot=True, head_offset=0, as_text=True)¶ Returns a list of values of a specific column. The column may be identified by its index (integer) or by the title (string).
Parameters: - index_or_titles (int or string or list of strings) – Index or title of column
- head (boolean (Default:
True
)) – Include head rows. - body (boolean (Default:
True
)) – Include body rows. - foot (boolean (Default:
True
)) – Include foot rows. - head_offset (int (Default:
0
)) – Offset for the header for removing header rows. - as_text (Boolean (Default:
True
)) – Converts cell values to text.
Returns: A list of lists of texts.
Return type: list
-
dicts
(body=True, foot=True, head_offset=0, as_text=True)¶ Returns a list of dicts, where each dict is a row (of either table body or table foot). The keys of the row dicts are the table headings and the values are the cell texts. Cells with colspan are repeated.
Parameters: - body (boolean (Default:
True
)) – Include body rows. - foot (boolean (Default:
True
)) – Include foot rows. - head_offset (int (Default:
0
)) – Offset for the header for removing header rows. - as_text (Boolean (Default:
True
)) – Converts cell values to text.
Returns: A list of lists of texts.
Return type: list
- body (boolean (Default:
-
filter_unfamiliars
(nodes)¶ Returns all nodes from the
nodes
list which are part of this table, filtering all other nodes (unfamiliars).Parameters: nodes – The list of nodes to filter. Returns: The filtered list of nodes. Return type: ftw.testbrowser.nodes.Nodes
-
find
(text)¶ Find a cell of this table by text. When nothing is found, it falls back to the default
find
behavior.Parameters: text (string) – The text to be looked for. Returns: A single node object or None if nothing matches. Return type: ftw.testbrowser.nodes.NodeWrapper
-
foot_rows
¶ All footer rows of this table. Footer rows are those rows (
tr
) which are within thetfoot
tag.Returns: A list of footer rows. Return type: ftw.testbrowser.nodes.Nodes
-
get_rows
(head=False, body=False, foot=False, head_offset=0)¶ Returns merged head, body or foot rows. Set the keyword arguments to
True
for selecting the type of rows.Parameters: - head (boolean (Default:
False
)) – Selects head rows. - body (boolean (Default:
False
)) – Selects body rows. - foot (boolean (Default:
False
)) – Selects foot rows. - head_offset (int (Default:
0
)) – Offset for the header for removing header rows.
Returns: A list of rows which are part of this table.
Return type: - head (boolean (Default:
-
get_titles
(head_offset=0)¶ Returns the titles (thead) of the table. If there are multiple table head rows, the cells of the rows are merged per column (with newline as separator).
Parameters: head_offset (int (Default: 0
)) – Offset for the header for removing header rows.Returns: A list of table head texts per column. Return type: list
-
head_rows
¶ All heading rows of this table. Heading rows are those rows (
tr
) which are within thethead
tag.Returns: A list of heading rows. Return type: ftw.testbrowser.nodes.Nodes
-
is_familiar
(node)¶ Returns
True
whennode
is a component of the this table. ReturnsFalse
whennode
is a table component but is part of a nested table.Parameters: node ( ftw.testbrowser.nodes.NodeWrapper
) – The node to check.Returns: whether node
is part of this tableReturn type: boolean
-
lists
(head=True, body=True, foot=True, head_offset=0, as_text=True)¶ Returns a list of lists, where each list represents a row and contains the texts of the cells. Cells with colspan are repeated (padding) so that row lengths are equal.
Parameters: - head (boolean (Default:
True
)) – Include head rows. - body (boolean (Default:
True
)) – Include body rows. - foot (boolean (Default:
True
)) – Include foot rows. - head_offset (int (Default:
0
)) – Offset for the header for removing header rows. - as_text (Boolean (Default:
True
)) – Converts cell values to text.
Returns: A list of lists of texts.
Return type: list
- head (boolean (Default:
-
rows
¶ All rows of this table.
Returns: A list of rows which are part of this table. Return type: ftw.testbrowser.nodes.Nodes
-
titles
¶ Returns the titles (thead) of the table. If there are multiple table head rows, the cells of the rows are merged per column (with newline as separator).
Returns: A list of table head texts per column. Return type: list
-
-
class
ftw.testbrowser.table.
TableCell
(node, browser)¶ Bases:
ftw.testbrowser.table.TableComponent
Represents a table cell (
td
orth
).-
row
¶ Returns the row (
tr
node) of this cell.Returns: The row node. Return type: ftw.testbrowser.table.TableRow
-
-
class
ftw.testbrowser.table.
TableComponent
(node, browser)¶ Bases:
ftw.testbrowser.nodes.NodeWrapper
Represents any component of a table tag. This includes: ‘colgroup’, ‘col’, ‘thead’, ‘tbody’, ‘tfoot’, ‘tr’, ‘td’, ‘th’
-
table
¶ Returns the table of which this button is parent. It returns the first table node if it is a nested table.
Returns: the table node Return type: ftw.testbrowser.table.Table
-
-
class
ftw.testbrowser.table.
TableRow
(node, browser)¶ Bases:
ftw.testbrowser.table.TableComponent
Represents a table row (
tr
).-
cells
¶ The cell nodes of this row.
Returns: A Node
list of cell nodes.Return type: ftw.testbrowser.nodes.Nodes
-
-
ftw.testbrowser.table.
colspan_padded_text
(row)¶ Returns a list with the normalized_text of each cell of the
row
, but adds empty padding-cells for cells with a colspan.Parameters: node ( ftw.testbrowser.nodes.TableRow
) – The row node.Returns: A list of cell texts Return type: list