Add PositionDescriptor.should.beAbove()

ROADMAP.md

@@ -22,11 +22,8 @@
 
 * (DONE) .should.equal()
 * (DONE) .should.notEqual()
-* .should.beAbove()
-* .should.beBelow()
-* .should.beToRightOf()
-* .should.beToLeftOf()
-* .should.beBiggerThan()
+* PositionDescriptor assertions
+* .should.beLargerThan()
 * .should.beSmallerThan()
 * (DONE) Update nickname generation
 * Rename element.rendered --> element.rendering or other? If so, rename ElementRendered class?
@@ -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) CHANGELOG
-  * Improved automatic nicknames
-  * Add QElement.parent(nickname)
-* (DONE) README
-	* Credit Justin for inspiring nickname improvements
+* (DONE) .should.beAbove()
+* .should.beBelow()
+* .should.beRightOf()
+* .should.beLeftOf()
+* API
+* CHANGELOG
 
 
 ## Dogfooding Notes

src/descriptors/_position_descriptor_test.js

@@ -64,14 +64,37 @@ 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 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"
+			);
+		});
+
+	});
 
 });
 
+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);

src/descriptors/position_descriptor.js

@@ -31,17 +31,34 @@ Me.extend = oop.extendFn(Me);
 Me.x = factoryFn(X_DIMENSION);
 Me.y = factoryFn(Y_DIMENSION);
 
-Me.prototype.plus = function plus(amount) {
+Me.prototype.createShould = function() {
+	var self = this;
+	var should = Descriptor.prototype.createShould.call(this);
+
+	should.beAbove = function(expected, message) {
+		self.doAssertion(expected, message, function(actualValue, expectedValue, expectedDesc, message) {
+			if (actualValue.compare(expectedValue) >= 0) {
+				return message + self + " should be at least " + expectedValue.diff(self.plus(1).value()) + ".\n" +
+					"  Expected: less than " + expectedDesc + "\n" +
+					"  But was:  " + actualValue;
+			}
+		});
+	};
+
+	return should;
+};
+
+Me.prototype.plus = function(amount) {
 	if (this._pdbc.dimension === X_DIMENSION) return RelativePosition().right(this, amount);
 	else return RelativePosition().down(this, amount);
 };
 
-Me.prototype.minus = function minus(amount) {
+Me.prototype.minus = function(amount) {
 	if (this._pdbc.dimension === X_DIMENSION) return RelativePosition().left(this, amount);
 	else return RelativePosition().up(this, amount);
 };
 
-Me.prototype.to = function to(position) {
+Me.prototype.to = function(position) {
 	ensure.signature(arguments, [[ Me, Number ]]);
 	if (typeof position === "number") {
 		if (this._pdbc.dimension === X_DIMENSION) position = AbsolutePosition().x(position);
@@ -54,7 +71,7 @@ Me.prototype.to = function to(position) {
 	return GenericSize().create(this, position, "distance from " + this + " to " + position);
 };
 
-Me.prototype.convert = function convert(arg, type) {
+Me.prototype.convert = function(arg, type) {
 	switch (type) {
 		case "number": return this._pdbc.dimension === X_DIMENSION ? Position.x(arg) : Position.y(arg);
 		case "string":