feather-testing-core

A readable testing DSL that turns async test boilerplate into fluent, chainable steps.

Part of the Feather Framework ecosystem.

The Core Idea

This DSL defines a universal vocabulary — fillIn, clickButton, assertText, and more — that can be backed by any test framework. Playwright and React Testing Library are just the first two adapters. You write your tests once in a fluent, chainable style; the adapter handles the framework-specific details.

Before / After — Playwright E2E

Before (Vanilla Playwright):

test("sign up", async ({ page }) => {
  await page.goto("/");
  await expect(page.getByText("Hello, Anonymous!")).toBeVisible();
  await page.getByText("Sign up instead").click();
  await page.getByLabel("Email").fill("[email protected]");
  await page.getByLabel("Password").fill("password123");
  await page.getByRole("button", { name: "Sign up" }).click();
  await expect(page.getByText("Hello! You are signed in.")).toBeVisible();
});

After:

test("sign up", async ({ session }) => {
  await session
    .visit("/")
    .assertText("Hello, Anonymous!")
    .click("Sign up instead")
    .fillIn("Email", "[email protected]")
    .fillIn("Password", "password123")
    .clickButton("Sign up")
    .assertText("Hello! You are signed in.");
});

Before / After — React Testing Library

Before (Vanilla RTL):

test("form submission", async () => {
  render(<App />);
  const user = userEvent.setup();

  await user.type(screen.getByLabelText("Email"), "[email protected]");
  await user.type(screen.getByLabelText("Password"), "password123");
  await user.click(screen.getByRole("button", { name: "Sign in" }));
  expect(await screen.findByText("Hello! You are signed in.")).toBeInTheDocument();
});

After:

test("form submission", async () => {
  render(<App />);
  const session = createSession();

  await session
    .fillIn("Email", "[email protected]")
    .fillIn("Password", "password123")
    .clickButton("Sign in")
    .assertText("Hello! You are signed in.");
});

Same DSL, Any Backend

Notice both examples use the exact same methods — fillIn, clickButton, assertText. The DSL is framework-agnostic. Playwright and React Testing Library are just the first two adapters. You can implement the TestDriver interface for any testing library and get the same fluent syntax.

Inspired by Phoenix Test — Elixir's pipe-chain testing DSL.

Installation

npm install feather-testing-core

Note: This package is ESM-only ("type": "module"). It works with modern bundlers and test runners out of the box. If your project uses CommonJS require(), you'll need to update your config to support ESM imports.

All test framework dependencies are optional peers — install only what you use:

# For Playwright E2E tests
npm install @playwright/test

# For React Testing Library integration tests
npm install @testing-library/react @testing-library/user-event

Usage

Playwright E2E

// e2e/fixtures.ts
import { test as featherTest } from "feather-testing-core/playwright";
export const test = featherTest;
export { expect } from "@playwright/test";

// e2e/auth.spec.ts
import { test } from "./fixtures";

test("full auth lifecycle", async ({ session }) => {
  // Sign up
  await session
    .visit("/")
    .assertText("Hello, Anonymous!")
    .click("Sign up instead")
    .fillIn("Email", "[email protected]")
    .fillIn("Password", "password123")
    .clickButton("Sign up")
    .assertText("Hello! You are signed in.");

  // Sign out
  await session
    .clickButton("Sign out")
    .assertText("Hello, Anonymous!");

  // Sign in
  await session
    .fillIn("Email", "[email protected]")
    .fillIn("Password", "password123")
    .clickButton("Sign in")
    .assertText("Hello! You are signed in.");
});

React Testing Library

import { createSession } from "feather-testing-core/rtl";

test("form submission", async () => {
  render(<App />);
  const session = createSession();

  await session
    .fillIn("Email", "[email protected]")
    .fillIn("Password", "password123")
    .clickButton("Sign in")
    .assertText("Hello! You are signed in.");
});

API

Every method returns this for chaining. A single await at the start of the chain executes all steps sequentially.

Navigation

| Method | Description | |--------|-------------| | visit(path) | Navigate to URL (Playwright only) |

Interactions

