🌌 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.

1Experimental

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	Add 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

note

• describe, it and test 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 since it.only is not enabled in --only=describe)
• ❌ test.only (it forces a failure since test.only is not enabled in --only=describe)

import { describe, it, test } from 'poku';

describe.only(() => {
  it(() => {
    // ...
  });

  test(() => {
    // ...
  });
});

test(() => {
  // ...
});

npx poku --only=describe

note

• describe methods without .only will be skipped.
• it and test methods without .only will be executed normally, including outside the scope of describe (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 since describe.only is not enabled in --only=it)

import { describe, it, test } from 'poku';

describe(() => {
  it.only(() => {
    // ...
  });

  test.only(() => {
    // ...
  });
});

test.only(() => {
  // ...
});

npx poku --only=it

note

• it and test methods without .only will be skipped.
• describe methods without .only will be executed normally.

---

tip

• The .only helper works exactly as its respective describe, it and test methods (e.g., by running beforeEach and afterEach for the test.only or it.only).
• It works for both sequential and parallel executions normally, including synchronous and asynchronous tests.

Important

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 both describe, it and test methods, you need to use the --only flag.
• To enable the .only helper for describe methods, you need to use the --only=describe flag.
• To enable the .only helper for it and test 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