ember-cli-page-object

The ember-cli-page-object addon is a tool for creating page objects for acceptance and integration tests in Ember applications. It allows you to model complex pages and components using a declarative syntax, reducing the need for repetitive CSS selectors in your tests and providing a clean, high-level interface for DOM interactions.

import {
  create,
  visitable,
  fillable,
  clickable,
  text
} from 'ember-cli-page-object';

const page = create({
  visit: visitable('/'),

  username: fillable('#username'),
  password: fillable('#password'),
  submit: clickable('button'),
  error: text('.errors')
});

test('my awesome test', async function(assert) {
  await page
    .visit()
    .username('admin')
    .password('invalid')
    .submit();

  assert.equal(page.error, 'Invalid credentials');
});

The scope attribute defines the CSS selector that encloses a component. By default, nested components inherit the parent's scope to build a specific selector (e.g., .parent .child).

If you need a nested component to ignore the parent's scope and use an absolute selector, set resetScope: true in its definition.

const form = create({
  scope: '.my-form',

  dialog: {
    scope: '.some-dialog',
    resetScope: true
  }
});

// dialog will be searched for using '.some-dialog' instead of '.my-form .some-dialog'

Attributes are declarative wrappers around DOM operations. They can be used to query state (getters) or perform operations (actions).

• Attributes: Used to query values like text() or value(). You can pass a selector to an attribute to add specificity beyond the component's scope.
• Actions: Special attributes that perform asynchronous DOM operations. They return a Promise-like chainable page object node, allowing you to chain multiple operations in a single await statement.

Commonly used default attributes include click, fillIn, isVisible, isPresent, text, and value.

import { create, fillable, triggerable } from 'ember-cli-page-object';

const form = create({
  scope: 'form.search-form',

  fillIn: fillable('input[type="search"]'),
  submit: triggerable('submit')
});

// Actions are chainable
await form
  .fillIn('some text')
  .submit();

Components are functional fragments of the DOM described using plain objects. You define a component by specifying its scope (a CSS selector) and its attributes or methods. Component instances are created using the create function.

For complex interfaces, compose simpler component definitions into larger ones. When a component is nested, its selector is calculated by combining the parent's scope with the child's scope.

import { create, clickable, fillable } from 'ember-cli-page-object';

const FormDefinition = {
  scope: '.awesome-form',

  firstName: fillable('#firstName'),
  lastName: fillable('#lastName'),
  submit: clickable('button')
};

const form = create(FormDefinition);

await form
  .firstName('John')
  .lastName('Doe')
  .submit();

A Page Object represents a complete route/template in your application. It is composed of various page-object-components and can include attributes like visitable for navigation and collection for lists of elements.

Unlike components, Page Objects are typically exported as an instance created via create(), allowing them to be imported and used directly in acceptance tests.

You can also define native asynchronous methods on a Page Object to provide high-level APIs that orchestrate multiple component interactions.

$ ember generate page-object search-page

You can add native JavaScript functions and getters to your component definitions to create higher-level, domain-specific APIs for your tests. This is useful for grouping multiple low-level interactions into a single logical step or transforming data (e.g., mapping a collection of elements to an array of strings).

import { collection } from 'ember-cli-page-object';

const MyForm = {
  errors: collection('ul.errors > li'),

  title: { scope: '#firstName' },
  description: { scope: '#lastName' },
  submitButton: { scope: 'button' },

  async submit(data) {
    await this.title.fillIn(data.username);
    await this.description.fillIn(data.password);
    return this.submitButton.click();
  }

  get errorMessages() {
    return this.errors.map((e) => e.text);
  }
};

A Page Object Component is the primary building block of the library. It consists of a scope, attributes, custom methods, and nested components. You can generate a component definition using the ember generate page-object-component command.

To define a component, you specify its CSS scope and then define its attributes (like text inputs or buttons). You can use triggerable to define action attributes that trigger DOM events.

$ ember generate page-object-component search-form

The addon provides blueprints to scaffold common Page Object patterns. You can use the ember generate command to create these files.

Available Blueprints

• page-object: Creates a new page object.
• page-object-component: Creates a new component to be used in a page object.
• page-object-helper: Creates a new helper to be used in a page object.

Example: Generating a Page Object

To create a new page object named users, run:

$ ember generate page-object users

This will create the file at tests/pages/users.js.

You can install the addon using the Ember CLI install command or by adding the NPM package directly to your development dependencies.

Using Ember CLI

$ ember install ember-cli-page-object

Using NPM

$ npm install --save-dev ember-cli-page-object