Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions e2e/playwright/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,67 @@ docker/run.sh --update-snapshots # rewrite the etalons of the tests that ran
The etalons here are recorded anew, not copied from `e2e/testcafe-devextreme`: the two runners
crop and render differently, so a TestCafe image is not a valid reference for this suite.

It is still the check of the port. Recording writes whatever the test reached, and a verify run
compares against that same file, so neither notices a test that shot the wrong state. Before
deleting the TestCafe etalon, compare the new one with it: the same picture, within the per-pixel
threshold. Three differences are expected:

- A scrollbar. This suite shows it, TestCafe cut it off, so a viewport shot of a page that
overflows comes out up to 15 px larger, with the scrollbar in the extra strip.
- Anything under a TestCafe mask (`<name>_mask.png` next to the etalon, black where ignored).
- Single antialiased pixels on the edges of shapes that sit on fractional coordinates. The TestCafe
comparer ignored antialiasing (looks-same, `ignoreAntialiasing`, tolerance 5), so its etalon
could drift there unnoticed; this suite compares them strictly.

Anything else, a block of pixels or a moved edge, means the test reached a different state; find
out why rather than accept the image.

**Masks.** `testScreenshot` takes no mask, and the usual reason for one is gone:
`toHaveScreenshot` stops CSS animations (an infinite one at its first frame) and hides the caret.
Port a masked test without its mask, then run it strictly in the container a few times in a row
(`--repeat-each 10`). If it is stable, delete the mask with the TestCafe etalon. If it is not, make
the state deterministic (stop the animation, fix the data or the clock) rather than hide it.

Migrating a test means, in one PR: port the test, record its etalon here, and delete the TestCafe
test together with its etalon. The two sets must never cover the same case at once — a stale pair
left behind gets updated by whoever touches the component next and starts asserting a render
nobody checks.

### Record etalons on a Mac

