Skip to content

docs(cdk/testing): Clean up references to the now deprecated ProtractorHarnessEnvironment #24307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 31, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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