INTEGRATE: PositionDescriptor assertions

* dev:
  Tweak roadmap
  Update distribution files
  Update changelog with PositionDescriptor assertions
  Copyedit PositionDescriptor API docs
  Update PositionDescriptor API docs, make minor tweaks to other API docs
  Add PositionDescriptor.should.beLeftOf(), .should.beRightOf()
  Add PositionDescriptor.should.beBelow()
  Add PositionDescriptor.should.beAbove()

CHANGELOG.md

@@ -16,8 +16,11 @@ description to be done
 
 *New methods:*
 
+(to be fleshed out/cleaned up)
+
 * (all descriptors) .should.equal()
 * (all descriptors) .should.notEqual()
+* PositionDescriptor.should.beAbove(), beBelow(), beLeftOf(), beRightOf()*
 
 *Other changes:*
 

ROADMAP.md

@@ -22,10 +22,7 @@
 
 * (DONE) .should.equal()
 * (DONE) .should.notEqual()
-* .should.beAbove()
-* .should.beBelow()
-* .should.beToRightOf()
-* .should.beToLeftOf()
+* (DONE) PositionDescriptor assertions
 * .should.beBiggerThan()
 * .should.beSmallerThan()
 * (DONE) Update nickname generation
@@ -41,20 +38,14 @@
 	* Update src/values README - just a copyedit pass
 
 
-## To Do: quixote.elementFromDom
+## To Do: PositionDescriptor assertions
 
-* (DONE) Add tests
-* (DONE) Move code out of QElement
-* (DONE) nicknames: '#id', '.class', '<tag>'
-* (DONE) Update nickname-generation code
-* (DONE) API docs
-	* QElement.add, QElement.parent, quixote.elementFromDom nickname generation
-	* Add 'nickname' to QElement.parent()
+* (DONE) .should.beAbove()
+* (DONE) .should.beBelow()
+* (DONE) .should.beRightOf()
+* (DONE) .should.beLeftOf()
+* (DONE) API
 * (DONE) CHANGELOG
-  * Improved automatic nicknames
-  * Add QElement.parent(nickname)
-* (DONE) README
-	* Credit Justin for inspiring nickname improvements
 
 
 ## Dogfooding Notes

docs/ElementRendered.md

@@ -46,9 +46,9 @@ Stability: 3 - Stable
 
 Check whether the element is rendered.
 
-`elementRendered.should.equal(expectedRender, message)`
+`elementRendered.should.equal(expectation, message)`
 
-* `expectedRender (ElementRendered equivalent)` The expected render status.
+* `expectation (ElementRendered equivalent)` The expected render status.
 
 * `message (optional string)` A message to include when the assertion fails.
 
@@ -68,9 +68,9 @@ Stability: 3 - Stable
 
 Check whether the element is rendered opposite to another element.
 
-`elementRendered.should.notEqual(expectedRender, message)`
+`elementRendered.should.notEqual(expectation, message)`
 
-* `expectedPosition (ElementRendered equivalent)` The render status to not match.
+* `expectation (ElementRendered equivalent)` The render status to not match.
 
 * `message (optional string)` A message to include when the assertion fails.
 

docs/PositionDescriptor.md

@@ -48,17 +48,20 @@ lightbox.rendered.should.equal(false);  // recommended
 Use 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.
 
 
-### position.should.equal()
+### Equality
 
 ```
 Stability: 3 - Stable
 ```
 
-Check whether the position matches another position.
+Check whether two positions match.
 
-`position.should.equal(expectedPosition, message)`
+* `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.
 
-* `expectedPosition (PositionDescriptor equivalent)` The expected position.
+Parameters:
+
+* `expectation (PositionDescriptor equivalent)` The position to compare against.
 
 * `message (optional string)` A message to include when the assertion fails.
 
@@ -70,25 +73,26 @@ logo.top.should.equal(header.top);
 ```
 
 
-### position.should.notEqual()
+### Relative Positioning
 
-```
-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.
 
-Check whether the position does not match another position.
+* `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.
 
-`position.should.notEqual(expectedPosition, message)`
+Parameters:
 
-* `expectedPosition (PositionDescriptor equivalent)` The position to not match.
+* `expectation (PositionDescriptor equivalent)` The position to compare against.
 
 * `message (optional string)` A message to include when the assertion fails.
 
 Example:
 
 ```javascript
-// "The light box should not be flush against the bottom of the navbar."
-lightbox.top.should.notEqual(navbar.bottom);
+// "The light box should be below the navbar."
+lightbox.top.should.beBelow(navbar.bottom);
 ```
 
 

docs/SizeDescriptor.md

@@ -55,9 +55,9 @@ Stability: 3 - Stable
 
 Check whether the size matches another size.
 
-`size.should.equal(expectedSize, message)`
+`size.should.equal(expectation, message)`
 
