Jasmine jQuery Matchers and Fixture Loader

Common errors

• ReferenceError: setFixtures is not defined

  cause The `jasmine-jquery` script was not loaded into the global scope, or was loaded after your test specs began executing, or `jasmine-core` was not loaded first.
  fix Ensure `jasmine-jquery.js` is loaded into the global scope via a `<script>` tag in your test runner HTML, or via a pre-processor in your test setup, *before* your test files run. Also, verify `jQuery` and `Jasmine` itself are loaded globally beforehand.

• expect(...).toBeInDOM is not a function

  cause The custom matchers provided by `jasmine-jquery` have not been successfully registered with Jasmine's `expect` object. This typically happens if `jasmine-jquery.js` failed to load or initialize correctly.
  fix Double-check the loading order: `jQuery` -> `Jasmine` -> `jasmine-jquery.js`. Ensure there are no JavaScript errors during the loading of `jasmine-jquery.js` that might prevent it from registering its matchers.

• TypeError: Cannot read properties of undefined (reading 'fn') at jasmine-jquery.js

  cause `jQuery` was not available in the global scope (i.e., `window.jQuery` was undefined) when `jasmine-jquery` attempted to initialize and extend jQuery's functionality.
  fix Make certain that `jQuery` is loaded and accessible globally *before* `jasmine-jquery.js` is loaded. If using a module bundler, ensure `jQuery` is explicitly exposed to the global `window` object.

• Error: Fixture could not be loaded: myFixture.html

  cause The fixture file specified (e.g., `myFixture.html`) could not be found at the expected path, or the fixture path configuration (`jasmine.getFixtures().fixturesPath`) is incorrect or not set.
  fix Verify that `jasmine.getFixtures().fixturesPath` is correctly configured in your test setup to point to the directory containing your fixture files. Ensure the fixture file name and extension are correct and that the file is actually present and accessible at that path.

Warnings

• breaking `jasmine-jquery` is designed for older testing environments where scripts are loaded globally (e.g., via `<script>` tags) and assumes the presence of global `jQuery` and `jasmine` objects. It does not support modern JavaScript module systems (ESM or CommonJS) for direct `import` or `require` of its features. Attempting to use it in a module-based environment without proper shimming or global exposure will lead to `ReferenceError` or features not being available.
  Fix: For module-based projects, consider alternative DOM testing utilities like `@testing-library/jest-dom` or integrate `jasmine-jquery` through global script loading in a test HTML runner or a shimming setup. Ensure `jQuery` and `jasmine` are loaded globally *before* `jasmine-jquery.js`.
• gotcha This library relies heavily on a global `jQuery` object. If `jQuery` is not loaded into the global scope (e.g., loaded via a module bundler in a private scope), `jasmine-jquery` will fail to initialize or its matchers will not function correctly, often manifesting as `TypeError: Cannot read properties of undefined (reading 'fn')`.
  Fix: Ensure `jQuery` is exposed globally (e.g., `window.jQuery = require('jquery')` or by loading jQuery via a `<script>` tag before `jasmine-jquery`). If using a module bundler, explicitly expose `jQuery` to the `window` object before `jasmine-jquery` is processed.
• deprecated The project appears to be unmaintained since 2017, and its development patterns (reliance on globals, Bower for package management) are largely superseded by modern JavaScript ecosystems. Users are encouraged to evaluate more actively maintained alternatives for DOM testing (e.g., `@testing-library/jest-dom` for Jest, or custom matchers for other frameworks) that integrate better with module systems and offer more robust features for modern web development.
  Fix: For new projects or migrations, consider modern DOM testing libraries that align with current front-end development practices. For existing projects, be aware of the lack of updates and potential compatibility issues with newer jQuery or Jasmine versions.

Install

• npm install jasmine-jquery npm
• yarn add jasmine-jquery yarn
• pnpm add jasmine-jquery pnpm

Imports

• toBeInDOM
  wrong:

  import { toBeInDOM } from 'jasmine-jquery'

  correct:

  expect($('<div/>')[0]).toBeInDOM()

  Matchers like `toBeInDOM` are automatically added to Jasmine's global `expect` object upon loading the jasmine-jquery script via a `<script>` tag. No direct `import` or `require` is needed or supported for individual matchers.
• setFixtures
  wrong:

  const setFixtures = require('jasmine-jquery').setFixtures;

  correct:

  setFixtures('<div id="test-elem"></div>')

  Fixture functions like `setFixtures` and `loadFixtures` are exposed as global functions after the `jasmine-jquery.js` script is loaded into the HTML test runner. These functions are not available via standard module imports.
• readFixtures
  wrong:

  import { readFixtures } from 'jasmine-jquery'

  correct:

  const content = readFixtures('my-template.html')

  Similar to `setFixtures`, `readFixtures` is a globally available function for reading fixture content. It expects the fixture file to be accessible via the configured `fixturesPath`.

Quickstart

This quickstart demonstrates how to set up `jasmine-jquery` within a Jasmine test suite. It shows how to load HTML content using `loadFixtures` (assuming a configured `fixturesPath`) and then apply various custom jQuery matchers like `toExist`, `toHaveAttr`, `toBeChecked`, `toBeVisible`, `toBeHidden`, `toContainText`, and `toContainElement` to assert properties and states of DOM elements.

/*
  To run this, you'd typically include jasmine-jquery.js in an HTML test runner
  after jQuery and Jasmine are loaded globally. Example HTML setup:

  <script src="path/to/jquery.js"></script>
  <script src="path/to/jasmine.js"></script>
  <script src="path/to/jasmine-html.js"></script>
  <script src="path/to/boot.js"></script>
  <script src="path/to/jasmine-jquery.js"></script>
  <script src="path/to/your-spec.js"></script>

  And a fixture file: spec/javascripts/fixtures/myFixture.html
  ---
  <div id="test-container" class="active data-attr" data-info="example">
    <input type="checkbox" id="myCheckbox" checked />
    <button id="myButton">Click Me</button>
    <p>Some important text here.</p>
  </div>
*/

describe("Jasmine-jQuery Matchers and Fixtures Integration", function() {
  beforeEach(function() {
    // Configure the path to your fixtures (e.g., 'spec/javascripts/fixtures/')
    // jasmine.getFixtures().fixturesPath = 'base/spec/javascripts/fixtures';

    // Load a fixture from a file into the DOM
    loadFixtures('myFixture.html');
  });

  afterEach(function() {
    // jasmine-jquery automatically removes fixtures after each spec, 
    // but clearFixtures() can be called explicitly if needed.
    // clearFixtures();
  });

  it("should load the fixture and allow attribute checks", function() {
    const $container = $('#test-container');
    expect($container).toExist();
    expect($container).toHaveAttr('class', 'active data-attr');
    expect($container).toHaveAttr('data-info', 'example');
    expect($container).not.toHaveAttr('id', 'wrong-id');
  });

  it("should correctly check the state of a checkbox", function() {
    const $checkbox = $('#myCheckbox');
    expect($checkbox).toBeChecked();
    $checkbox.prop('checked', false);
    expect($checkbox).not.toBeChecked();
  });

  it("should verify element visibility and text content", function() {
    const $button = $('#myButton');
    expect($button).toBeVisible();
    $button.hide();
    expect($button).toBeHidden();

    const $paragraph = $('#test-container p');
    expect($paragraph).toContainText('important text');
    expect($paragraph).not.toContainText('unrelated');
  });

  it("should verify contained elements using selectors", function() {
    const $container = $('#test-container');
    expect($container).toContainElement('input#myCheckbox');
    expect($container).toContainElement('button');
    expect($container).not.toContainElement('span');
  });
});