Skip to content

Latest commit

 

History

History
272 lines (161 loc) · 11.9 KB

QElement.md

File metadata and controls

272 lines (161 loc) · 11.9 KB
Raw

Quixote API: QElement

QElement instances represent individual HTML elements. You'll use their properties to make assertions about your elements. For properties that don't exist yet, use element.getRawStyle().

Properties

Use these properties to make assertions about the element.

Compatibility Note: We make every effort to ensure that properties work identically across browsers. If you discover a cross-browser incompatibility that doesn't correspond to an actual, visible difference, please file an issue.

Pixel Rounding Note: Browsers handle pixel rounding in different ways. We consider pixel values to be the same if they're within 0.5px of each other. If you have rounding errors that are greater than 0.5px, make sure your test browsers are set to a zoom level of 100%. Zooming can exaggerate rounding errors.

Positions and Sizes

Stability: 3 - Stable

These properties include padding and borders (if any), but not margins. They can also be "not rendered" if the element has the display: none property or if the element isn't in the DOM. (For more exact rendering assertions, use the element rendering properties below.)

Example:

logo.height.should.equal(10);           // The logo height should equal 10 pixels.
logo.left.should.equal(navbar.height);  // The logo's left edge should be the same as the navbar's left edge.

Element Rendering

Stability: 3 - Stable

