Forem: Project Au Lait

A Test-First Approach with Playwright for Unstable Systems

Project Au Lait — Sat, 10 May 2025 02:18:43 +0000

This article introduces a method for achieving a test-first approach using E2E testing frameworks such as Playwright. This method addresses the following challenges encountered when attempting to automate tests:

You want to verify behavior while implementing test code, but the system under test is still unstable and doesn't run properly.
It's difficult to explain the content of the test code to non-engineers.

This approach assumes the design described in the previous article introducing the E2E test design pattern "Extended Page Object Model" here:

A common base class is created for PageElements, separating the Testing Framework APIs from PageElement and centralizing them in the base class.

A working implementation of this approach is available on GitHub.

Overview

This approach attempts to solve the above issues by adding the following features to the test code:

Execute test code without operating the browser.
Output the browser operation instructions to a file.

These features are collectively referred to as Dry Run below. The execution structure of the Dry Run feature is shown below:

In normal execution (real-run), BasePageElement operates the browser via BrowserController to perform tests. In contrast, during Dry Run execution (dry-run), BasePageElement does not use BrowserController and only outputs to DryRunLog.

The following sequence diagram illustrates this behavior:

PageElement instructs BasePageElement to operate screen elements.
In execution mode:
1. BasePageElement instructs BrowserController to operate the browser.
In Dry Run mode:
1. BasePageElement instructs DryRun to output a log.
2. DryRun outputs the screen operation details to a DryRunLog file.

The interactions and implementations of each component are described in the following sections.

PageElement -> BasePageElement

PageElement uses methods provided by BasePageElement to operate screen elements.
For example, the clickLoginButton method in LoginPagePageElement:

import BasePageElement from '@arch/BasePageElement';

export default class LoginPagePageElement extends BasePageElement {
  get pageNameKey() {
    return 'login';
  }

  async clickLoginButton() {
    await this.click('#login-form input[name="login"]');
  }
}

DryRun is not involved in the interaction between PageElement and BasePageElement. However, it is important that PageElement never directly uses the Playwright API and always does so via BasePageElement.

BasePageElement -> BrowserController

BasePageElement uses BrowserController to operate screen elements. In implementation, BrowserController is the Playwright API’s Page. BasePageElement adds control logic to skip using BrowserController during Dry Run and instead log the actions. Here's a simplified implementation of the click method with such control (see BasePageElement.ts for the full version):

import { expect, type Page } from '@playwright/test';
import { Action, DryRun } from '@arch/DryRun';

export default abstract class BasePageElement {
  private page : Page;
  abstract get pageNameKey(): string;

  protected async click(selector: string) {
    if (!DryRun.isOn) {
      await this.page.locator(selector).click();
    } else {
      const log = DryRun.log(this.pageNameKey, selector, Action.CLICK);
      await this.page.evaluate(`console.log(\`${log}\`);`);
    }
  }
}

The DryRun.log method receives information for identifying the action and outputs it to a file, while also printing it to the browser’s console.log, making it visible in Playwright’s Trace Viewer. Similar branching logic is implemented for methods like inputText and select.

DryRun

DryRun manages execution mode (normal or dry run), builds log strings, and outputs them to a file. Here's a simplified implementation (see DryRun.ts for the full version):

import fs from 'fs';

export enum Action {
  GOTO,
  CLICK,
  INPUT,
}

export class DryRun {

  constructor(public isOn: boolean, private readonly formatter: LogFormatter) {}

  log(pageNameKey: string, itemNameKey: string, action: Action, input?: string) {
    const pageName = this.resolvePageName(pageNameKey);
    const itemName = this.resolveItemName(itemNameKey);

    const logStr = this.formatter.format(pageName, itemName, action, input);

    fs.appendFileSync(this.filePath, str + '\n');
  }
}

DryRun logs are meant to show "what screen operations are performed in the test scenario." Therefore, the log string must include the following information:

Which screen? (pageNameKey)
Which screen element? (itemNameKey)
What action was taken? (action)
What value was used? (input)

Example DryRun log output:

Navigates to "/" on the top page.
Inputs "admin" in "Username" on the login screen.
Inputs "newadminpass" in "Password" on the login screen.
Clicks "Login Button" on the login screen.
Clicks "Project Menu" on the top page.
Clicks "Demo Project" on the top page.
Clicks "Work Packages Menu" on the project page.
Clicks "Create Button" on the project page.
Clicks "Task Link" on the project page.
Inputs "Test Subject onak9fp7aj8" in "Title" on the task input screen.
Inputs "High" in "Priority" on the task input screen.
Clicks "Save Button" on the task input screen.

Dry Run Log on Trace Viewer

The DryRun log output via console.log in BasePageElement appears in the Playwright Trace Viewer during normal execution like this:

