Ember Simulant Test Helpers

Common errors

• Module not found: Error: Can't resolve 'ember-simulant-test-helpers'

  cause Attempting to import the package using CommonJS `require()` syntax in a modern Ember CLI project, or the package was not properly installed or linked.
  fix Ensure the package is installed via `ember install ember-simulant-test-helpers` and use ES module `import { helperName } from 'ember-simulant-test-helpers';` syntax. Verify `node_modules` contains the package.

• TypeError: Cannot read properties of undefined (reading 'panX')

  cause The `ember-simulant-test-helpers` package might not be correctly integrated into the Ember testing environment, or the import path is incorrect, leading to an undefined module.
  fix Double-check the import statement for typos: `import { panX } from 'ember-simulant-test-helpers';`. Ensure `ember install ember-simulant-test-helpers` was run successfully and that your Ember CLI version supports the package's integration method.

• Error: `find` was called but no element was found for selector '.my-swipe-aware-thingy'.

  cause This error originates from `@ember/test-helpers`, indicating that the element you're trying to interact with using `panX` (or other helpers) does not exist in the DOM when the test helper is called.
  fix Verify that your `await render(...)` call renders the target element before `panX` is invoked. Check for typos in the selector passed to `find` and ensure the component is correctly rendered and visible in the test context.

Warnings

• breaking The project is effectively abandoned, with its last commit several years ago. It is unlikely to receive updates for compatibility with newer Ember versions (e.g., Ember 4.x+ or Octane) or modern browser APIs. Users might encounter silent failures or unexpected behavior.
  Fix: Consider migrating to actively maintained Ember testing utilities or exploring alternatives for advanced DOM event simulation. Manual event dispatching with modern browser APIs might be a more stable approach.
• gotcha The specified Node.js engine versions (`10.* || >= 12`) are significantly outdated. Running this package with recent Node.js versions (e.g., Node 16+) may lead to compatibility issues, warnings during installation, or runtime errors.
  Fix: While `npm install --force` or `npm install --legacy-peer-deps` might bypass installation errors, runtime compatibility issues with newer Node versions are likely. It's recommended to test thoroughly in a modern environment or avoid this package for new projects.
• gotcha The package's 0.x versioning indicates that its API was never considered stable. While it has not changed since 0.3.2, relying on an unstable API from an abandoned project introduces significant long-term maintenance risk.
  Fix: Thoroughly test existing implementations and document current behavior. For new features or projects, prioritize alternative solutions with stable APIs and active maintenance.
• gotcha The underlying `simulant.js` library, which `ember-simulant-test-helpers` depends on, might also be outdated. Its event simulation methods may not accurately reflect current browser event models or touch event specifications, potentially leading to 'false positive' tests.
  Fix: Manually verify the simulated events against real browser behavior, especially for critical interactions. Be aware that the fidelity of older event simulation libraries might degrade over time as browser standards evolve.

Install

• npm install ember-simulant-test-helpers npm
• yarn add ember-simulant-test-helpers yarn
• pnpm add ember-simulant-test-helpers pnpm

Imports

• panX
  wrong:

  const panX = require('ember-simulant-test-helpers');

  correct:

  import { panX } from 'ember-simulant-test-helpers';

  Ember applications typically use ESM imports. CommonJS `require` will not work in modern Ember test environments.
• panY

  import { panY } from 'ember-simulant-test-helpers';

  The library exports various gesture helpers like `panY` for vertical panning, alongside `panX`.
• swipe

  import { swipe } from 'ember-simulant-test-helpers';

  While `panX` is shown, the library provides a range of gesture-based helpers for simulating complex interactions such as `swipe`.

Quickstart

Demonstrates how to import and use the `panX` helper within an Ember rendering test to simulate a horizontal pan gesture on a DOM element.

import { find, render } from '@ember/test-helpers';
import { setupRenderingTest } from 'ember-qunit';
import { module, test } from 'qunit';
import { panX } from 'ember-simulant-test-helpers';

module('Integration | Helper | panX', function(hooks) {
  setupRenderingTest(hooks);

  test('it can simulate a horizontal pan gesture', async function(assert) {
    await render('<div class="my-swipe-aware-thingy" style="width: 200px; height: 100px; touch-action: none;"></div>');

    const element = find('.my-swipe-aware-thingy');
    let panDetected = false;
    element.addEventListener('panstart', () => panDetected = true);
    element.addEventListener('panend', () => assert.true(panDetected, 'Pan start should be detected'));

    await panX(element, {
      position: [50, 50],
      amount: 100,
      duration: 100
    });

    assert.dom('.my-swipe-aware-thingy').exists('The element should still be in the DOM');
    // In a real test, you'd assert on application state changes or CSS transformations
  });
});