This property describes whether an element is rendered. It can include padding and borders, but it never includes margins. We check these things about the element:

  • Whether it's part of the DOM (elements that have been removed from the DOM aren't rendered)
  • Its width and height (elements with no width or height aren't rendered)
  • Its position on the page (things you can scroll to are rendered, but things hidden off the top or left of the page aren't)
  • The display property
  • The clip property
  • The overflow property

Note that an element can be rendered, but still be invisible to the user—for example, if it's composed entirely of transparent pixels, or if the visibility: hidden property is set, or some other reason.

  • element.render (ElementRender) Whether any part of the element is rendered.
  • element.render.top (PositionDescriptor) Top edge of the rendered part of the element.
  • element.render.right (PositionDescriptor) Right edge of the rendered part of the element.
  • element.render.bottom (PositionDescriptor) Bottom edge of the rendered part of the element.
  • element.render.left (PositionDescriptor) Left edge of the rendered part of the element.
  • element.render.center (PositionDescriptor) Horizontal center: midway between right and left.
  • element.render.middle (PositionDescriptor) Vertical middle: midway between the top and bottom.
  • element.render.width (SizeDescriptor) Width of the rendered part of the element.
  • element.render.height (SizeDescriptor) Height of the rendered part of the element.

Example: "The caption doesn't break out of the bottom of the content area."

caption.render.bottom.should.equal(content.bottom);

Compatibility Notes:

  • We don't support the clip-path property at this time. It's so complicated that full support is unlikely.

  • We don't support the overflow: clip property at this time, but we might in the future. As of April 2020, overflow: clip is still experimental and no browsers support it.

  • We don't support the overflow: overlay property and probably never will. It's deprecated.

  • The element.render properties don't work on IE 8. This is due to bugs in IE 8's reporting of the clip property. You can check for IE 8's broken behavior with the quixote.browser.misreportsClipAutoProperty() browser detect.

  • Some browsers, such as IE 11 and Chrome Mobile 44, misreport the value of the clip property under certain circumstances. This could cause the element.render properties to throw an error. You can check for this broken behavior with the quixote.browser.misreportsAutoValuesInClipProperty() browser detect.

Methods

element.getRawStyle()

Stability: 3 - Stable

Determine how the browser is actually rendering an element's style. This uses getComputedStyle() under the covers. (On IE 8, it uses currentStyle).

style = element.getRawStyle(property)

  • style (string) The browser's computed style, or an empty string if the style wasn't recognized.

  • property (string) The name of the property to retrieve. Should always be written in kebab-case, even on IE 8.

Example: var fontSize = element.getRawStyle("font-size");

Compatibility Note: getRawStyle does not attempt to resolve cross-browser differences, with two exceptions:

  • IE 8 uses currentStyle rather than getComputedStyle(), and kebab-case property names are converted to camelCase to match currentStyle's expectation.
  • Different browsers return null, undefined, or "" when a property can't be found. Quixote always returns "".

Compatibility Note: When using getRawStyle("font-size"), be aware that Mobile Safari may increase the size of small fonts. (You can prevent this behavior by using -webkit-text-size-adjust: 100%; in your CSS.) You can detect this behavior by using quixote.browser.enlargesFonts().

element.getRawPosition()

Stability: 3 - Stable

Determine where an element is displayed within the frame viewport, as computed by the browser. This uses getBoundingClientRect() under the covers. Note that scrolling the document will cause the position to change. You can use QFrame.getRawScrollPosition() to compensate for the effect of scrolling.

position = element.getRawPosition()

  • position (object) The position of the element relative to the top-left corner of the viewport. In other words, if you scroll the document down 10 pixels, top will be 10 pixels larger. All values include border and padding, but not margin.
    • top (number) top edge
    • right (number) right edge
    • bottom (number) bottom edge
    • left (number) left edge
    • width (number) width (right edge minus left edge)
    • height (number) height (bottom edge minus top edge)

Example: var top = element.getRawPosition().top;

Compatibility Note: getRawPosition() does not attempt to resolve cross-browser differences, with one exception:

  • IE 8's getBoundingClientRect() does not have width or height properties, but getRawPosition() calculates them from the other properties.

element.calculatePixelValue()

Stability: 3 - Stable

Convert a CSS length string, such as 12em, to the corresponding number of pixels. The calculation is provided by the browser and takes into account all styles currently in effect on the element.

pixels = element.calculatePixelValue(length)

  • pixels (number) The number of pixels in the length.

  • length (string) A CSS length string. Negative values are supported.

Compatibility Note: IE 8 and IE 11 round the pixels result to the nearest integer value. You can detect this behavior by using quixote.browser.roundsOffPixelCalculations().

element.add()

Stability: 3 - Stable

Create an element and append it as a child of this element. Throws an exception unless exactly one element is created. (But that one element may contain children.)

child = element.add(html, nickname)

  • child (QElement) The element you created.

  • html (string) HTML for your element.

  • nickname (optional string) The name to use when describing your element in error messages. Defaults to the element ID, class names, or tag name, in that order.

Example: var foo = element.add("<p>foo</p>", "foo");

element.remove()

Stability: 3 - Stable

Remove the element from the DOM.

element.remove()

element.parent()

Stability: 3 - Stable

Get the element's parent element.

parent = element.parent(nickname)

  • parent (QElement or null) The parent element. Null if this element is the frame's body element or if this element has been removed from the DOM.

  • nickname (optional string) The name to use when describing your element in error messages. Defaults to the element ID, class names, or tag name, in that order.

element.contains()

Stability: 3 - Stable

Determine if this element contains another element.

isContained = element.contains(otherElement)

  • isContained (boolean) True if element is an ancestor of otherElement or if they are the same element. False otherwise.

  • otherElement (QElement) The possible child element to check.

element.toDomElement()

Stability: 3 - Stable

Retrieve the underlying HTMLElement DOM element for the frame.

dom = element.toDomElement()

Deprecated Methods

element.assert()

Stability: 0 - Deprecated

Deprecation Warning: This method may be removed in a future release. Use QElement properties' should assertions instead.

Check whether the element's properties match a set of expected values. If they match, nothing happens; if they don't match, this method throws an exception explaining the difference.

element.assert(expected, message)

  • expected (object) An object containing one or more QElement properties (top, right, etc.) as keys, along with the expected value as another property or a hard-coded value.

  • message (optional string) A message to include when the assertion fails and an exception is thrown.

Example:

element.assert({
  top: 13,                   // compare to a hard-coded value
  bottom: otherElement.top   // compare to another descriptor
});

element.diff()

Stability: 0 - Deprecated

Deprecation Warning: This method may be removed in a future release. Use QElement properties' should assertions instead.

Compare the element's properties to a set of expected values. This is the same as QElement.assert(), except that it returns a string rather than throwing an exception.

diff = element.diff(expected)

  • diff (string) A human-readable description of any differences found, or an empty string if none.

  • expected (object) An object containing one or more QElement properties (top, right, etc.) as keys, along with the expected value as another property or hard-coded value.