Add Expectation.extend for custom matchers

[benbrimeyer]

• Added Expectation.extend which allow projects to add their own matchers to TestEZ.
  • Matchers are functions that should return an object with with two keys, boolean pass and a string message

-- setting up test runners
local TestEZ = require(ReplicatedStorage.Packages.Dev.TestEZ)

TestEZ.Expectation.extend({
	divisibleBy = function(receivedValue, expectedValue)
		local pass = receivedValue % expectedValue == 0
		if pass then
			return {
				pass = true,
				message = ("Expected %s to be divisible by %s"):format(receivedValue, expectedValue)
			}
		else
			return {
				pass = false,
				message = ("Expected %s not to be divisible by %s"):format(receivedValue, expectedValue)
			}
		end
	end
})

-- spec.lua
it("should be an even number", function()
	expect(10).to.be.divisibleBy(2)
end)

Heavily influenced by https://jestjs.io/docs/en/expect#expectextendmatchers

[benbrimeyer]

Rationale:
This allows use cases to register their own, opinionated expectations that integrates into expect.

For example, this would allow a mocking library to add its own expectation for spies or would allow the following issues to be closed (in favor of a "TestEZ-extended"-like library)

• .greater.than and .less.than #33
• Option to test for deep equality #46
• Lack of easy way to assert that a value is true or false or truthy or falsy #45

[benbrimeyer]

Still some open questions that could be answered now or at a later date:

• Should TestEZ-provided expectations be protected? Right now there's a chance that an external use case can overwrite an existing TestEZ expectation.
• Should previously extended expectations be protected in the same manner? For example, if spyToBeCalled has been registered twice, should we simply overwrite with the latest or throw? (Throwing may cause issues with compatibility)

[MagiMaster]

After discussing this some earlier, I think we'll want this much sooner than we'll be able to commit to replacing the expectation syntax. As this PR is fairly old at this point and will likely require some rework anyway:

One thing I'd like to see with something like this is the ability for these to be defined in a scoped way (e.g. in init.spec.lua files instead of in the starter scripts). That may be a break from the original API, but I think it alleviates a lot of concerns about conflicting overrides. If there's an issue, it'll be because you overrode your own stuff, not because some other unrelated code did. It also makes allowing overriding the builtin expectations a lot safer if that's something we want (I could see either way on that).

Unfortunately, the way Expectation is written, making it so that the changes are scoped will be a bit trickier. You'd need to store the extensions in the test plan's tree (or something parallel to that) and pass them along as needed.

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[benbrimeyer]

Closing in favor of #142