You can view actual Playwright Report and Trace Viewer results of a Dry Run execution at the following URL:

Playwright Report + Trace Viewer

Conclusion

By integrating the Dry Run feature into test code, it becomes possible to execute test logic without operating the browser. In other words, test code can be run without accessing the target system. This allows implementation of test code even when the system is still unstable. Additionally, Dry Run logs provide a readable overview of test scenarios without reading the actual code, making them a valuable resource for non-engineering project members. For an implementation example and demo, refer to the following GitHub repository:

GitHub Repository

[Boost]

Project Au Lait — Mon, 05 May 2025 10:23:55 +0000

Project Au Lait

Apr 22 '25

SVQK - A Web Application Development Platform Using Svelte + Quarkus

#svelte #quarkus #playwright #opensource

Comments

2 min read

Design Pattern for Playwright End-to-End Testing

Project Au Lait — Wed, 30 Apr 2025 08:34:15 +0000

This article introduces a design pattern for end-to-end testing using Playwright. This pattern is an extension of the Page Object Model, aimed at improving test code readability and reducing the increase in code volume when adding more test scenarios or test data variations. This pattern is adopted by SVQK. A working implementation example and its test results are available in the following repositories:

Test Architecture

First, the structure of end-to-end testing using Playwright is illustrated below:

TestRunner: The Playwright test execution engine. It calls the test code (TestCode) and manages the start, progression, and completion of test scenarios. In implementation, it is the test function provided by Playwright.
TestCode: The main implementation of test scenarios and test cases. It describes user actions and expected behaviors, delegating browser control to BrowserController.
BrowserController: Directly controls the browser (Browser) using Playwright's browser operation APIs. It handles page transitions, button actions, element validations, etc. This is the page instance in Playwright.
Browser: A browser instance controlled by Playwright. It provides the user interface and accesses the application under test.
TestSubject: The actual web application under test. It is operated externally via the browser and its behavior is validated.

Component Structure

Next is the component structure of TestCode:

Spec: The entry point for Playwright tests. It generates Models (test data) using the Factory, and executes test scenarios using the Facade and PageObject.
Facade: Executes a series of screen operations and validations across multiple screens using PageObject.
PageObject: Executes a series of operations and validations within a single screen using PageElement. One class per screen and one method per operation sequence within the screen.
PageElement: Uses APIs provided by BasePageElement to perform UI operations and validations. One class per screen, and one method per screen element operation/validation.
Factory: Generates Models used in testing.

Each component is explained in detail below.

Spec

The Spec component runs the test scenario. The scenario is implemented as a Playwright test case, and operations and validations are implemented using the Facade and PageObject. Here is an example scenario for "Registering a task":

Log in as user admin
Select project Demo project
Register a task

import { DryRun } from '@arch/DryRun';
import LoginFacade from '@facades/LoginFacade';
import ProjectFactory from '@factories/ProjectFactory';
import TaskFactroy from '@factories/TaskFactory';
import UserFactory from '@factories/UserFactory';
import TopPage from '@pages/top/TopPage';
import { test, expect } from '@playwright/test';

test('Register a task', async ({ page }) => {
  const dryRun = DryRun.build();
  const topPage = new TopPage({ page, dryRun });
  const loginFacade = new LoginFacade();

  const admin = UserFactory.createAdmin();
  const demoProject = ProjectFactory.createDemoProject();

  const projectPage = await loginFacade.loginToProject(topPage, admin, demoProject);
  const taskInputPage = await projectPage.gotoTaskInputPage();

  const task = TaskFactroy.createTask();
  await taskInputPage.input(task);
});

Using Factories, Facades, and PageObjects instead of raw element manipulation makes the scenario's data (Model) and transitions clearer.

PageObject

PageObject handles a series of operations and validations within a screen. These are implemented using PageElement. Here's an example PageObject for a login screen:

import ChangePasswordPage from '@pages/changePassword/ChangePasswordPage';
import LoginPageElement from './LoginPageElement';
import BasePageElement from '@arch/BasePageElement';
import TopPage from '@pages/top/TopPage';
import { UserModel } from '@models/UserModel';

export default class LoginPage {
  private readonly loginPageEl: LoginPageElement;

  constructor(page: BasePageElement) {
    this.loginPageEl = new LoginPageElement(page);
  }

  async login(user: UserModel) {
    await this.loginPageEl.inputUserName(user.username);
    await this.loginPageEl.inputPassword(user.password);
    await this.loginPageEl.clickLoginButton();
    return new TopPage(this.loginPageEl);
  }

  async firstLogin(user: UserModel) {
    await this.login(user);
    return new ChangePasswordPage(this.loginPageEl);
  }
}

Each method in PageObject represents a screen-level action. If it includes a screen transition, the next PageObject is returned.

PageElement

