PositionDescriptor instances represent an X or Y position on the web page. The position of the top-left corner of the page is zero. X positions increase to the right and Y positions increase downward.
Stability: 3 - Stable
Methods with a PositionDescriptor equivalent parameter can take any of the following:
- A
PositionDescriptorinstance, such asQElement.top. - A number representing an X or Y page coordinate in pixels.
- The string
"none", which means the position is not rendered.
// "The top of the sidebar should be the same as the bottom of the nav bar."
sidebar.top.should.equal(topNav.bottom);// "The logo's left edge should have an X-coordinate of 15."
logo.left.should.equal(15);Note: Although PositionDescriptor can tell you if a position is rendered, it's better to use an ElementRender property such as QElement.render.
// "The light box should not be rendered."
lightbox.top.should.equal("none"); // not recommended
lightbox.render.should.equal(false); // recommendedUse these methods to make assertions about the position. In all cases, if the assertion is true, nothing happens. Otherwise, the assertion throws an exception explaining why it failed.
Stability: 3 - Stable
Check whether two positions match.
position.should.equal(expectation, message)Assert that the position matches the expectation.position.should.notEqual(expectation, message)Assert that the position does not match the expectation.
Parameters:
-
expectation (PositionDescriptor equivalent)The position to compare against. -
message (optional string)A message to include when the assertion fails.
Example:
// "The logo should be at the top of the header."
logo.top.should.equal(header.top);Stability: 3 - Stable
Check whether a position is above, below, left, or right of another position. A position is "above" the expectation when it's closer to the top of the page, and "below" when it's closer to the bottom of the page.
position.should.beAbove(expectation, message)Assert that the position is above the expectation.position.should.beBelow(expectation, message)Assert that the position is below the expectation.position.should.beLeftOf(expectation, message)Assert that the position is to the left of the expectation.position.should.beRightOf(expectation, message)Assert that the position is to the right of the expectation.
Parameters:
-
expectation (PositionDescriptor equivalent)The position to compare against. Must be be rendered. -
message (optional string)A message to include when the assertion fails.
Example:
// "The light box should be below the navbar."
lightbox.top.should.beBelow(navbar.bottom);These methods are useful when you want to compare elements that aren't exactly aligned.
Stability: 3 - Stable
Create a PositionDescriptor that is further down the page or to the right.
newPosition = position.plus(amount)
-
newPosition (PositionDescriptor)The new position. -
amount (SizeDescriptor equivalent)The number of pixels to increase.
Example:
// "The top of the sidebar should be 10px below the bottom of the navigation bar."
sidebar.top.should.equal(navbar.bottom.plus(10));Stability: 3 - Stable
Create a PositionDescriptor that is further up the page or to the left.
newPosition = position.minus(amount)
-
newPosition (PositionDescriptor)The new position. -
amount (SizeDescriptor equivalent)The number of pixels to decrease.
Example:
// "The logo should be 15px from the right side of the navigation bar."
logo.right.should.equal(navbar.right.minus(15));Stability: 3 - Stable
Create a Span that represents an imaginary line between two positions. Useful for compare distances or midpoints.
span = position.to(position2, nickname)
-
span (Span)An imaginary line betweenpositionandposition2. -
position2 (PositionDescriptor or number)The other end of the imaginary line. Must have the same X or Y axis asposition. -
nickname (optional string)The name to use when describing your span in error messages. Defaults to using the two positions.
Example:
// "The header stretches across both columns."
header.width.should.equal(leftColumn.left.to(rightColumn.right));