Skip to content

Latest commit

 

History

History
162 lines (108 loc) · 8.38 KB

descriptors.md

File metadata and controls

162 lines (108 loc) · 8.38 KB

Quixote API: Descriptors

Descriptors are the most important concept in Quixote. They're used with QElement.assert(). Each descriptor represents some piece of styling information, such as an element's width or the height of the page.

Using QElement.assert(), descriptors can be compared to hard-coded values, like this:

header.assert({
  height: 30      // the header is 30px tall
});

They can also be compared to other descriptors, like this:

header.assert({
  width: frame.viewport().width     // the header's width is the same as the viewport's width
});

Many descriptors have additional methods that allow you to refine your comparisons. For example, height is a SizeDescriptor. It has methods like times():

header.assert({
  height: logo.height.times(2)    // the header is twice as tall as the logo
});

With descriptors, you can make relative comparisons and avoid hardcoding values. This is one of Quixote's unique benefits—be sure to try it!

Compatibility Note: We make every effort to ensure that descriptors 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.

Descriptor Catalog

The following descriptors are available:

Element Positions and Sizes

Stability: 2 - Unstable

Descriptors for the position and size of an element are available on QElement instances. The values of these descriptors include padding and borders (if any), but not margins.

Example: "The logo matches the height of the navbar and is aligned to its right edge."

logo.assert({
  height: navbar.height,    // the logo height is equal to the navbar height
  right: navbar.right       // the logo's right edge is the same as the navbar's right edge
});

Viewport Positions and Sizes

Stability: 1 - Experimental

Descriptors for the position and size of the viewport are available on QFrame.viewport(). The viewport is the part of the webpage that's visible in the test frame, not including scrollbars. By comparing element positions and sizes to viewport descriptors, you can make assertions about what's visible to the user.

Example: "The cookie disclaimer stretches across the bottom of the viewport."

var viewport = frame.viewport();
disclaimer.assert({
  bottom: viewport.bottom,    // the bottom of the disclaimer is at the bottom of the viewport
  width: viewport.width       // the width of the disclaimer is the same as the width of the viewport
});

Compatibility Notes:

  • Although there is a standard way to get the dimensions of the viewport, and we've confirmed that it works on our tested browsers, it may not be supported properly by all browsers. If you use these descriptors, perform a visual check to make sure they're working as expected, and please report compatibility problems.

  • In particular, the current solution for viewport dimensions only works on pages in standards mode. Specifically, they have been tested on pages using <!DOCTYPE html>. They do not work on pages without a doctype. If support for another doctype is important to you, please let us know by opening an issue.

  • Mobile Safari sometimes ignores the width and height attributes on an iframe, as described in the compatibility note for quixote.createFrame(). This can result in viewport descriptors returning larger-than-expected values.

Page Positions and Sizes

Stability: 1 - Experimental

Descriptors for the position and size of the page are available on QFrame.page(). Unlike the viewport, these descriptors include the entire page displayed in the frame, whether or not it's scrolled out of view or not, and the page is always at least as big as the viewport. By comparing element positions and sizes to viewport descriptors, you can make assertions about where elements are positioned on the page.

Example: "The sidebar extends down the right side of the page."

var page = frame.page();
sidebar.assert({
  right: page.right,    // The right edge of the sidebar is the same as the right edge of the page 
  height: page.height   // The height of the sidebar is the same as the height of the page
});

Compatibility Notes:

  • There is no standard way to get the dimensions of the page. We have implemented a solution that works on our tested browsers, but it may not work on all browsers. If you use these descriptors, perform a visual check to make sure they're working as expected, and please report compatibility problems.

  • In particular, the current solution for page dimensions only works on pages in standards mode. Specifically, they have been tested on pages using <!DOCTYPE html>. They do not work on pages without a doctype. If support for another doctype is important to you, please let us know by opening an issue.

Descriptor API

All descriptors implement the following method. In most cases, you won't need to call this method directly. Instead, use QElement.assert() or QElement.diff().

diff()

Stability: 2 - Unstable

Compare the descriptor to an expected value, which may be another descriptor. Throws an exception if the value isn't comparable to the descriptor.

This is the same as calling QElement.diff(), except that it operates on just one descriptor at a time.

diff = descriptor.diff(expected)

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

  • expected (any) The expected value.

Example: var diff = element.top.diff(otherElement.top);