Have ideas to improve npm?Join in the discussion! »

    qunit-wait-for
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.1 • Public • Published

    qunit-wait-for

    Verify

    Wait for a QUnit Assertion

    Installation

    Install the dependency:

    yarn add -D qunit-wait-for
    

    and then add the following in your JavaScript code:

    import QUnit from "qunit";
    import { installWaitFor } from "qunit-wait-for";
    
    installWaitFor(QUnit);

    If you're using Ember, the right place for that snippet is your tests/test-helper.js.

    What does it do?

    A common pattern in UI testing is the idea of needing to wait for some condition to be met before moving on in your tests. Normally we do some setup, interact with our application, wait for some event to take place, and then perform our assertions. For example, you might see something like this in an Ember integration test:

    // Start with some modal rendered
    await render(hbs`<ModalDialog />`);
    
    // Close the modal, which might need time to animate off-screen
    await click("[data-test-close-button]");
    
    // Wait for the modal to actually be gone
    await waitUntil(() => findAll("[data-test-modal-element]").length === 0);
    
    // Actually _assert_ that the modal is gone
    assert.dom("[data-test-modal-element").doesNotExist();

    Many testing libraries provide helper functions to wait for your tests to catch up to the desired state:

    • In Ember, there are many test helpers that serve this purpose; waitUntil, settled, and await-ing the promise returned from other test helpers all serve this purpose
    • In React, the async utilities from @testing-library/dom provide this functionality

    However, needing to know when -- and how -- to correctly wait for the UI under test to reach the right state adds complexity to your tests and can couple them tightly to the underlying implementation of the code being tested.

    There's another approach that you can take that's much cleaner; rather than waiting for your tests to reach some state and then asserting against it, you can let your assertions run immediately and gracefully handle an initial failure. Then, try the assertion again, over and over until it passes (or a timeout is reached). I call this pattern "convergence testing" based on work from The Frontside on BigTest.js. The result is a test that both correctly waits for asynchronous operations to complete and is decoupled from specific logic around how to wait for the right state.

    With qunit-wait-for, the example above can be simplified to this:

    await render(hbs`<ModalDialog />`);
    
    await click("[data-test-close-button]");
    
    await assert.waitFor(() => {
      assert.dom("[data-test-modal-element").doesNotExist();
    });

    Usage

    To use it, pass a callback to assert.waitFor and within it place your normal assertion:

    await assert.waitFor(() => {
      assert.dom("[data-test-my-element]").exists();
    });

    The resulting promise resolves when either the condition is met or the timeout is reached. This promise should always be await-ed so ensure one of those two things has happened before moving on.

    You can also provide an override for the amount of time to wait for the assertion to pass, if needed. By default it will wait for up to 1000ms (1 second):

    // Wait for up to 2 seconds instead of 1
    await assert.waitFor(
      () => {
        assert.dom("[data-test-my-element]").exists();
      },
      { timeout: 2000 }
    );

    Prior Art

    Install

    npm i qunit-wait-for

    DownloadsWeekly Downloads

    121

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    50.8 kB

    Total Files

    25

    Last publish

    Collaborators

    • avatar