Skip to content

Commit

Permalink
docs(cdk/testing): Clean up references to the now deprecated Protract…
Browse files Browse the repository at this point in the history
…orHarnessEnvironment (#24307)

* docs(cdk/testing): Clean up references to the now deprecated ProtractorHarnessEnvironemnt

* fix(cdk/testing): fix spelling
  • Loading branch information
mmalerba committed Jan 31, 2022
1 parent ebc3e10 commit 1f40b7d
Show file tree
Hide file tree
Showing 4 changed files with 17 additions and 16 deletions.
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5535,4 +5535,4 @@ You can view a beta version of the docs at https://beta-angular-material-io.fire

# Changes Prior to 7.0.0

To view changes that occurred prior to 7.0.0, see [CHANGELOG_ARCHIVE.md](https://github.com/angular/components/blob/master/CHANGELOG_ARCHIVE.md).
To view changes that occurred prior to 7.0.0, see [CHANGELOG_ARCHIVE.md](https://github.com/angular/components/blob/master/CHANGELOG_ARCHIVE.md).
8 changes: 4 additions & 4 deletions guides/using-component-harnesses.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,14 @@ The following sections will illustrate these benefits in more detail.
## Which kinds of tests can use harnesses?

The Angular CDK's component harnesses are designed to work in multiple different test environments.
Support currently includes Angular's Testbed environment in Karma unit tests and Protractor
Support currently includes Angular's Testbed environment in Karma unit tests and Selenium WebDriver
end-to-end (e2e) tests. You can also support additional environments by creating custom extensions
of the CDK's `HarnessEnvironment` and `TestElement` classes.

## Getting started

The foundation for all test harnesses lives in `@angular/cdk/testing`. Start by importing either
`TestbedHarnessEnvironment` or `ProtractorHarnessEnvironment` based on whether you're writing a
`TestbedHarnessEnvironment` or `SeleniumWebDriverHarnessEnvironment` based on whether you're writing a
unit test or an e2e test. From the `HarnessEnvironment`, you can get a `HarnessLoader` instance,
which you will use to load Angular Material component harnesses. For example, if we're writing unit
tests for a `UserProfile` component, the code might look like this:
Expand Down Expand Up @@ -64,8 +64,8 @@ different paths.
- `@angular/cdk/testing` contains symbols that are shared regardless of the environment your tests
are in.
- `@angular/cdk/testing/testbed` contains symbols that are used only in Karma tests.
- `@angular/cdk/testing/protractor` (not shown above) contains symbols that are used only in
Protractor tests.
- `@angular/cdk/testing/selenium-webdriver` (not shown above) contains symbols that are used only in
Selenium WebDriver tests.
## Loading an Angular Material harness
Expand Down
3 changes: 2 additions & 1 deletion src/cdk/testing/protractor/protractor-harness-environment.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ const defaultEnvironmentOptions: ProtractorHarnessEnvironmentOptions = {

/**
* A `HarnessEnvironment` implementation for Protractor.
* @deprecated
* @deprecated As of v13.0.0, this environment no longer works, as it is not
* compatible with the new [Angular Package Format](https://angular.io/guide/angular-package-format).
* @breaking-change 13.0.0
*/
export class ProtractorHarnessEnvironment extends HarnessEnvironment<ElementFinder> {
Expand Down
20 changes: 10 additions & 10 deletions src/cdk/testing/test-harnesses.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,12 @@ matches the harness class to instances of the component in the DOM. Beyond that,
given harness is specific to its corresponding component; refer to the component's documentation to
learn how to use a specific harness.

#### Using `TestbedHarnessEnvironment` and `ProtractorHarnessEnvironment`
#### Using `TestbedHarnessEnvironment` and `SeleniumWebDriverHarnessEnvironment`

These classes correspond to different implementations of the component harness system with bindings
for specific test environments. Any given test must only import _one_ of these classes. Karma-based
unit tests should use the `TestbedHarnessEnvironment`, while Protractor-based end-to-end tests
should use the `ProtractorHarnessEnvironment`. Additional environments require custom bindings; see
unit tests should use the `TestbedHarnessEnvironment`, while Selenium WebDriver-based end-to-end tests
should use the `SeleniumWebDriverHarnessEnvironment`. Additional environments require custom bindings; see
[API for harness environment authors](#api-for-harness-environment-authors) for more information on
alternate test environments.

Expand Down Expand Up @@ -107,13 +107,13 @@ it('loads harnesses', async () => {
});
```

`ProtractorHarnessEnvironment` has an API that offers a single static method:
`SeleniumWebDriverHarnessEnvironment` has an API that offers a single static method:

| Method | Description |
| ------ | ----------- |
| `loader(): HarnessLoader` | Gets a `HarnessLoader` instance for the current HTML document, rooted at the document's root element. |

Since Protractor does not deal with fixtures, the API in this environment is simpler. The
Since Selenium WebDriver does not deal with fixtures, the API in this environment is simpler. The
`HarnessLoader` returned by the `loader()` method should be sufficient for loading all necessary
`ComponentHarness` instances.

Expand Down Expand Up @@ -304,7 +304,7 @@ The functions created with the locator methods described above all return `TestE
| `dispatchEvent(name: string, data?: Record<string, EventData>): Promise<void>;` | Dispatches an event with a particular name. |

`TestElement` is an abstraction designed to work across different test environments (Karma,
Protractor, etc). When using harnesses, you should perform all DOM interaction via this interface.
Selenium WebDriver, etc). When using harnesses, you should perform all DOM interaction via this interface.
Other means of accessing DOM elements (e.g. `document.querySelector`) will not work in all test
environments.

Expand Down Expand Up @@ -574,7 +574,7 @@ may need to explicitly wait for tasks outside `NgZone`, as this does not happen

Harness environment authors are developers who want to add support for using component harnesses in
additional testing environments. Out-of-the-box, Angular CDK's component harnesses can be used in
Protractor E2E tests and Karma unit tests. Developers can support additional environments by
Selenium WebDriver E2E tests and Karma unit tests. Developers can support additional environments by
creating custom implementations of `TestElement` and `HarnessEnvironment`.

#### Creating a `TestElement` implementation for the environment
Expand All @@ -583,7 +583,7 @@ The first step in adding support for a new testing environment is to create a `T
implementation. The `TestElement` interface serves as an environment-agnostic representation of a
DOM element; it lets harnesses interact with DOM elements regardless of the underlying environment.
Because some environments don't support interacting with DOM elements synchronously
(e.g. webdriver), all of the `TestElement` methods are asynchronous, returning a `Promise` with the
(e.g. WebDriver), all of the `TestElement` methods are asynchronous, returning a `Promise` with the
result of the operation.

| Method | Description |
Expand Down Expand Up @@ -616,7 +616,7 @@ maintain a mapping from `TestKey` codes to the codes used in the particular test
The
[`UnitTestElement`](https://github.com/angular/components/blob/master/src/cdk/testing/testbed/unit-test-element.ts#L57)
and
[`ProtractorElement`](https://github.com/angular/components/blob/master/src/cdk/testing/protractor/protractor-element.ts#L67)
[`SeleniumWebDriverElement`](https://github.com/angular/components/blob/master/src/cdk/testing/selenium-webdriver/selenium-web-driver-element.ts#L22)
implementations in Angular CDK serve as good examples of implementations of this interface.

#### Creating a `HarnessEnvironemnt` implementation for the environment
Expand Down Expand Up @@ -654,7 +654,7 @@ require arguments to be passed. (e.g. the `loader` method on `TestbedHarnessEnvi
The
[`TestbedHarnessEnvironment`](https://github.com/angular/components/blob/master/src/cdk/testing/testbed/testbed-harness-environment.ts#L20)
and
[`ProtractorHarnessEnvironment`](https://github.com/angular/components/blob/master/src/cdk/testing/protractor/protractor-harness-environment.ts#L16)
[`SeleniumWebDriverHarnessEnvironment`](https://github.com/angular/components/blob/master/src/cdk/testing/selenium-webdriver/selenium-web-driver-harness-environment.ts#L71)
implementations in Angular CDK serve as good examples of implementations of this interface.

#### Handling auto change detection status
Expand Down

0 comments on commit 1f40b7d

Please sign in to comment.