refactor(cdk-experimental/testing): Refactor the ComponentHarness API

[mmalerba]

Drawbacks to current API

• QueryOptions is confusing, undefined, true, and false mean different things for allowNull. The concept of allowNull also doesn't really apply when getting a list of elements
• The find method is confusing as it doesn't actually find anything, it returns a function to find things
• The user is required to specify the host selector for the harness they want to load, even though the harness should always know what selector its looking for

New API

The new API combines the variaous load methods as well as the Locator class from the old API into a single class called HarnessEnvironment. The HarnessEnvironment implements two separate interfaces, one for test authors: HarnessLoader, and one for component harness authors: LocatorFactory. Both protractor and testbed have their own concrete implementations of HarnessEnvironment, but they cannot be constructed directly. Users are required to construct them via a create method which returns a HarnessLoader interface. This way only the methods that make sense for the test author are exposed to the test author.

The HarnessLoader provides methods to find new HarnessLoaders for sub-portions of the DOM and methods to create ComponentHarnesses by searching for the corresponding host selector under its root element. Each ComponentHarness class is required to specify its host selector, so the user doesn't have to.

The LocatorFactory is the interface to the HarnessEnvironent available when extending ComponentHarness. It gives harness authors methods to create locator functions for finding TestElements and ComponentHarnesses under its root element. It also provides a method to get a LocatorFactory rooted at the document root, this can be used instead of the global option from the old API.

The methods described above for finding HarnessLoaders ComponentHarnesses and locator functions come in 3 different flavors (required, optional, and all). These different variants should be used instead of the old allowNull syntax. There is currently no replacement for {allowNull: undefined} but if we feel its important we can add a default variant of the method as well.

Examples

Component harness author code

// Old
class MyHarness extends ComponentHarness {
  readonly header = this.find(MyHeaderHarness, 'my-header', {allowNull: false});
  readonly overlay = this.find('.my-overlay', {allowNull: false, global: true});
}

// New
class MyHarness extends ComponentHarness {
  readonly header = this.requiredLocator(MyHeaderHarness);
  readonly overlay = this.documentRootLocatorFactory().optionalLocator('.my-overlay');
}

Test author code

// Old
it('does stuff', async () => {
  const harness = load(MyHarness, fixture);
  // Not possible to load harness for specific subsection
});

// New
it('does stuff', async () => {
  const harness = await TestbedHarnessEnvironment.harnessForFixtureRoot(MyHarness, fixture);
  const subsectionLoader = await TestbedHarnessEnvironment.create(fixture).findRequired('.sub-section');
  const subsectionHarness = await subsectionLoader.requiredHarness(MyHarness);
});

Questions

• Should we add a plain locator method that behaves the same as requiredLocator for unit tests but doesn't check element.isPresent in e2e tests?
• Its slightly more verbose, but should we call the methods locatorForRequired? It reads a little nicer: this.locatorForRequired(MyCompHarness)

[crisbeto]

LGTM

[jelbourn]

LGTM

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}