| Method | Description | |--------|-------------| | click(text) | Find any element by text and click it | | clickLink(text) | Click <a> by accessible name | | clickButton(text) | Click <button> by accessible name | | fillIn(label, value) | Fill input by label or placeholder | | selectOption(label, option) | Select dropdown option by label | | check(label) / uncheck(label) | Toggle checkbox by label | | choose(label) | Select radio button by label | | submit() | Submit the most recently interacted form (see below) | | attachFile(label, path) | Set a file input (found by label) to the file at path | | dropFile(selector, path) | Dispatch a DataTransfer drop of the file onto a drop area | | pressKey(key) | Press a key on the focused control — 'Enter', 'Escape', 'Control+A' | | hover(text) | Hover the element with this text |

upload(label, path) is the former name of attachFile and still works, deprecated.

Interactions address controls exactly

Every interaction above names the control it wants, and that name is matched in full: clickButton("Check") clicks the button named Check, never the sidebar chip named "Checklist Run — checklist". Whitespace is still normalized, so multi-line markup and padded labels keep working.

This matters because Playwright's bare-string matchers are case-insensitive substring matchers. Left as-is, a verb aimed at one control silently widens to any other control whose name merely contains the same text — and the run dies on a strict-mode violation that only appears when both are on screen at once, which turns a naming collision into an ordering-dependent flake. RTL matches whole strings by default, so with this both adapters answer the same question.

Assertions are the deliberate exception: assertText / refuteText / assertHas ask "does this text appear", so they stay substring matches. An exact refuteText("Check") would pass while Checklist Run is plainly on the page.

To act on a control whose name is genuinely a prefix of another's, scope the lookup rather than loosening it:

await session.within("main", (s) => s.clickButton("Check"));

How submit() finds the submit button

submit() tracks the <form> element from the last fillIn, selectOption, check, uncheck, or choose call, then uses this strategy:

