Query Engines

[ro0gr]

Right now we do only support jquery selectors, which is the largest blocker to get rid of this dependency(https://github.com/san650/ember-cli-page-object/issues/289). Meanwhile it seems that support for different search engines like xpath, or a11y finders does also makes sense.

Suggestion

Provide a way to specify a desired query engine for each selector in design time:

const Page = {
  scope: '.Page', // default engine is used

  form: xpath('//form', {
    name: byLabel('Name:', inputDefinition),
   
    save: byText('Save', buttonDefinition)
  }),
}

I don't have a good name for the utils like xpath and byText yet, let me call them locators for now(suggestions are welcome).

Locators have interface similar to the collection, with a required selector as the first argument, and optional definition. In addition, it should provide some contextual information so during runtime a proper engine is used. This information could be stored behind a Symbol, and should have interface like:

interface QueryMeta<Selector> {
  engine: QueryEngine;
  
  selector: Selector
}

For engines like a11y I can imagine selectors to be objects rather than strings so we probably need a generic Selector type.

In it's turn QueryEngine could have the following interface:

  interface QueryEngine<Selector> {
    // `path` is an array of selectors. It's up to engine to decide whether to concat into a single string and do single request,
    // or do requests one by one
    all(path: Selector[], contextElement: Element): Element[]

    // when error happens, we need a way to convert selectors path 
    // into a string in order to include it to the error message
    serialize(path: Selector[]): string;

    /**
     * @throws in case of selector is invalid
     * e.g. in jquery selectors you are not allowed to use comma to combine multiple selectors
     */ 
    validate(path: Selector[]): void:
  }

Configuring

For now, JQueryQueryEngine is supposed to be a default one. But user should be able to remove it by smth like:

import { setDefaultQueryEngine } from 'ember-cli-page-object/query/engines';
import CSSQueryEngine from 'ember-cli-page-object/query/engines/css';

setDefaultQueryEngine(CSSQueryEngine);

---

Though I talk about xpath, and a11y here, these are out of scope of this issue. Here I'd like to focus on the ability to support different engines, and maybe provide us with the CSSQueryEngine, JQueryQueryEngine.