Fluent matchers extension

[cdibbs]

I began to think about this idea in the comments on another issue, but will finish it, here. Essentially, when using Alsatian's current Expect/matchers framework, I felt like it could be more expressive. So, I thought I would explore the possibility of extending it. This weekend I had a little time to begin tinkering around in one of my own projects to develop an API that would at least complement the current one.

I ended up with a fluent interface. (Now that I think about it, I guess I am somewhat partial to these. 😄) Here is some of the syntax I've come up with so far:

        // what I was after:
        Expect(result)
            .to.beInstanceOf(RunnerResult)
            .with.properties({
                ErrorType: CommandErrorType.SystemState,
                Message: m => Expect(m).to.beDefined()
            })
           .and.keys(["to","existence","check"]);
       Expect(() => couldThrow())
           .to.throw(MyError)
           .with.properties({ message: /regex/ });

       // more mundane:   
       Expect([1,2,3]).with.elements([2,3]).and.not.elements([5,6]);
       Expect("something").to.beDefined();
       Expect(weirdThing).to.satisfy(c => myPredicate(c));
       Expect(stringy).to.match(/stuff/);

The above is not comprehensive. I plan to add or have added other common methods like .to.equal and .to.strictlyEqual and .with.all(e => predicate).

It still needs work--tests, in particular--but I am pretty happy with the API, so far. I wonder whether it should be in Alsatian core, or an extension package people could opt to install separately. What do you think?

[jamesadarich]

Hey @cdibbs. Thanks for raising this looks like some interesting thoughts.

What I'd like to know is how you envisage this differing from the Expect function that we have at the moment?

From what I can see so far:

• Chainable matchers e.g. your instance of and with properties
• to and with properties - I think I've seen this in chai, I guess the benefit is limiting options in intellisense but Alsatian does this by type matching. Is there another benefit here?

Are there any other differences or additions you'd propose?

[cdibbs]

@jamesrichford - Yep, that pretty close to sums it up.

1. Chainable/fluent matchers and nested matching.
2. Stop words like to and with. My original hope was that these could also impact context like not does--and they may still--but I am still playing around, so we'll see. I'd like to avoid chai's somewhat verbose style. A few stop words improve readability (imho), but many hinder it.

To exemplify the second one, I had roughly this thought:

Expect(sthg)
  .with(s => s.Prop).matches(/asdf/).and /* keeps context */.not.matches(/fdsa/)
  .with(/* drops context*/ s => s.Prop2).etc.

but ended up going the properties(...) route, instead.

[cdibbs]

@jamesrichford - How do you feel about having a second Expect in Alsatian called FluentExpect? We could experiment with both, side by side, for awhile.

[cdibbs]

@jamesrichford A note on the PR - in the jsdoc comments on 2-3 methods I dropped some git.io shortened links to wiki pages on my fork (writing them helped me flesh out my ideas). In the long run, I thought it might be nice to point those to the official wiki.

[cdibbs]

Per discussions and discoveries on the PR (#459), we've decided this should be in its own library.

[cdibbs]

@jamesrichford, @Jameskmonger FYI I've released an alpha of the plugin called alsatian-fluent-assertions, in case you guys want to take a look. It lives here, for now. I've fleshed out the wiki, a bit, too (helps me get my ducks in a row).

I am reasonably confident there are no major bugs, but I'll continue using it in my own stuff for awhile before releasing a public beta.