1. By type="submit" — looks for <button type="submit"> or <input type="submit"> (the DOM's ground truth)
2. By accessible name — looks for a <button> whose name contains "submit" (case-insensitive)
3. Enter key fallback — presses Enter on the last form field

If no form was previously interacted with, submit() throws an error.

File uploads

// Standard file input, found by its label
await session.attachFile("Avatar", "fixtures/avatar.png");

// Custom drop area (drag-and-drop upload zones)
await session.dropFile("#dropzone", "fixtures/report.pdf");

In Playwright, dropFile reads the real file and dispatches a drop event with a DataTransfer. In RTL (JSDOM has no filesystem), both verbs synthesize an empty File named after the path's basename — assert on the file name, not its contents.

Keys

pressKey names keys the Playwright way on both adapters: a single character types itself, a named key is 'Enter' / 'Escape' / 'ArrowDown', and modifiers combine with + ('Control+A', 'Meta+Enter'). The RTL adapter translates that to user-event's keyboard syntax, so one spec reads the same in both places. A prefix that is not Control, Shift, Alt, or Meta is rejected rather than typed as text.

Assertions

| Method | Description | |--------|-------------| | assertText(text) / refuteText(text) | Assert text is visible / not visible | | assertValue(label, value) | Assert a field (by label or placeholder) has this value | | assertChecked(label) / refuteChecked(label) | Assert a checkbox is checked / not checked | | assertSelected(label, optionLabel) | Assert the select's currently selected option | | assertOptions(label, [labels]) | Assert a select offers exactly these options, in order | | assertHas(selector, opts?) / refuteHas(...) | Assert element exists (Playwright only, see options below) | | assertPath(path, opts?) / refutePath(path) | Assert URL path (Playwright only, see options below) | | assertDownload(filename, trigger, opts?) | Assert trigger starts a download with this filename (Playwright only) |

Form-state assertions

await session
  .fillIn("Email", "[email protected]")
  .assertValue("Email", "[email protected]")
  .check("Subscribe")
  .assertChecked("Subscribe")
  .refuteChecked("Receive ads")
  .selectOption("Plan", "Pro")
  .assertSelected("Plan", "Pro")
  .assertOptions("Plan", ["Free", "Pro", "Enterprise"]);

In Playwright these are backed by toHaveValue / toBeChecked / toHaveText, so they auto-retry. The RTL adapter polls the DOM with waitFor for the same retry semantics.

Pair every refute with a positive assertion

refuteText / refuteHas assert absence — and absence also holds when the page failed to render at all. A blank page passes refuteHas(".delete-button"). Always pair a refute with a positive assertion on the same region so the test proves the page actually rendered:

// ❌ Passes even if the action bar never rendered
await session.refuteHas(".action-bar button", { text: "Delete" });

// ✅ The positive complement proves the action bar rendered with exactly [Import]
await session
  .assertHas(".action-bar button", { count: 1 })
  .assertHas(".action-bar button", { text: "Import" })
  .refuteHas(".action-bar button", { text: "Delete" });

assertHas / refuteHas options

| Option | Type | Description | |--------|------|-------------| | text | string | Filter elements to those containing this text | | count | number | Assert exact number of matching elements | | exact | boolean | When true, text matches as an exact substring. When false (default), matches as a regex | | timeout | number | Custom timeout in milliseconds (overrides Playwright default) |

// Assert at least one .card element is visible
await session.assertHas(".card");

// Assert a .card containing specific text
await session.assertHas(".card", { text: "Overdue" });

// Assert exact count
await session.assertHas("li.todo-item", { count: 3 });

// Assert with custom timeout
await session.assertHas(".loaded", { timeout: 10000 });

// Refute: assert no matching elements exist
await session.refuteHas(".spinner");
await session.refuteHas(".card", { text: "Deleted Item" });

assertPath / refutePath options

The path is compared against the URL's parsed pathname exactly — assertPath("/import") does not pass on /re/import.

// Assert path (ignores query params)
await session.assertPath("/projects");

// Assert path with specific query params
await session.assertPath("/search", { queryParams: { q: "hello", page: "1" } });

// Refute: assert you are NOT on this path
await session.refutePath("/login");

Downloads

The wait has to be armed before the click that starts the download, so the triggering steps go in a callback — the same shape as within():

await session
  .visit("/exports")
  .assertDownload("report.csv", (s) => s.clickButton("Export"))
  .assertText("Export complete");

filename is matched against the browser's suggested filename, exactly for a string or by test() for a RegExp. opts.timeout bounds the wait for the download to start. This is browser-only: the RTL adapter throws a BrowserOnlyVerbError, wrapped by the chain into a StepError that names the step.

Waiting: until(description, fn)

| Method | Description | |--------|-------------| | until(description, fn, opts?) | Poll fn until it returns something truthy, then continue |

Tests wait for conditions, not for clocks. until() is the honest alternative to a sleep: it polls a predicate you write, and the mandatory description is what the trace prints, so a timeout names the thing you were waiting for instead of the mechanism you waited with.

await session
  .visit("/exports")
  .clickButton("Export")
  .until("the export job reports done", ({ page }) =>
    page.evaluate(() => window.__exportDone),
  )
  .assertText("Download ready");

The predicate receives the adapter context — { page, scope } for Playwright, { user, container } for RTL — and may be sync or async. opts takes { timeout, interval } in ms; omit them to inherit the adapter's own budget (Playwright's expect.poll, RTL's waitFor).

When the budget runs out, the chain trace says what you were waiting for:

>>> [FAILED] until: the export job reports done

The description is required at the call site, before the chain runs — a blank one throws immediately, because a step named until: teaches a reader nothing. The feather-testing/no-wait-for-timeout lint rule (see Lint plugin) points at this verb, so "no sleeps" stops being a review convention and becomes a check.

Scoping

| Method | Description | |--------|-------------| | within(selector, fn) | Scope actions to a container element |

// All actions inside the callback are scoped to the matched element
await session
  .visit("/dashboard")
  .within(".sidebar", (s) =>
    s.clickLink("Settings").assertText("Preferences")
  )
  .assertText("Dashboard"); // back to full-page scope after within()

Escape hatches: step(name, fn) and raw(label, fn)

When you need something the DSL doesn't cover, queue a named custom step instead of abandoning the chain. The callback receives the adapter's context — { page, scope } for Playwright, { user, container } for RTL — and the name shows up in StepError output like any built-in step:

await session
  .visit("/board")
  .step("drag card to Done column", async ({ page }) => {
    await page.getByText("My card").dragTo(page.locator("#done"));
  })
  .assertText("Done (1)");

raw(label, fn) goes one level lower: it hands over the driver itself — Playwright's page, RTL's scoped query object — with no context wrapper. Use it when you want the native API and nothing else:

await session
  .visit("/board")
  .raw("stub the clipboard", (page) =>
    page.evaluate(() => navigator.clipboard.writeText("copied")),
  )
  .clickButton("Paste")
  .assertText("copied");

Both hatches take a mandatory label and register as named steps, so a failure inside one still names intent:

>>> [FAILED] raw('stub the clipboard')

That is the whole point of having them: an untraced raw tail ends the trace at the last DSL verb, and no hatch at all pushes teams to abandon the DSL mid-spec. In Playwright, raw always hands over the page, not the within() scope — re-scoping is the caller's job once you have left the DSL.

Debug

| Method | Description | |--------|-------------| | debug() | Playwright: saves a full-page screenshot to debug-{timestamp}.png in the CWD. RTL: calls screen.debug() to log the current DOM to the console. |

How It Works

The Session class uses a thenable action-queue pattern. Each method pushes an async operation onto an internal queue and returns this. The class implements PromiseLike<void>, so await triggers execution of the entire queue.

session.visit("/").fillIn("Name", "x").clickButton("Go")
       ↓              ↓                    ↓
    [push thunk]  [push thunk]        [push thunk]
                                           ↓
                                    await triggers
                                    sequential execution

This means you write one await per chain, not one per line.

Breaking chains

If you need conditional logic mid-flow, break into multiple chains:

await session.visit("/").fillIn("Email", email);

if (isNewUser) {
  await session.click("Sign up instead").clickButton("Sign up");
} else {
  await session.clickButton("Sign in");
}

Composable helpers

Functions that take and return a Session work as reusable steps:

function signIn(session: Session, email: string, password: string): Session {
  return session
    .fillIn("Email", email)
    .fillIn("Password", password)
    .clickButton("Sign in");
}

test("authenticated flow", async ({ session }) => {
  await signIn(session.visit("/"), "[email protected]", "pass123")
    .assertText("Welcome!");
});

Error Messages

When a step fails, StepError shows the full chain with status markers:

feather-testing-core: Step 4 of 6 failed

Failed at: clickButton('Sign up')
Cause: locator.click: getByRole('button', { name: 'Sign up' }) resolved to 0 elements

Chain:
    [ok] visit('/')
    [ok] assertText('Hello, Anonymous!')
    [ok] fillIn('Email', '[email protected]')
>>> [FAILED] clickButton('Sign up')
    [skipped] fillIn('Password', 'password123')
    [skipped] assertText('Hello! You are signed in.')

The session keeps a history of executed steps, so when you break a flow into multiple chains (multiple awaits), the StepError still shows the full walk — steps from earlier chains appear as [ok] above the failing chain.

With the Playwright adapter, each queued step is also wrapped in test.step(), so chains appear as named steps in the trace viewer and HTML report.

RTL Adapter Limitations

The RTL adapter runs in JSDOM, which has no real browser. These methods are not available and will throw:

• visit() — render the component directly instead
• assertPath() / refutePath() — no URL in JSDOM
• assertHas() / refuteHas() — RTL discourages CSS selectors; use assertText() instead
• assertDownload() — JSDOM has no download machinery; it throws BrowserOnlyVerbError naming the verb and pointing at a Playwright spec

The verbs JSDOM can honestly do, it does: attachFile synthesizes a File from the path's basename, pressKey translates to user-event's keyboard syntax, hover fires real pointer events, and raw hands over the scoped query object.

Extending the RTL adapter

RTLDriver is meant to be subclassed when an app's markup needs a different lookup, so that a host harness binds this DSL rather than reimplementing it. Everything worth specializing is protected:

| Member | Why you'd override it | |--------|----------------------| | findField(label) | The single label-addressed lookup. Every labelled verb — fillIn, selectOption, check, uncheck, upload, assertValue, assertChecked, assertSelected, assertOptions — goes through it, so one override retargets them all | | scoped(element) | Factory used by within(), so a scoped session keeps your driver's behaviour | | user, root, container, lastFormElement, timeout | Shared state the built-in verbs read and write |

class WrapperLabelDriver extends RTLDriver {
  // Labels with no htmlFor, control is a sibling inside a wrapper div
  protected override async findField(label: string): Promise<HTMLElement> {
    for (const l of this.rootElement().querySelectorAll("label")) {
      if (l.textContent?.trim() !== label) continue;
      const control = l.parentElement?.querySelector("input, textarea, select");
      if (control) return control as HTMLElement;
    }
    throw new Error(`no field labelled '${label}'`);
  }

  protected override scoped(element: HTMLElement) {
    return new WrapperLabelDriver(this.user, element, this.timeout);
  }
}

The third constructor argument is a per-lookup timeout in ms; omit it to keep RTL's own default.

Exports

// Core (Session class + types)
import {
  Session,
  StepError,
  BrowserOnlyVerbError,
  type TestDriver,
} from "feather-testing-core";

// Playwright adapter
import { test, createSession, expect } from "feather-testing-core/playwright";

// RTL adapter
import { createSession } from "feather-testing-core/rtl";

// ESLint plugin (see below)
import featherTesting from "feather-testing-core/eslint-plugin";

Both adapter subpaths also re-export Session and StepError, so you can import everything from a single path:

import { test, Session, StepError } from "feather-testing-core/playwright";
import { createSession, Session, StepError } from "feather-testing-core/rtl";

Lint plugin

The DSL can only offer good habits; a linter can insist on them. This package ships an ESLint plugin whose rules are the defect classes a real suite audit found by expensive reading — each one now a check that runs in a second, with a message that names the fix so whoever hits it (person or agent) learns the alternative from the error alone.

// eslint.config.js — flat config
import featherTesting from "feather-testing-core/eslint-plugin";

export default [
  {
    files: ["tests/**/*.ts", "e2e/**/*.spec.ts"],
    ...featherTesting.configs.recommended,
  },
];

Or wire the rules yourself:

import featherTesting from "feather-testing-core/eslint-plugin";

export default [
  {
    files: ["tests/**/*.ts"],
    plugins: { "feather-testing": featherTesting },
    rules: {
      "feather-testing/no-weak-assertions": ["error", { matchers: ["toBeTruthy", "toBeDefined", "toBeFalsy"] }],
    },
  },
];

| Rule | Catches | Points at | |------|---------|-----------| | no-wait-for-timeout | page.waitForTimeout(...), and the new Promise(r => setTimeout(r, n)) sleep idiom | session.until(description, fn), expect.poll, web-first assertions | | no-conditional-skip | test.skip(cond), test.skip(), this.skip() — a spec that un-tests itself at runtime | making the precondition part of the test, or test.fixme so the report names it | | no-weak-assertions | expect(x).toBeTruthy() / .toBeDefined() (configurable) | asserting the shape you mean | | no-swallowed-cleanup-catch | .catch(() => {}) and empty catch {} blocks | asserting on the error, rethrowing with context, or annotating the deliberate ignore | | warn-serial-mode | test.describe.serial(...), configure({ mode: "serial" }) — warning, not error | independent tests, or an eslint-disable line saying why serial is required |

Deliberate exceptions stay possible and stay visible: an eslint-disable-next-line comment with a reason is exactly the annotation these rules are trying to force.

Why these five. They are not style preferences. Each one is a way a suite goes green while proving nothing: a sleep passes on a slow machine and fails on a fast one, a conditional skip silently un-tests a spec for its entire life, toBeTruthy() accepts almost any value, a swallowed cleanup error surfaces three tests later as something else, and serial mode turns one failure into a wall of red that hides its own cause. session.until() exists so the first rule has an honest alternative to point at — see the document set for why conventions belong in executable form rather than in a style guide nobody re-reads.

Documentation

• The document set — the minimal set of documents a project needs, what each one answers, and why hand-maintained cross-reference matrices lose to generated reports plus CI checks.

License

MIT