# Write component tests for Discourse

**URL:** <https://meta.discourse.org/t/write-component-tests-for-discourse/417554>\
**Category:** Developer Guides\
**Created:** [November 16, 2026, 4:21pm UTC](https://meta.discourse.org/t/write-component-tests-for-discourse/417554 "2026-11-16T16:21:02Z")\
**Posts on this page:** 1\
**Page:** 1

## AI-generated summary

This [guide](/t/-/66857) explains how to write component tests for Discourse using the `.gjs` format, which renders components in isolation for faster, more focused testing than acceptance tests. Tests for core components reside in `frontend/discourse/tests/integration/components/**`, UI-kit in `.../ui-kit/**`, and plugins in `plugins/<name>/test/javascripts/integration/**`. Files should be named `[component]-test.gjs`.

The guide provides a [first test example](/t/-/66857/1) demonstrating the use of `setupRenderingTest` from `discourse/tests/helpers/component-test` rather than `ember-qunit`. This helper sets up `this.siteSettings`, `this.site`, and a logged-in `this.currentUser` (which can be disabled with `{ anonymous: true }`). Assertions should use [qunit-dom](https://github.com/mainmatter/qunit-dom/blob/master/API.md) with descriptive messages. Module titles must end with the component's PascalCase invocation name.

For managing state and interactions, the guide emphasizes using `tracked()` for dynamic values instead of `this.set()` or test-only classes. If a component updates a value via a callback (e.g., `@onChange`), the callback should assign to the tracked value. For objects like models that are mutated, `trackedObject` from `@ember/reactive/collections` should be used. Crucially, developers must `await rerender()` after tracked writes (unless async work is triggered, where `await settled()` is needed) because tracked writes do not re-render synchronously. Edge cases, such as starting with `undefined` or forcing re-renders on identical values using `Object.is`, are also covered.

Finally, network requests are stubbed using the default [Pretender](https://github.com/pretenderjs/pretender) server. Routes are overridden directly in the test using `pretender.get(...)` and the `response` helper, ensuring the network boundary is mocked rather than internal component collaborators. The full document is [version controlled on GitHub](https://github.com/discourse/discourse/blob/main/docs/developer-guides/docs/03-code-internals/33-component-tests.md).

<div class="post-metadata">

**Author:** ![system](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/system/32/443519_2.png) [@system](https://meta.discourse.org/u/system)\
**Post date:** [November 16, 2026, 4:21pm UTC](https://meta.discourse.org/t/write-component-tests-for-discourse/417554/1 "2026-11-16T16:21:02Z")

</div>

Component tests render a single component in isolation and assert on the DOM it produces. They are faster and more focused than acceptance tests, which boot the whole application and visit a route. To run them, see [Run test suites](https://meta.discourse.org/t/-/66857).

## Where tests live

| Code under test | Test location |
| --- | --- |
| Core | `frontend/discourse/tests/integration/components/**` |
| Core `ui-kit` | `frontend/discourse/tests/integration/ui-kit/**` |
| Plugin | `plugins/<name>/test/javascripts/integration/**` |

Name the file after the component with a `-test.gjs` suffix. The `.gjs` format lets the test import the component and invoke it in an inline `<template>`, the same way production code does.

## A first test

```gjs
import { render } from "@ember/test-helpers";
import { module, test } from "qunit";
import { setupRenderingTest } from "discourse/tests/helpers/component-test";
import DPageSubheader from "discourse/ui-kit/d-page-subheader";

module("Integration | Component | DPageSubheader", function (hooks) {
  setupRenderingTest(hooks);

  test("renders the title", async function (assert) {
    await render(
      <template><DPageSubheader @titleLabel="Settings" /></template>
    );

    assert
      .dom(".d-page-subheader__title")
      .hasText("Settings", "shows @titleLabel");
  });
});

```

- Import `setupRenderingTest` from `discourse/tests/helpers/component-test`, not from `ember-qunit`. The Discourse wrapper also sets up `this.siteSettings`, `this.site` and a logged-in `this.currentUser`. Pass `{ anonymous: true }` as the second argument to render as a guest.
- The module title ends with the component’s invocation name in PascalCase (`DPageSubheader`, not `d-page-subheader`).
- Assert with [qunit-dom](https://github.com/mainmatter/qunit-dom/blob/master/API.md) (`assert.dom(...)`), and give every assertion a description so a failure says what broke.
- Plugin components are imported from `discourse/plugins/<name>/discourse/components/...`.

## Interacting with the component

The helpers in `@ember/test-helpers` (`click`, `fillIn`, `triggerKeyEvent`, …) dispatch real DOM events and wait for the resulting render. Always `await` them.

To check what the component reports back, pass a function that records its calls with `assert.step`:

```gjs
import { click, render } from "@ember/test-helpers";
import DButton from "discourse/ui-kit/d-button";

test("calls @action on click", async function (assert) {
  const onClick = () => assert.step("clicked");

  await render(
    <template><DButton @action={{onClick}} @translatedLabel="Save" /></template>
  );
  await click(".btn");

  assert.verifySteps(["clicked"], "calls @action once");
});

```

## Changing arguments after render

To test how a component reacts when its arguments change, hold the value in a standalone `tracked()` from `@glimmer/tracking`. Pass its `.value` to the component, then assign a new `.value`:

```gjs
import { tracked } from "@glimmer/tracking";
import { render, rerender } from "@ember/test-helpers";

test("follows @titleLabel", async function (assert) {
  const title = tracked("First");

  await render(
    <template><DPageSubheader @titleLabel={{title.value}} /></template>
  );

  title.value = "Second";
  await rerender();

  assert
    .dom(".d-page-subheader__title")
    .hasText("Second", "shows the new title");
});

```

- Use one `tracked()` per argument, instead of `this.set(...)` on the test context or a test-only class with `@tracked` fields. Values that don’t change can be local constants, or native assignments to the test context (`this.title = "a"`) before render.
- When the component writes a value back through a callback, such as `@onChange`, the callback assigns the tracked value: `const onChange = (newValue) => (value.value = newValue)`. A value a callback only records for the test to assert on is a plain local `let`.
- When the test changes properties of an object it passes in, such as a model, make that object a `trackedObject` (from `@ember/reactive/collections`) and assign its properties instead.
- `await rerender()` before the next assertion or interaction: unlike `this.set`, a tracked write does not re-render synchronously. Use `await settled()` instead when the change starts async work, such as a request.
- Start with the first value the test asserts. To start empty, use `tracked(undefined)`: a bare `tracked()` returns a decorator, and so does a single plain object whose keys are all option names (`value`, `initializer`, `equals`, `description`). Passing options as well forces the value form: `tracked({}, {})`.
- Assigning a value that is `Object.is`-equal to the current one does not re-render. Pass `{ equals: () => false }` as the second argument if a test relies on that.

## Stubbing requests

A default [Pretender](https://github.com/pretenderjs/pretender) server answers common endpoints. Add or override a route inside the test:

```gjs
import pretender, { response } from "discourse/tests/helpers/create-pretender";

test("shows the loaded items", async function (assert) {
  pretender.get("/admin/things.json", () => response({ things: [] }));
  // render and assert...
});

```

`response(body)` replies with a 200; `response(status, body)` sets the status. Stub the network boundary like this rather than stubbing the component’s own collaborators.

* * *

This document is version controlled - suggest changes [on github](https://github.com/discourse/discourse/blob/main/docs/developer-guides/docs/03-code-internals/33-component-tests.md).
