quixote

# Quixote API: `QElement` * [Back to overview README](../README.md) * [Back to API overview](api.md) `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()`](#elementgetrawstyle). ## 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](#element-rendering) below.) * `element.top (`[`PositionDescriptor`](PositionDescriptor.md)`)` The top edge of the element. * `element.right (`[`PositionDescriptor`](PositionDescriptor.md)`)` The right edge of the element. * `element.bottom (`[`PositionDescriptor`](PositionDescriptor.md)`)` The bottom edge of the element. * `element.left (`[`PositionDescriptor`](PositionDescriptor.md)`)` The left edge of the element. * `element.center (`[`PositionDescriptor`](PositionDescriptor.md)`)` Horizontal center: midway between right and left. * `element.middle (`[`PositionDescriptor`](PositionDescriptor.md)`)` Vertical middle: midway between the top and bottom. * `element.width (`[`SizeDescriptor`](SizeDescriptor.md)`)` Width of the element. * `element.height (`[`SizeDescriptor`](SizeDescriptor.md)`)` Height of the element. Example: ```javascript 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`](ElementRender.md)`)` Whether any part of the element is rendered. * `element.render.top (`[`PositionDescriptor`](PositionDescriptor.md)`)` Top edge of the rendered part of the element. * `element.render.right (`[`PositionDescriptor`](PositionDescriptor.md)`)` Right edge of the rendered part of the element. * `element.render.bottom (`[`PositionDescriptor`](PositionDescriptor.md)`)` Bottom edge of the rendered part of the element. * `element.render.left (`[`PositionDescriptor`](PositionDescriptor.md)`)` Left edge of the rendered part of the element. * `element.render.center (`[`PositionDescriptor`](PositionDescriptor.md)`)` Horizontal center: midway between right and left. * `element.render.middle (`[`PositionDescriptor`](PositionDescriptor.md)`)` Vertical middle: midway between the top and bottom. * `element.render.width (`[`SizeDescriptor`](SizeDescriptor.md)`)` Width of the rendered part of the element. * `element.render.height (`[`SizeDescriptor`](SizeDescriptor.md)`)` Height of the rendered part of the element. Example: "The caption doesn't break out of the bottom of the content area." ```javascript 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()`](quixote.md#quixotebrowser) 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()`](quixote.md#quixotebrowser) browser detect. ## Methods ### element.getRawStyle() ``` Stability: 3 - Stable ``` Determine how the browser is actually rendering an element's style. This uses [`getComputedStyle()`](https://developer.mozilla.org/en-US/docs/Web/API/Window.getComputedStyle) under the covers. (On IE 8, it uses [`currentStyle`](http://msdn.microsoft.com/en-us/library/ie/ms535231%28v=vs.85%29.aspx)). `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()`](quixote.md#quixotebrowser). ### element.getRawPosition() ``` Stability: 3 - Stable ``` Determine where an element is displayed within the frame viewport, as computed by the browser. This uses [`getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element.getBoundingClientRect) under the covers. Note that scrolling the document will cause the position to change. You can use [`QFrame.getRawScrollPosition()`](QFrame.md#framegetrawscrollposition) 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](https://developer.mozilla.org/en-US/docs/Web/CSS/length). 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()`](quixote.md#quixotebrowser). ### 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`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) DOM element for the frame. `dom = element.toDomElement()` * `dom (`[`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)`)` The DOM element. ## Deprecated Methods ### element.assert() ``` Stability: 0 - Deprecated ``` **Deprecation Warning:** This method may be removed in a future release. Use [QElement properties'](#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](#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: ```javascript 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'](#properties) `should` assertions instead. Compare the element's properties to a set of expected values. This is the same as [`QElement.assert()`](#elementassert), 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](#properties) (`top`, `right`, etc.) as keys, along with the expected value as another property or hard-coded value.