Redesign API about assertron

[unional]

Just think of a proposal:

const order = new AssertOrder()

order.step(0).once() // default
order.step(1).atLeast(3) // 3 or more times
order.step(2).atLeastOnce() // === atLeast(1)
order.step(3).exactly(3) // 3 times
order.step(4,5) // any(4,5) === called during step 4 and 5

[ashwinimanjunath]

Hello Homa,
I have fixes for Issues #15 & #16 in a local branch,trying to push these to remote and getting the below error:
remote: Permission to unional/assert-order.git denied to ashwinimanjunath.
fatal: unable to access 'https://github.com/unional/assert-order.git/': The requested URL returned error: 403
Have tried to troubleshoot with various options, however the push is not going through and cannot do a pull request. Could you please take a look and see if you could give me(ashwinimanjunath/[email protected]) access.

Thanks,
Ashwini

[unional]

You should fork this repo and make the changes in your repo. After you are done, you can push to github and create a pull request.

Thanks!

[chenfanggm]

Hi Homa,

For this issue, I really like the last proposal you posted. It really separates "step" from "validation". That means one could call step() to track execution order, and use once(), atLeast(), exactly() to count and validate that how many times that step should occur.

I really spend some time to try to understand the definition of "some()", which mixes move step, assert at least one hit and calculate total numbers of hit.

[unional]

@chenfanggm yes, some() is atLeastOnce().
At least once has some interesting behavior:

// this works
const order = new AssertOrder()
order.some(0)
order.some(0)
order.once(1)

// this also works
const order = new AssertOrder()
order.some(0)
order.some(0)
order.some(1) // meaning at the same "state", you can accept both 0,1

The total numbers of hit is an add-on so that consumer can track how many times some(n) is called

const order = new AssertOrder()
order.some(0) // returns 1
order.some(0) // returns 2
order.some(0) // returns 3
order.some(1) // returns 1
order.some(1) // returns 2

As regarding separates "step" form "validation", I like that too.

However, there is one issue with that approach.
I original wanted to have a default validation behavior on step() (as seen in order.step(0).once() // default). But this is not possible because when the step() executes, it wouldn't know if any validation functions will be called (thus executing the default validation behavior), meaning the default validation cannot be run synchronously (and throws synchronously).

This will allow subsequent code to run until the async code is given time to execute, meaning the code will not fail on the spot.

A workaround is to forgo this default behavior:

const order = new AssertOrder()
order.onStep(0).once()
...
// or
order.expect(0).once()

This is the same approach used by mocha / chai etc.

[unional]

As balancing the comment, I do prefer the TAP style interface more than Mocha and Chai.
I think it is more direct, less clutter, easier to implement, and more functional (vs OO):

// mocha/chai
expect(0).toBe(0)

// TAP / ava
t.is(0, 0)

The current API follows the TAP style. If there is a naming scheme that can clearly indicate the behavior, that's also an option.

I think @ashwinimanjunath atLeast(step, count) and atLeastOnce(step) is heading that direction.

[unional]

Proposal on the TAP way:

const order = new AssertOrder()
order.is(step) // current step is `step`
order.not(step) // current step is not `step`
order.exactly(step, count) // expected to be executed exactly `count` times
order.atLeast(step, count) // expected to be executed at least `count` times
order.atMost(step, count) // exected to be executed at most `count` times

// need more debate
order.anyOf([step1, step2, ...], count) 
order.anyOf([step1, step2, ...], [count1, count2, ...])
 
// alias
order.atLeastOnce(step) // `atLeast(step, 1)`
order.atMostOnce(step) // `atMost(step, 1)`