step API

[leobalter]

@wycatz suggested this step API and I'm game for it.

It records steps inside a test. Given this example:

QUnit.test('references are granular', assert => {
  let { SubSub } = MakeSub();

  let obj = SubSub.create({ loud: true });
  let root = rootFor(obj);

  let state = new State(root);

  set(obj, 'name', 'Daniel');

  step('Update name');

  state.validateTags({ name: false });
  state.validateValues({ name: 'Daniel' });
  state.update();

  set(obj, 'loud', false);

  step('Update loud');

  state.validateTags({ loud: false });
  state.validateValues({ loud: false });
  state.update();
});

Each step can be recorded as a assert.ok(true), but printing the given description.

There's one con to consider for this API, which is the idea that assertions can be split in different tests specially inside nested modules.

Even though, it is an interesting approach to consider.

[leobalter]

I did a quick prototype here: 3e515c3

[trentmwillis]

I like this (and think there are several use cases within our own test suite for it), but seems like it is missing one thing: asserting that the correct steps happened.

Seems like maybe we need assert.step( tag ) and then assert.verifySteps([ tag1, tag2, ... ]).

[leobalter]

That's a great and useful addition to the step api. I like it.

[platinumazure]

I'm not opposed to this landing, but I am not sure I understand the use case fully. I see the example above, but I'm not sure I fully understand what advantage this has over assert.ok(true) besides a slight readability improvement. Can anyone enlighten me, please?

[leobalter]

Improves readability and it's also motivated by occurrence. ok(true) is being used here and there to flag given steps and their order. While this could be solved using the current API, step and verifyStep will provide an API with an clear goal to be used in these cases.

Afaik, this case was frequent in some async jquery tests and will certainly gonna be used by Ember as this is an original request from Yehuda Katz.

[platinumazure]

@leobalter Thanks for the explanation, that works for me. That said, I'd love to see a longer-form case study for steps and step verification show up in the QUnit Cookbook maybe (unless that was covered in the documentation PRs?). If that seems worthwhile, I can create an issue.

[leobalter]

it is! Using async code is one of the nice ways to use for examples. Async fns and promises will be great for that.