maquette

Maquette is a lightweight JavaScript utility designed to synchronize the DOM tree in the browser with your application data using a Virtual DOM technique.

Key advantages include:

• Lightweight: Extremely small footprint (approx. 3.7Kb gzipped).
• Animations: Supports animating changes made to the DOM.
• Testability: Designed to make frontend logic easy to unit-test.

Navigate to the browser-tests directory to execute the tests using various modes:

To run the end-to-end browser tests, you must first build the maquette package and install the dependencies for the TodoMVC example from the repository root, then install the test dependencies within the browser-tests directory.

1. Prepare the Repository Root

From the repository root, install core dependencies and build the distribution files, then install the TodoMVC bower dependencies:

# From the repository root
npm ci
npm run dist

# Install TodoMVC bower dependencies
cd examples/todomvc
npm install --no-save bower
npx bower install
cd ../..

2. Install Test Dependencies

Navigate to the browser-tests directory to install Playwright and the Chromium browser:

cd browser-tests
npm install
npx playwright install chromium

The test suite uses the Page Object Model (POM) pattern to encapsulate page interactions. When writing new tests, follow these steps:

1. Update the Page Object: If you need to interact with new elements or perform new actions, add them to tests/TodoPage.ts.
2. Write the Spec: Create new spec files or add to tests/todomvc.spec.ts.
3. Group Tests: Use test.describe() to organize related test cases.
4. Use the Page Object: Always use the TodoPage instance for interactions and assertions to maintain consistency.

Example Test Case

test('should do something', async () => {
  await todoPage.addTodo('My todo');
  await todoPage.assertTodos(['My todo']);
});

While not strictly enforced by the core engine, the MaquetteComponent interface is a recommended pattern for building self-contained, reusable parts of your application.

To implement it, create an object or class with a render() method that returns a VNode or null.

interface MyComponent extends MaquetteComponent {
  render(): VNode {
    return h('div', { class: 'my-component' }, 'Hello World');
  }
}

The use object in the Playwright configuration defines shared settings for all test projects. For Maquette, these settings are optimized for local development and CI environments:

• baseURL: Set to http://127.0.0.1:8080 (uses 127.0.0.1 to avoid IPv6 resolution issues).
• actionTimeout: Timeout for actions like click or fill. Set to 3,000ms locally and 10,000ms on CI.
• expect.timeout: Timeout for assertions. Set to 3,000ms locally and 10,000ms on CI.
• trace: Set to on-first-retry to collect traces only when a test fails and is retried.
• screenshot: Set to only-on-failure to capture screenshots only when a test fails.

use: {
  baseURL: "http://127.0.0.1:8080",
  actionTimeout: process.env.CI ? 10000 : 3000,
  trace: "on-first-retry",
  screenshot: "only-on-failure",
},
expect: {
  timeout: process.env.CI ? 10000 : 3000,
}

The webServer configuration automatically manages a local development server before tests run.

• command: npx http-server .. -p 8080 -c-1 (starts a server on port 8080 with no cache).
• url: http://127.0.0.1:8080 (the URL to wait for before starting tests).
• reuseExistingServer: Set to true locally (if process.env.CI is not present) to speed up test runs if a server is already running.
• timeout: 120,000ms (time allowed for the server to start).

webServer: {
  command: "npx http-server .. -p 8080 -c-1",
  url: "http://127.0.0.1:8080",
  reuseExistingServer: !process.env.CI,
  timeout: 120 * 1000,
}

The projects array defines which browsers the tests should run against. By default, Maquette is configured for Chromium.

To test on other browsers, you can uncomment the following configurations:

• firefox: Uses devices['Desktop Firefox'].
• webkit: Uses devices['Desktop Safari'].

Example configuration for Chromium:

projects: [
  {
    name: "chromium",
    use: { ...devices["Desktop Chrome"] },
  },
],

The browser-tests directory is organized as follows:

• playwright.config.ts: Playwright configuration (defines web server on port 8080, browser defaults, and CI settings).
• package.json: Test dependencies and execution scripts.
• tests/TodoPage.ts: Page Object Model implementation for TodoMVC.
• tests/todomvc.spec.ts: Test specifications.
• README.md: Documentation.

The TodoPage class in tests/TodoPage.ts provides the following API for interacting with the TodoMVC application:

• Navigation: goto(), goBack()
• Actions: addTodo(), toggleTodoAt(), doubleClickTodoAt(), etc.
• Assertions: assertTodos(), assertCompletedStates(), etc.