[!WARNING] DEPRECATED — This package is deprecated. Use @uxf/e2e-playwright for new projects.
TestCafe helpers for end-to-end testing of UXF components. Each helper is a factory that locates a UXF component by its uxf-* class name / data-name attribute and exposes interaction and assertion methods.
Reach for this package only in existing suites that already run on TestCafe. For anything new, use @uxf/e2e-playwright instead — it is the actively maintained successor built on Playwright, with the same idea (component-scoped helpers) but a different, better API.
Key differences from @uxf/e2e-playwright:
@uxf/e2e (this package) |
@uxf/e2e-playwright |
|
|---|---|---|
| Runner | TestCafe | Playwright |
| Entry point | components object + waitForReact |
createUi(page) factory |
| Form finder field | name ({ name: "email" }) |
$name ({ $name: "email" }) |
| Status | Deprecated | Maintained |
This is a test-only toolkit — it is not a component library and renders nothing.
yarn add @uxf/e2e
Requires TestCafe 3.7.2 as a peer dependency (the only peer/runtime dependency):
yarn add -D testcafe@3.7.2
Tests target a deployed app. The example suite in this package reads the base URL from the BASE_URL environment variable.
waitForReact must run before the first interaction so the React tree is mounted (it replaces TestCafe's own waitForReact, which does not work with the Next.js App Router).
import { fixture, test } from "testcafe";
import { components, waitForReact } from "@uxf/e2e";
fixture("Button")
.page(`${process.env.BASE_URL}/examples/ui/button/Default`)
.beforeEach(async (t) => {
await waitForReact(10000, t);
});
test("UI Button", async () => {
await components.button({ text: "Default" }).click();
await components.button({ text: "Default" }).shouldExists();
await components.button({ text: "Not found" }).shouldNotExists();
await components.button({ text: "Disabled" }).shouldBeDisabled();
});
The public entry (@uxf/e2e) exports exactly two symbols:
| Export | Signature | Description |
|---|---|---|
waitForReact |
(timeout: number, testController: TestController) => Promise<void> |
Resolves once a React root is found in the DOM, or rejects after timeout ms. Call it in beforeEach. |
components |
object of helper factories (see below) | Every UXF component helper, grouped under one object. |
Individual helpers also resolve as deep imports by filesystem (there is no exports map), e.g. import { button } from "@uxf/e2e/ui/button" — but components is the intended surface.
Every helper takes a finder object and returns an object of methods. All finders extend BaseFinder:
type BaseFinder = { parent?: Selector }; // scope the search to a subtree; defaults to <body>
Two families build on it:
text, buttonText, iconName, or dataTestId (see table).FormComponentFinder): add name: string, matched against the component's data-name attribute (or the name attribute for input / dropzone). Note this is name, not $name as in @uxf/e2e-playwright.| Helper | Finder | Methods |
|---|---|---|
button |
{ text, nth?, parent? } |
click(), shouldExists(), shouldNotExists(), shouldBeDisabled(), shouldNotBeDisabled() |
iconButton |
{ iconName, nth?, parent? } |
click(), shouldExists(), shouldNotExists(), shouldBeDisabled(), shouldNotBeDisabled() |
buttonGroup |
{ dataTestId, parent? } |
clickOnButtonByText(text), shouldExists(), shouldExistsButtonByText(text) |
buttonList |
{ nth?, parent? } |
clickOnButton(text) |
checkboxButton |
{ buttonText, parent? } |
click(), shouldBeChecked(), shouldNotBeChecked(), shouldExist() |
textLink |
{ text, nth?, parent? } |
click(), shouldExists(timeout?), shouldNotExists(timeout?) |
toolbarTab |
{ text, nth?, parent? } |
click(), shouldExists(), shouldNotExists(), shouldBeActive(), shouldNotBeActive() |
flashMessage |
{ parent? } (optional) |
shouldExists(timeout?), shouldNotExists(timeout?), shouldContainsText(text, timeout?) |
message |
{ parent? } |
shouldExist(), shouldNotExist() |
modal |
{ parent? } |
shouldExist(timeout?), shouldNotExist(timeout?) |
All locate by { name } (data-name / name attribute); those noted also accept nth?.
| Helper | Value type | Methods |
|---|---|---|
input |
string |
type(value), replace(value), shouldHaveValue(value), shouldBeDisabled(), shouldNotBeDisabled(), shouldExist(), shouldNotExist() |
textInput |
string |
same surface as input (type, replace, shouldHaveValue, shouldBeDisabled, shouldNotBeDisabled, shouldExist, shouldNotExist) |
textarea (nth?) |
string |
type(value), replace(value), shouldHaveValue(value), shouldBeDisabled(), shouldNotBeDisabled(), shouldBeReadonly() |
checkboxInput |
boolean |
click(), shouldBeChecked(), shouldNotBeChecked(), shouldExist(), shouldBeDisabled() |
toggle (nth?) |
boolean |
click(), shouldExists(), shouldNotExists(), shouldBeSelected(), shouldNotBeSelected(), shouldBeDisabled(), shouldNotBeDisabled() |
radioGroup |
string |
selectByText(text), shouldBeSelected(text), shouldNotBeSelected(text) |
select |
string |
selectNthItem(nth), selectItemWithText(optionText, nth?), shouldHaveValue(value), shouldBeEmpty(), shouldNotBeEmpty(), shouldBeDisabled(), shouldNotBeDisabled(), shouldExists(), shouldNotExists(), clear() |
multiSelect (nth?) |
string[] |
selectItemsByText(texts), selectItemsByIndex(indexes), removeItemsByText(texts), removeItemsByIndex(indexes), shouldHaveValues(texts), shouldNotHaveValues(texts), shouldExist(), shouldBeDisabled(), shouldBeInvalid() |
combobox (nth?) |
string |
typeTextAndSelectItemByIndex(text, index?, timeout?), selectItemWithTextFromDropdown(text, timeout?), replace(text, index?), shouldHaveValue(value, timeout?), shouldBeEmpty(timeout?), shouldExist(timeout?), shouldBeDisabled(timeout?), shouldNotBeDisabled(timeout?), shouldBeInvalid(timeout?), shouldShowInvalidText(text), shouldBeRequired() |
multiCombobox (nth?) |
string[] |
selectItemByTypeText(text, timeout?, index?), selectItemFromDropdown(text, timeout?), replace(text, index?), shouldHaveValue(value, timeout?), shouldExist(timeout?), shouldBeDisabled(timeout?), shouldBeInvalid(timeout?) |
datePickerInput (nth?) |
Date parts |
selectDate(DD, MM, YYYY), replace(DD, MM, YYYY), shouldHaveValue(value), clear(), shouldBeEmpty(), shouldBeDisabled(), shouldNotBeDisabled(), shouldBeInvalid() |
datetimePickerInput (nth?) |
Date parts |
selectDatetime(DD, MM, YYYY, hr, min), replace(DD, MM, YYYY, hr, min), shouldHaveValue(value), clear(), shouldBeEmpty(), shouldBeDisabled(), shouldNotBeDisabled(), shouldBeInvalid() |
dropzone |
string[] (file paths) |
uploadFiles(files, timeout?), uploadedFilesShouldExist(files), uploadedFilesShouldNotExist(files), removeUploadedFile(fileName), shouldExists(), shouldNotExists(), shouldBeDisabled(), shouldNotBeDisabled() |
select also accepts a second positional argument: select(finder, selectIndex = 0).
| Helper | Methods |
|---|---|
components.cms.menu() |
openLink(mainLabel, subLabel?, index?), openBurgerMenu(), openUserMenu(), openUserMenuLink(label, device?), shouldExistsLink(label), shouldNotExistsLink(label) |
import { components } from "@uxf/e2e";
const email = components.textInput({ name: "email" });
await email.type("test@example.com");
await email.shouldHaveValue("test@example.com");
await components.select({ name: "country" }).selectItemWithText("Česká republika");
await components.combobox({ name: "city" }).typeTextAndSelectItemByIndex("Praha", 0, 5000);
await components.dropzone({ name: "avatar" }).uploadFiles(["./Jpg-test.jpg"], 20000);
await components.flashMessage().shouldContainsText("Uloženo", 5000);
waitForReact first (in beforeEach). The package's own waitForReact — not TestCafe's — is required; the standard one does not detect the Next.js App Router's React tree.name, not $name. @uxf/e2e-playwright renamed it to $name; do not copy that shape here.shouldExists()/shouldNotExists() on some helpers (button, select, toggle, dropzone, textLink) but shouldExist()/shouldNotExist() on others (input, textInput, checkboxInput, checkboxButton, message, modal). Follow the table above per helper.Date (selectDate(DD, MM, YYYY)), and assert against a DD.MM.YYYY string._uploads_ folder (see tests/_uploads_/) and pass paths like "./Jpg-test.jpg".nth / index arguments default to 0. Numeric column indexes and nth selectors count every matching element on the page, including scoped-out ones — pass parent to narrow the search.