PageElement is responsible for operations and validations of individual screen elements. One method per element operation/validation is implemented using BasePageElement. Example:

import BasePageElement from '@arch/BasePageElement';

export default class LoginPagePageElement extends BasePageElement {
  get pageNameKey() {
    return 'login';
  }

  async inputUserName(userName: string) {
    await this.inputText('#username', userName);
  }

  async inputPassword(password: string) {
    await this.inputText('#password', password);
  }

  async clickLoginButton() {
    await this.click('#login-form input[name="login"]');
  }
}

This allows developers to write logic using only screen-specific selectors, without being aware of Playwright APIs.

BasePageElement

BasePageElement is the superclass of PageElement, providing utility methods using the Playwright API. These methods standardize element access and allow abstracting complex UI behavior. Example:

import { expect, type Page } from '@playwright/test';

export default abstract class BasePageElement {
  page: Page;

  constructor(page: BasePageElement | { page: Page }) {
    this.page = page.page;
  }

  protected async open(path: string) {
    await this.page.goto(path);
  }

  protected async inputText(selector: string, value: any) {
    await this.page.locator(selector).fill(value.toString());
  }

  protected async select(selector: string, value: any) {
    const select = this.page.locator(selector);
    await select.click();
    const ariaControls = await select
      .locator('div.ng-input > input')
      .getAttribute('aria-controls');
    await this.page.locator(`#${ariaControls}`).getByText(value.toString()).click();
  }
}

The select method handles custom UI components not based on standard HTML.

Closed state:
Open state:

Facade

Facade coordinates multiple screen-level actions using PageObjects. Each method starts with one PageObject and returns another. Example:

import ProjectModel from '@models/ProjectModel';
import { UserModel } from '@models/UserModel';
import TopPage from '@pages/top/TopPage';

export default class LoginFacade {
  async loginToProject(topPage: TopPage, user: UserModel, project: ProjectModel) {
    const loginPage = await topPage.open();
    await loginPage.login(user);

    const projectPage = await topPage.selectProject(project);
    projectPage.gotoWorkPackages();

    return projectPage;
  }
}

Factory

Factory is used to generate test Models. This enables reuse across scenarios. Example:

import { UserModel } from '@models/UserModel';

export default class UserFactory {
  static createAdmin() {
    return {
      username: 'admin',
      password: 'admin'
    } as UserModel;
  }
}

Conclusion

This article introduced a design pattern that extends the Page Object Model. While the component structure is more complex than the basic POM, it enables scaling test scenarios and data patterns with clarity and minimal code. SVQK offers a reference implementation and a code generation tool to automate this structure. You can try it out in the Quickstart.

SVQK - A Web Application Development Platform Using Svelte + Quarkus

Project Au Lait — Tue, 22 Apr 2025 09:12:20 +0000

At Project Au Lait, we are developing and publishing an open-source asset called SVQK, which combines Svelte (Frontend) and Quarkus (Backend) for web application development. The asset includes automated testing tools and source code generation tools. This article introduces an overview of SVQK. (For instructions on how to use SVQK, refer to the Quick Start.)

Overview

Applications developed using SVQK are structured as follows:

The frontend provides a user interface that runs in the browser, handling input validation and data input/output using Web APIs. The backend provides Web APIs and handles transaction control, business logic execution, and database access internally.

Setup

SVQK is published on Maven Central as a Maven archetype (project template). To develop a web application using SVQK, first create a project using the following Maven command:

mvn archetype:generate \
  -DarchetypeGroupId=dev.aulait.svqk \
  -DarchetypeArtifactId=svqk-archetype-refimpl \
  -DarchetypeVersion=0.9 \
  -DgroupId=my.group.id  \
  -DartifactId=my-artifactid \
  -Dversion=1.0-SNAPSHOT

The created project includes the following tools and scripts:

Docker + PostgreSQL
Flyway + DB Migration scripts
Quarkus
SvelteKit
Playwright + End-to-End Test scripts

After creating the project, set up these tools and scripts using the following command:

./mvnw install -T 1C -P setup

This command not only sets up the tools and scripts but also runs tests to verify that the tools and applications work as expected. The tests include unit tests for backend components, integration tests for manipulating Web APIs using a Rest Client, and end-to-end tests for frontend operations using Playwright. This setup command can be executed both on a local PC and in a CI environment.

Source Code Generation

SVQK projects include a source code generation tool using Yeoman. This tool generates source code for screens and APIs that perform CRUD operations on tables. Additionally, it supports generating end-to-end tests and integration tests for the screens and APIs.

Summary

By using SVQK, you can quickly set up an environment for developing web applications with Svelte + Quarkus. The tests for the developed applications are automated and can be executed on both local PCs and CI environments. For instructions on how to use SVQK, refer to the Quick Start.