Add expect.extend

CHANGELOG.md

@@ -8,7 +8,6 @@
   * Limitations:
     * `expect.extend` cannot be called from within `describe` blocks
     * Custom matcher names cannot overwrite pre-existing matchers, including default matchers and matchers introduces from previous `expect.extend` calls.
-    * Custom matcher names may not start with "_"
 
 ## 0.3.3 (2020-09-25)
 * Remove the lifecycle hooks from the session tree. This prevents the `[?]` spam from the reporter not recognizing these nodes.

src/Expectation.lua

@@ -76,7 +76,9 @@ function Expectation.new(value)
 	local self = {
 		value = value,
 		successCondition = true,
-		condition = false
+		condition = false,
+		matchers = {},
+		_boundMatchers = {},
 	}
 
 	setmetatable(self, Expectation)
@@ -91,8 +93,8 @@ function Expectation.new(value)
 	return self
 end
 
-function Expectation:checkMatcherNameCollisions(name)
-	if SELF_KEYS[name] or NEGATION_KEYS[name] or self[name] then
+function Expectation.checkMatcherNameCollisions(name)
+	if SELF_KEYS[name] or NEGATION_KEYS[name] or Expectation[name] then
 		return false
 	end
 
@@ -103,9 +105,7 @@ function Expectation:extend(matchers)
 	self.matchers = matchers or {}
 
 	for name, implementation in pairs(self.matchers) do
-		assert(name:sub(1, 1) ~= "_", string.format("Cannot write matcher %q. Matchers cannot start with %q", name, "_"))
-		assert(self:checkMatcherNameCollisions(name), string.format("Cannot overwrite matcher %q; it already exists", name))
-		self[name] = bindSelf(self, function(_self, ...)
+		self._boundMatchers[name] = bindSelf(self, function(_self, ...)
 			local result = implementation(self.value, ...)
 			local pass = result.pass == self.successCondition
 
@@ -132,6 +132,10 @@ function Expectation.__index(self, key)
 		return newExpectation
 	end
 
+	if self._boundMatchers[key] then
+		return self._boundMatchers[key]
+	end
+
 	-- Fall back to methods provided by Expectation
 	return Expectation[key]
 end
@@ -178,6 +182,9 @@ function Expectation:a(typeName)
 	return self
 end
 
+-- Make alias public on lass
+Expectation.an = Expectation.a
+
 --[[
 	Assert that our expectation value is truthy
 ]]

src/ExpectationContext.lua

@@ -1,4 +1,5 @@
 local Expectation = require(script.Parent.Expectation)
+local checkMatcherNameCollisions = Expectation.checkMatcherNameCollisions
 
 local function copy(t)
 	local result = {}
@@ -27,9 +28,8 @@ end
 
 function ExpectationContext:extend(config)
 	for key, value in pairs(config) do
-		if self._extensions[key] then
-			error(string.format("Cannot reassign %q in expect.extend", key))
-		end
+		assert(self._extensions[key] == nil, string.format("Cannot reassign %q in expect.extend", key))
+		assert(checkMatcherNameCollisions(key), string.format("Cannot overwrite matcher %q; it already exists", key))
 
 		self._extensions[key] = value
 	end

src/TestPlan.lua

@@ -107,7 +107,7 @@ local function newEnvironment(currentNode, extraEnvironment)
 
 	env.expect = setmetatable({
 		extend = function(...)
-			error(string.format("Cannot call %q from within a %q node.", "expect.extend", "describe"))
+			error("Cannot call \"expect.extend\" from within a \"describe\" node.")
 		end,
 	}, {
 		__call = function(_self, ...)

tests/passing/expectExtend-illegalWrites.spec.lua

@@ -8,61 +8,47 @@ local noOptMatcher = function(_received, _expected)
 end
 
 local ERROR_CANNOT_OVERWRITE = "Cannot overwrite matcher"
-local ERROR_CANNOT_START_WITH = "Matchers cannot start with"
-
-local runTest = function(expectedError)
-	return function()
-		local success, message = pcall(function()
-			expect()
-		end)
-
-		assert(success == false, "should have been thrown")
-		assert(message:match(expectedError), string.format("\nUnexpected error:\n%s", message))
-	end
-end
 
 return function()
 	describe("attempt to overwrite default", function()
 		beforeAll(function()
-			expect.extend({
-				-- This should throw since `ok` is a default matcher
-				ok = noOptMatcher,
-			})
+			local success, message = pcall(function()
+				expect.extend({
+					-- This should throw since `ok` is a default matcher
+					ok = noOptMatcher,
+				})
+			end)
+
+			assert(success == false, "should have thrown")
+			assert(message:match(ERROR_CANNOT_OVERWRITE), string.format("\nUnexpected error:\n%s", message))
 		end)
-
-		it("SHOULD fail with expected error message", runTest(ERROR_CANNOT_OVERWRITE))
 	end)
 
 	describe("attempt to overwrite never", function()
 		beforeAll(function()
-			expect.extend({
-				-- This should throw since `never` is protected
-				never = noOptMatcher,
-			})
+			local success, message = pcall(function()
+				expect.extend({
+					-- This should throw since `never` is a default matcher
+					never = noOptMatcher,
+				})
+			end)
+
+			assert(success == false, "should have thrown")
+			assert(message:match(ERROR_CANNOT_OVERWRITE), string.format("\nUnexpected error:\n%s", message))
 		end)
-
-		it("SHOULD fail with expected error message", runTest(ERROR_CANNOT_OVERWRITE))
 	end)
 
 	describe("attempt to overwrite self", function()
 		beforeAll(function()
-			expect.extend({
-				-- This should throw since `a` is protected
-				a = noOptMatcher,
-			})
+			local success, message = pcall(function()
+				expect.extend({
+					-- This should throw since `a` is a default matcher
+					a = noOptMatcher,
+				})
+			end)
+
+			assert(success == false, "should have thrown")
+			assert(message:match(ERROR_CANNOT_OVERWRITE), string.format("\nUnexpected error:\n%s", message))
 		end)
-
-		it("SHOULD fail with expected error message", runTest(ERROR_CANNOT_OVERWRITE))
-	end)
-
-	describe("attempt to start with _", function()
-		beforeAll(function()
-			expect.extend({
-				-- This should throw since this starts with _
-				_fooBar = noOptMatcher,
-			})
-		end)
-
-		it("SHOULD fail with expected error message", runTest(ERROR_CANNOT_START_WITH))
 	end)
 end