Skip to content

A platform for community discussion. Free, open, simple.

DEV: Deprecate queryAll and de-jquery other qunit-helpers (#41326)

David Taylor5046884aebc0
diff --git a/.skills/discourse-writing-js-tests/SKILL.md b/.skills/discourse-writing-js-tests/SKILL.md
index 1d8eca36d3c..b22f04c8873 100644
--- a/.skills/discourse-writing-js-tests/SKILL.md
+++ b/.skills/discourse-writing-js-tests/SKILL.md
@@ -16,6 +16,9 @@ Discourse uses [QUnit](https://qunitjs.com/) with `ember-qunit` and
- **One concept per `test`** — each `test()` verifies one behavior for clear failure diagnosis.
- **Prefer `assert.dom(...)`** over manual DOM querying. It produces better failure messages
and waits-free, synchronous DOM reads. See the [qunit-dom API](https://github.com/mainmatter/qunit-dom/blob/master/API.md).
+ When you need the element(s) themselves — for an interaction or a computed value — use
+ `find()` / `findAll()` from `@ember/test-helpers` (scoped to the test container), not
+ `document.querySelector` or the deprecated `queryAll()`.
- **Always `await` interactions** — `render`, `click`, `fillIn`, `visit`, `settled`, etc. are
async. Forgetting `await` causes flaky tests.
- **Always pass a description** as the last argument to assertions — it documents intent and
@@ -121,7 +124,8 @@ module("Integration | Component | BookmarkIcon", function (hooks) {
- Prefer **`.gjs`** with inline `<template>` so you can import and invoke the real component.
- Options: `setupRenderingTest(hooks, { anonymous: true })` for an anonymous user;
`{ stubRouter: true }` to stub `service:router`.
-- Interact with `@ember/test-helpers`: `click`, `fillIn`, `triggerKeyEvent`, `settled`, `find`.
+- Interact with `@ember/test-helpers`: `click`, `fillIn`, `triggerKeyEvent`, `settled`; query
+ the rendered DOM with `find` (first match) / `findAll` (all matches).
- For select-kit and FormKit widgets, use `discourse/tests/helpers/select-kit-helper` and
`discourse/tests/helpers/form-kit-helper` rather than poking the DOM directly.
@@ -187,10 +191,11 @@ import siteFixtures from "discourse/tests/fixtures/site-fixtures";
- **Input simulation**: `createFile(name, type)`, `paste(selector, text)`,
`selectText(selector)`, `simulateKey(el, key)` / `simulateKeys(el, keys)`, `metaModifier`.
- **Conditional tests**: `conditionalTest`, `chromeTest`, `firefoxTest`.
-- **Legacy DOM helpers** (jQuery-backed): `query()`, `queryAll()`, `exists()`, `count()`,
- `visible()`, `invisible()`, `fixture()`. **Prefer `assert.dom(...)` and `find()` in new
- tests** — reach for these only when matching existing style.
-- **Deprecated**: `discourseModule` — use QUnit's `module` instead.
+- **DOM lookup helpers**: `query()`, `exists()`, `count()`, `visible()`, `invisible()`,
+ `fixture()`. **Prefer `assert.dom(...)` for assertions and `find()` / `findAll()` for
+ elements in new tests** — reach for these only when matching existing style.
+- **Deprecated, do not use**: `queryAll()` — use `findAll()` or `assert.dom(...)` instead;
+ `discourseModule` — use QUnit's `module` instead.
## Custom assertions
diff --git a/frontend/discourse/app/lib/dom-utils.js b/frontend/discourse/app/lib/dom-utils.js
index 2b30f09ae21..5ca1d750361 100644
--- a/frontend/discourse/app/lib/dom-utils.js
+++ b/frontend/discourse/app/lib/dom-utils.js
@@ -99,4 +99,12 @@ function position(element) {
};
}
-export default { offset, position };
+export function visible(element) {
+ return !!(
+ element.offsetWidth ||
+ element.offsetHeight ||
+ element.getClientRects().length
+ );
+}
+
+export default { offset, position, visible };
diff --git a/frontend/discourse/tests/helpers/qunit-helpers.js b/frontend/discourse/tests/helpers/qunit-helpers.js
index 6c6f8c94fe8..837b82453c1 100644
--- a/frontend/discourse/tests/helpers/qunit-helpers.js
+++ b/frontend/discourse/tests/helpers/qunit-helpers.js
@@ -2,6 +2,7 @@
import { run } from "@ember/runloop";
import {
find,
+ findAll,
getApplication,
settled,
triggerKeyEvent,
@@ -45,6 +46,7 @@ import { rollbackAllPrepends } from "discourse/lib/class-prepend";
import { clearPopupMenuOptions } from "discourse/lib/composer/custom-popup-menu-options";
import deprecated from "discourse/lib/deprecated";
import { clearDesktopNotificationHandlers } from "discourse/lib/desktop-notifications";
+import { visible as isVisible } from "discourse/lib/dom-utils";
import { clearRegisteredEditCategoryTabs } from "discourse/lib/edit-category-tabs";
import { getOwnerWithFallback } from "discourse/lib/get-owner";
import { restoreBaseUri } from "discourse/lib/get-url";
@@ -497,6 +499,14 @@ export async function selectDate(selector, date) {
}
export function queryAll(selector, context) {
+ deprecated(
+ "`queryAll` is deprecated. Use `findAll` from `@ember/test-helpers` for elements, or `assert.dom` from qunit-dom for assertions.",
+ {
+ id: "discourse.qunit-helpers.query-all",
+ since: "2026.7.0-latest",
+ }
+ );
+
context = context || "#ember-testing";
return $(selector, context);
}
@@ -505,21 +515,53 @@ export function query() {
return document.querySelector("#ember-testing").querySelector(...arguments);
}
+const JQUERY_SELECTOR_PATTERN =
+ /:(contains|visible|hidden|eq|lt|gt|even|odd|first|last|header|input|checkbox|radio|selected|parent)\b(?!-)/i;
+
+function elementsFor(target) {
+ if (isEmpty(target)) {
+ return [];
+ }
+
+ if (typeof target === "string") {
+ if (JQUERY_SELECTOR_PATTERN.test(target)) {
+ deprecated(
+ `"${target}" uses a jQuery-only selector. Use a native CSS selector instead; jQuery selector support will be removed.`,
+ {
+ id: "discourse.qunit-helpers.jquery-selector",
+ since: "2026.7.0-latest",
+ }
+ );
+
+ return $(target, "#ember-testing").toArray();
+ }
+
+ return findAll(target);
+ }
+
+ if (target instanceof Element) {
+ return [target];
+ }
+
+ return Array.from(target);
+}
+
export function invisible(selector) {
- const $items = queryAll(selector + ":visible");
- return (
- $items.length === 0 ||
- $items.css("opacity") !== "1" ||
- $items.css("visibility") === "hidden"
- );
+ const visibleItems = elementsFor(selector).filter(isVisible);
+ if (visibleItems.length === 0) {
+ return true;
+ }
+
+ const style = window.getComputedStyle(visibleItems[0]);
+ return style.opacity !== "1" || style.visibility === "hidden";
}
export function visible(selector) {
- return queryAll(selector + ":visible").length > 0;
+ return elementsFor(selector).some(isVisible);
}
export function count(selector) {
- return queryAll(selector).length;
+ return elementsFor(selector).length;
}
export function exists(selector) {