feat: add only modifier to describe, it and test methods

[wellwelwel]

Closes #722.

• Tests using poku runner
• Tests without poku runner
• describe + describe.only
• describe.only + describe.only
• it + it.only
• it.only + it.only
• describe.only + it
• describe.only + it.only
• describe + it.only
• Improve overloads
• Fail for .only without --only
• add docs

---

Experimental usage

--only

• Only tests using .only will be run. This applies to describe, it and test.
• If a common describe has a it.only in its scope, the it.only will not be reached.

--describeOnly

• Only describe tests using .only will be run.

--itOnly or --testOnly (alias):

• Only it and test tests using .only will be run.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.12%. Comparing base (402af07) to head (d7ea358).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #767      +/-   ##
==========================================
+ Coverage   99.08%   99.12%   +0.04%     
==========================================
  Files          36       36              
  Lines        1742     1824      +82     
  Branches       10       10              
==========================================
+ Hits         1726     1808      +82     
  Misses          8        8              
  Partials        8        8              

Flag	Coverage Δ
linux	99.01% <100.00%> (+0.04%)	⬆️
osx	99.06% <100.00%> (+0.04%)	⬆️
windows	99.01% <100.00%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mrazauskas]

Below it is documented that --only is the same as --describeOnly --itOnly. Hm.. Looks like these are contradicting statements. Or?

[mrazauskas]

Also, did you consider: --only=it, --only=test, --only=describe,test? The jump from --only to --describeOnly does not feel intuitive. If I want the only feature, makes me think of typing --only first and optionally adding something to it. Or?

[mrazauskas]

Another aspect, what happens with the after/before hooks? And is the code contain within describe() executed at some point? Or how? Not clear.

[wellwelwel]

--only=it, --only=test, --only=describe,test

That sounds interesting.

---

Below it is documented that --only is the same as --describeOnly --itOnly. Hm.. Looks like these are contradicting statements. Or?

I'm not sure I understand 😅

---

Another aspect, what happens with the after/before hooks? And is the code contain within describe() executed at some point? Or how? Not clear.

Everything should work exactly the same with or without the .only. The .only just calls the base it or describe methods, for example:

poku/src/modules/helpers/modifiers.ts

Lines 87 to 88 in 8dcce80

	if (typeof messageOrCb === 'string' && cb) return itBase(messageOrCb, cb);
	if (typeof messageOrCb === 'function') return itBase(messageOrCb);

[mrazauskas]

What is “exactly the same”? So the describe() code is always executed? Or only with --testOnly, but not with --describeOnly? And what about --only, all describe() code with be executed, or none, or some?

[wellwelwel]

One more: behaviour example of .only within nested describe blocks is missing. describe > describe.only > test. Is this describe.only executed with --only=describe? Or the parent describe gets skipped?

If the first describe is skipped, everything within its scope/context will be skipped too 🙋🏻‍♂️

[mrazauskas]

Trying it out:

import { describe, test } from "poku";

describe(() => {
  describe.only(() => {
    test("one", () => {
      //
    });
  });
});

test("two", () => {
  //
});

• --only=describe runs "two". The command is about only and describe, but it runs a test that does not have only and is not within a describe. Puzzling? Isn’t it?

---

import { describe, test } from "poku";

describe.only(() => {
  test("one", () => {
    //
  });
});

test("two", () => {
  //
});

• --only runs nothing. Hm.. (First I was looking for my mistake. Now I think this is by design. Perhaps? Or is this a bug? Hm..)

[mrazauskas]

Ah.. I see. Second example is my mistake. To make it work as I expect, if this pattern would be implemented:

import { test } from "poku";

test.only((t) => {
  t.test("one", () => {
    //
  });
});

test("two", () => {
  //
});

[wellwelwel]

• Puzzling? Isn’t it?

At this point, it's important to consider that --only=describe is different from "mapping the describe methods", but rather "enabling .only for the describe methods". To use .only for test and it, it's necessary to enable it for them.

• Now I think this is by design

Yes, the describe is executed, but the "one" don't, since it doesn't use the .only with --only.

[wellwelwel]

The limitations of not mapping the tests to the .only case while trying to bring about a similar behavior to the usual one were holding me back both technically and creatively.

The idea of switching on and off and the concept of "enabling", helped me to reconcile a different approach without losing the idea of JavaScript syntax.