-* `expectedSize (SizeDescriptor equivalent)` The expected size.
+* `expectation (SizeDescriptor equivalent)` The expected size.
 
 * `message (optional string)` A message to include when the assertion fails.
 
@@ -77,9 +77,9 @@ Stability: 3 - Stable
 
 Check whether the size does not match another size.
 
-`size.should.notEqual(expectedSize, message)`
+`size.should.notEqual(expectation, message)`
 
-* `expectedSize (SizeDescriptor equivalent)` The position to not match.
+* `expectation (SizeDescriptor equivalent)` The position to not match.
 
 * `message (optional string)` A message to include when the assertion fails.
 

src/descriptors/_position_descriptor_test.js

@@ -64,14 +64,111 @@ describe("DESCRIPTOR: PositionDescriptor", function() {
 		assert.equal(x.to(X + 20).toString(), "distance from " + x + " to " + (X + 20) + "px x-coordinate", "toString()");
 	});
 
-	function createDescriptor(dimension, value) {
-		return new TestPositionDescriptor(dimension, value);
-	}
+
+	describe("assertions", function() {
+
+		it("checks that position is above an expected value", function() {
+			var actual = createDescriptor("y", 10);
+			var expectedSuccess = createDescriptor("y", 15);
+			var expectedFailure = createDescriptor("y", 5);
+
+			assert.noException(
+				function() { actual.should.beAbove(expectedSuccess); }
+			);
+
+			assert.exception(
+				function() { actual.should.beAbove(expectedFailure, "my message"); },
+				"my message: y.10px should be at least 6px higher.\n" +
+				"  Expected: less than 5px (y.5px)\n" +
+				"  But was:  10px"
+			);
+		});
+
+		it("checks that position is below an expected value", function() {
+			var actual = createDescriptor("y", 10);
+			var expectedSuccess = createDescriptor("y", 5);
+			var expectedFailure = createDescriptor("y", 15);
+
+			assert.noException(
+				function() { actual.should.beBelow(expectedSuccess); }
+			);
+
+			assert.exception(
+				function() { actual.should.beBelow(expectedFailure, "my message"); },
+				"my message: y.10px should be at least 6px lower.\n" +
+				"  Expected: more than 15px (y.15px)\n" +
+				"  But was:  10px"
+			);
+		});
+
+		it("checks that position is left of an expected value", function() {
+			var actual = createDescriptor("x", 10);
+			var expectedSuccess = createDescriptor("x", 15);
+			var expectedFailure = createDescriptor("x", 5);
+
+			assert.noException(
+				function() { actual.should.beLeftOf(expectedSuccess); }
+			);
+
+			assert.exception(
+				function() { actual.should.beLeftOf(expectedFailure, "my message"); },
+				"my message: x.10px should be at least 6px to left.\n" +
+				"  Expected: less than 5px (x.5px)\n" +
+				"  But was:  10px"
+			);
+		});
+
+		it("checks that position is right of an expected value", function() {
+			var actual = createDescriptor("x", 10);
+			var expectedSuccess = createDescriptor("x", 5);
+			var expectedFailure = createDescriptor("x", 15);
+
+			assert.noException(
+				function() { actual.should.beRightOf(expectedSuccess); }
+			);
+
+			assert.exception(
+				function() { actual.should.beRightOf(expectedFailure, "my message"); },
+				"my message: x.10px should be at least 6px to right.\n" +
+				"  Expected: more than 15px (x.15px)\n" +
+				"  But was:  10px"
+			);
+		});
+
+		it("fails fast if using above/below on x-coordinate", function() {
+			assert.exception(
+				function() { x.should.beAbove(5); },
+				/Can't use 'should.beAbove\(\)' on X coordinates. Did you mean 'should.beLeftOf\(\)'\?/
+			);
+			assert.exception(
+				function() { x.should.beBelow(5); },
+				/Can't use 'should.beBelow\(\)' on X coordinates. Did you mean 'should.beRightOf\(\)'\?/
+			);
+		});
+
+
+		it("fails fast if using left/right on y-coordinate", function() {
+			assert.exception(
+				function() { y.should.beLeftOf(5); },
+				/Can't use 'should.beLeftOf\(\)' on Y coordinates. Did you mean 'should.beAbove\(\)'\?/
+			);
+			assert.exception(
+				function() { y.should.beRightOf(5); },
+				/Can't use 'should.beRightOf\(\)' on Y coordinates. Did you mean 'should.beBelow\(\)'\?/
+			);
+		});
+
+	});
 
 });
 
+function createDescriptor(dimension, value) {
+	return new TestPositionDescriptor(dimension, value);
+}
+
 
 function TestPositionDescriptor(dimension, value) {
+	this.should = this.createShould();
 	this._dimension = dimension;
 	if (dimension === "x") {
 		PositionDescriptor.x(this);