π only
The .only
helper enables selective execution of tests, allowing you to focus on specific describe
, it
, and/or test
blocks by running only those marked with .only
. See the usage to understand the different conditions and behaviors.
This method can be changed according to users' suggestions and needs. Major changes in this method won't be considered breaking changes while it's in experimental stage.
History
Version | Changes |
---|---|
v2.7.0 | only modifier to describe , it and test methods. |
Usageβ
To enable the .only
helper, you must to pass one of the following flags to enable it selectively:
--only
β
Enables the .only
helper for describe
, it
and test
methods.
- β
describe.only
- β
it.only
- β
test.only
- βοΈ
describe
(it will be skipped)- βοΈ
it
(it will be skipped)- βοΈ
test
(it will be skipped)
import { describe, it, test } from 'poku';
describe.only(() => {
it.only(() => {
// ...
});
test.only(() => {
// ...
});
});
test.only(() => {
// ...
});
npx poku --only
describe
,it
andtest
methods without.only
will be skipped.
--only=describe
β
Enables the .only
helper for describe
method.
- β
describe.only
- β
it
- β
test
- βοΈ
describe
(it will be skipped)- β
it.only
(it forces a failure sinceit.only
is not enabled in--only=describe
)- β
test.only
(it forces a failure sincetest.only
is not enabled in--only=describe
)
import { describe, it, test } from 'poku';
describe.only(() => {
it(() => {
// ...
});
test(() => {
// ...
});
});
test(() => {
// ...
});
npx poku --only=describe
describe
methods without.only
will be skipped.it
andtest
methods without.only
will be executed normally, including outside the scope ofdescribe
(top-level).
--only=it
β
Alternative flag:
--only=test
Enables the .only
helper for it
and test
methods.
- β
it.only
- β
test.only
- β
describe
- βοΈ
it
(it will be skipped)- βοΈ
test
(it will be skipped)- β
describe.only
(it forces a failure sincedescribe.only
is not enabled in--only=it
)
import { describe, it, test } from 'poku';
describe(() => {
it.only(() => {
// ...
});
test.only(() => {
// ...
});
});
test.only(() => {
// ...
});
npx poku --only=it
it
andtest
methods without.only
will be skipped.describe
methods without.only
will be executed normally.
- The
.only
helper works exactly as its respectivedescribe
,it
andtest
methods (e.g., by runningbeforeEach
andafterEach
for thetest.only
orit.only
). - It works for both sequential and parallel executions normally, including synchronous and asynchronous tests.
It's important to recall that Poku respects conventional JavaScript syntax in tests and doesn't change the order of the executions. See the examples to clarify it.
Common issuesβ
.only
vs. scopeβ
If a .only
method is inside a skipped method, it won't be executed, for example:
import { describe, it, test } from 'poku';
describe.only(() => {
it.only(() => {
// ... β
});
// it(() => {
// // ...
// });
// test(() => {
// // ...
// });
});
// describe(() => {
// it.only(() => {
// // ... β
// });
//
// test(() => {
// // ...
// });
// });
npx poku --only
Migrating from other Test Runnersβ
In Poku, the .only
helper works like a switch:
- To enable the
.only
helper for bothdescribe
,it
andtest
methods, you need to use the--only
flag. - To enable the
.only
helper fordescribe
methods, you need to use the--only=describe
flag. - To enable the
.only
helper forit
andtest
methods, you need to use the--only=it
flag.
An example running a it.only
inside a describe
method without .only
:
import { describe, it } from 'poku';
describe(() => {
it.only(() => {
// ... β
});
// it(() => {
// // ...
// });
});
npx poku --only=it
This way, you enable .only
only for it
and test
methods, keeping describe
methods with their default behavior. It means that describe
methods will run even without .only
due to --only=it
, while it
and test
methods will only run if you use the .only
helper.
It's also important to note that the --only
flag applies to all files to be tested and you can use the flag with or without poku
command, for example:
npx poku test/my-test.test.js --only
node test/my-test.test.js --only
npx tsx test/my-test.test.ts --only
Mapped vs. non-mapped tests (advanced concept)β
Poku doesn't map the tests to determine which ones will be run or not from appending .only
tests, instead, it toggles which methods (describe
, it
and test
) will be run according to the flags --only
, --only=describe
or --only=it
.
Why isn't it.only
executed in the following example?
describe(() => {
it.only(() => {
// ... β
});
});
npx poku --only
As the describe
method isn't using the .only
helper, it will be skipped, including everything within its scope, which includes the it.only
in this example.
Complex examplesβ
--only=it
β
import { describe, it, test, assert, beforeEach, afterEach } from 'poku';
beforeEach(() => {
// It will run normally before all `it.only` and `test.only`.
});
afterEach(() => {
// It will run normally after all `it.only` and `test.only`.
});
let counter = 0;
// β¬οΈ `describe` scopes β¬οΈ
describe('1', () => {
counter++; // β
`describe` scope will be executed as it's in "native" JavaScript flow
it.only('2', () => {
counter++; // β
`it.only` will be executed
});
it('3', () => {
counter++; // βοΈ `it` will be skipped
});
test.only('4', () => {
counter++; // β
`test.only` will be executed
});
test('5', () => {
counter++; // βοΈ `test` will be skipped
});
});
// β¬οΈ Top-level or non-`describe` scopes β¬οΈ
counter++; // β
Will be executed as it's in "native" JavaScript flow
test('6', () => {
counter++; // βοΈ `test` will be skipped
});
test.only('7', () => {
counter++; // β
`test.only` will be executed
});
it('8', () => {
counter++; // βοΈ `it` will be skipped
});
it.only('9', () => {
counter++; // β
`it.only` will be executed
});
// describe.only('10', () => {
// counter++; // β It would force a failure since `describe.only` is not enabled in `--only=it`
// });
assert.strictEqual(counter, 6);
npx poku --only=it