The image is `linux/amd64`, the platform of the CI agent. On Apple Silicon it runs through Rosetta;
under QEMU emulation Chrome is several times slower. [Colima](https://github.com/abiosoft/colima)
gives the `docker` CLI a free runtime that uses Rosetta:

```bash
softwareupdate --install-rosetta --agree-to-license
brew install colima docker docker-buildx
colima start --vm-type vz --vz-rosetta --cpu 4 --memory 8
docker run --rm --platform linux/amd64 ubuntu:24.04 uname -m # prints x86_64
```

4 CPUs and 8 GB are enough for a component folder: `docker/run.sh` takes half the cores, so two
workers. Give the VM more for a larger run (`colima stop`, then `colima start --cpu 8 --memory 12`).
After a reboot, `colima start` brings it back with the same settings.

The container uses the host's `node_modules` and DevExtreme build, so build first and rebuild after
a source change. Then, from `e2e/playwright`, record and verify the etalons of the folder in both
themes the CI jobs run:

```bash
pnpm exec nx build devextreme-scss # from the repository root
pnpm exec nx build devextreme -c testing

docker/run.sh --update-snapshots tests/editors/selectBox/
THEME=fluent-next.blue.light docker/run.sh --update-snapshots tests/editors/selectBox/

docker/run.sh tests/editors/selectBox/
THEME=fluent-next.blue.light docker/run.sh tests/editors/selectBox/
```

The first run builds the image and takes a few minutes. Look through the new files before
committing them, as with etalons from CI.

### Etalons from CI

Without a container, CI records the etalons. A test whose etalon does not exist fails, and
Expand Down Expand Up @@ -183,6 +239,13 @@ viewport is 1200×800 and the widgets of the previous test are disposed.
Port a test one to one: the same steps, the same checks, the same screenshot names. A title changes
only when it repeats in the file, which Playwright rejects: add the loop parameters to it.

**`runInTheme`.** In TestCafe it was a filter, not a setting: the test ran only in the job whose
theme matched — usually one of the whole-suite theme jobs — and the folder jobs skipped it.
`test.use({ theme })` instead runs the test in that theme in every job that takes its folder, the
default and the `- fluent-next` one. That is the port: the result does not depend on the job, and a
screenshot keeps one etalon named after the pinned theme. Do not add a theme tag on top of it: the
test would run once more in the tagged job.

**Typing.** `fill` sets the value at once and sends no key events, so masked, numeric and date
editors do not react to it. Type with `pressSequentially`, and press keys under their Playwright
names: `Enter`, `Escape`, `ArrowLeft`, `Control+a`.
Expand All @@ -202,5 +265,15 @@ the observer runs.
that is not the target. TestCafe delivered a click to a covered element anyway, so a test that
relied on it needs the target made reachable, not the check switched off.

**Scrolling before a click.** TestCafe scrolled the whole target into view before a click;
Playwright scrolls only as far as the click point. When the target is wider or taller than the
window, the focus then scrolls the page after the click, and a drop-down closes on that scroll —
sometimes before the next step, sometimes after it. Scroll the target into view first, as TestCafe
did: `element.scrollIntoView({ block: 'nearest', inline: 'nearest' })` in `locator.evaluate`.

**Page errors.** A test fails on an uncaught error in the page, as it did in TestCafe. A test whose
TestCafe version ended with `expect(true).ok()` checks exactly that and needs no assertion.

**Old models.** A model in `packages/testcafe-models` that the ported tests used goes in the same
PR, but only after a search proves nothing else uses it: grep all of `e2e/` and `packages/` for its
import path, since other tests and other models import models too. A model still in use stays.
13 changes: 13 additions & 0 deletions e2e/playwright/models/dropDownButton.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
import type { Locator } from '@playwright/test';
import type { WidgetName } from './types';
import DropDownList from './internal/dropDownList';

export default class DropDownButton extends DropDownList {
// eslint-disable-next-line class-methods-use-this
public getName(): WidgetName { return 'dxDropDownButton'; }

// The widget element itself names the popup content.
public getPopupOwner(): Locator {
return this.element;
}
}
13 changes: 13 additions & 0 deletions e2e/playwright/models/internal/classMatcher.ts
Original file line number Diff line number Diff line change
@@ -1 +1,14 @@
import type { Locator } from '@playwright/test';
import { expect } from '@playwright/test';

export const classMatcher = (className: string): RegExp => new RegExp(`(^|\\s)${className}(\\s|$)`);

export const expectClass = async (
locator: Locator,
className: string,
present = true,
): Promise<void> => {
const assertion = expect(locator);

await (present ? assertion : assertion.not).toHaveClass(classMatcher(className));
};
59 changes: 59 additions & 0 deletions e2e/playwright/models/internal/dropDownList.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
import type { Locator, Page } from '@playwright/test';
import { expect } from '@playwright/test';
import List from '../list';
import TextBox from '../textBox';

const ATTR = {
popupId: 'aria-owns',
};

const CLASS = {
dropDownButton: 'dx-dropdowneditor-button',
invisible: 'dx-state-invisible',
list: 'dx-list',
};

export default abstract class DropDownList extends TextBox {
public readonly dropDownButton: Locator;

constructor(page: Page, selector: Locator | string) {
super(page, selector);

this.dropDownButton = this.element.locator(`.${CLASS.dropDownButton}`);
}

// The element that names the popup content in "aria-owns" once the popup is rendered; the
// content itself sits in an overlay wrapper elsewhere in the body.
public getPopupOwner(): Locator {
return this.input;
}

public isOpened(): Promise<boolean> {
return this.getPopupOwner().evaluate((owner, { attr, invisible }) => {
const popupId = owner.getAttribute(attr);
const popup = popupId ? document.getElementById(popupId) : null;

return !!popup && !popup.parentElement?.classList.contains(invisible);
}, { attr: ATTR.popupId, invisible: CLASS.invisible });
}

public async getPopup(): Promise<Locator> {
const owner = this.getPopupOwner();

await expect(owner).toHaveAttribute(ATTR.popupId, /./);

const popupId = await owner.getAttribute(ATTR.popupId);

return this.page.locator(`#${popupId}`);
}

public async getList(): Promise<List> {
await expect.poll(() => this.isOpened()).toBe(true);

return new List(this.page, (await this.getPopup()).locator(`.${CLASS.list}`));
}

public async open(): Promise<void> {
await this.invoke('open');
}
}
9 changes: 3 additions & 6 deletions e2e/playwright/models/internal/widget.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
import type { Locator, Page } from '@playwright/test';
import { expect } from '@playwright/test';
import type { WidgetName } from '../types';
import { hasClass } from './hasClass';
import { classMatcher } from './classMatcher';
import { expectClass } from './classMatcher';

const CLASS = {
focused: 'dx-state-focused',
Expand All @@ -29,10 +28,8 @@ export default abstract class Widget {
return `dx-${widgetName.slice(2).toLowerCase() + (className ? `-${className}` : '')}`;
}

public async expectClass(className: string, present = true): Promise<void> {
const assertion = expect(this.element);

await (present ? assertion : assertion.not).toHaveClass(classMatcher(className));
public expectClass(className: string, present = true): Promise<void> {
return expectClass(this.element, className, present);
}

public expectState(state: WidgetState, present = true): Promise<void> {
Expand Down
28 changes: 28 additions & 0 deletions e2e/playwright/models/list/checkBox.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
import type { Locator } from '@playwright/test';
import { expectClass } from '../internal/classMatcher';

const CLASS = {
checkBox: 'dx-checkbox',
checked: 'dx-checkbox-checked',
focused: 'dx-state-focused',
};

export default class ListItemCheckBox {
public readonly element: Locator;

private readonly item: Locator;

constructor(item: Locator) {
this.item = item;
this.element = item.locator(`.${CLASS.checkBox}`);
}

public expectChecked(present = true): Promise<void> {
return expectClass(this.element, CLASS.checked, present);
}

// The list moves the focus between its items; the check box itself never takes it.
public expectFocused(present = true): Promise<void> {
return expectClass(this.item, CLASS.focused, present);
}
}
34 changes: 34 additions & 0 deletions e2e/playwright/models/list/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
import type { Locator, Page } from '@playwright/test';
import type { WidgetName } from '../types';
import Widget from '../internal/widget';
import ListItem from './item';

const CLASS = {
item: 'dx-list-item',
nestedItem: 'nested-item',
selectAll: 'dx-list-select-all',
};

export default class List extends Widget {
public readonly items: Locator;

public readonly selectAll: ListItem;

constructor(page: Page, selector: Locator | string) {
super(page, selector);

this.items = this.element.locator(`.${CLASS.item}:not(.${CLASS.nestedItem})`);
this.selectAll = new ListItem(this.element.locator(`.${CLASS.selectAll}`));
}

// eslint-disable-next-line class-methods-use-this
public getName(): WidgetName { return 'dxList'; }

public getItem(index = 0): ListItem {
return new ListItem(this.items.nth(index));
}

public async scrollTo(value: number): Promise<void> {
await this.invoke('scrollTo', value);
}
}
22 changes: 22 additions & 0 deletions e2e/playwright/models/list/item.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
import type { Locator } from '@playwright/test';
import { expectClass } from '../internal/classMatcher';
import ListItemCheckBox from './checkBox';

const CLASS = {
disabled: 'dx-state-disabled',
};

export default class ListItem {
public readonly element: Locator;

public readonly checkBox: ListItemCheckBox;

constructor(element: Locator) {
this.element = element;
this.checkBox = new ListItemCheckBox(element);
}

public expectDisabled(present = true): Promise<void> {
return expectClass(this.element, CLASS.disabled, present);
}
}
25 changes: 25 additions & 0 deletions e2e/playwright/models/lookup.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import type { Locator, Page } from '@playwright/test';
import type { WidgetName } from './types';
import DropDownList from './internal/dropDownList';

const CLASS = {
field: 'dx-lookup-field',
};

export default class Lookup extends DropDownList {
public readonly field: Locator;

constructor(page: Page, selector: Locator | string) {
super(page, selector);

this.field = this.element.locator(`.${CLASS.field}`);
}

// eslint-disable-next-line class-methods-use-this
public getName(): WidgetName { return 'dxLookup'; }

// Lookup has no text input: the field takes its place.
public getPopupOwner(): Locator {
return this.field;
}
}
9 changes: 3 additions & 6 deletions e2e/playwright/models/radioGroup/button.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
import type { Locator } from '@playwright/test';
import { expect } from '@playwright/test';
import { classMatcher } from '../internal/classMatcher';
import { expectClass } from '../internal/classMatcher';

const CLASS = {
valueContainer: 'dx-radio-value-container',
Expand All @@ -18,9 +17,7 @@ export default class RadioButton {
this.element = item.locator(`:scope > .${CLASS.valueContainer} > .${CLASS.icon}`);
}

public async expectChecked(present = true): Promise<void> {
const assertion = expect(this.item);

await (present ? assertion : assertion.not).toHaveClass(classMatcher(CLASS.checked));
public expectChecked(present = true): Promise<void> {
return expectClass(this.item, CLASS.checked, present);
}
}
7 changes: 7 additions & 0 deletions e2e/playwright/models/selectBox.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import type { WidgetName } from './types';
import DropDownList from './internal/dropDownList';

export default class SelectBox extends DropDownList {
// eslint-disable-next-line class-methods-use-this
public getName(): WidgetName { return 'dxSelectBox'; }
}
20 changes: 20 additions & 0 deletions e2e/playwright/models/tagBox.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
import type { Locator, Page } from '@playwright/test';
import type { WidgetName } from './types';
import SelectBox from './selectBox';

const CLASS = {
tag: 'dx-tag',
};

export default class TagBox extends SelectBox {
public readonly tags: Locator;

constructor(page: Page, selector: Locator | string) {
super(page, selector);

this.tags = this.element.locator(`.${CLASS.tag}`);
}

// eslint-disable-next-line class-methods-use-this
public getName(): WidgetName { return 'dxTagBox'; }
}
10 changes: 10 additions & 0 deletions e2e/playwright/models/textBox.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
import type { Locator, Page } from '@playwright/test';
import type { WidgetName } from './types';
import Widget from './internal/widget';
import Button from './button';

const CLASS = {
input: 'dx-texteditor-input',
label: 'dx-label',
buttonsContainer: 'dx-texteditor-buttons-container',
button: 'dx-button',
};

export default class TextBox extends Widget {
Expand All @@ -19,6 +22,13 @@ export default class TextBox extends Widget {
// eslint-disable-next-line class-methods-use-this
public getName(): WidgetName { return 'dxTextBox'; }

public getButton(index = 0): Button {
return new Button(
this.page,
this.element.locator(`.${CLASS.buttonsContainer} > .${CLASS.button}`).nth(index),
);
}

public getLabel(): Locator {
return this.element.locator(`.${CLASS.label}`);
}
Expand Down
Loading
Loading