iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Angular component harnesses let tests operate reusable components through a supported, user-facing API instead of depending on private details such as DOM structure or CSS classes. Angular CDK supplies harness environments for TestBed unit tests and WebDriver end-to-end tests, so a component harness can be shared across both kinds of suites.
What an Angular component harness does
A component harness is a class that gives a test a defined way to find and interact with a component, much as a user would. Rather than asserting against incidental markup or dispatching events directly against particular elements, a test calls methods exposed by the harness to ask about or change component behavior. Angular describes this as a way to reduce coupling to implementation details and make tests easier to maintain; its guidance does not quantify a reliability or maintenance improvement. Angular’s component harness overview
The harness is not a promise that a test will keep passing after the component’s behavior changes. A test should still fail when a meaningful user-visible contract changes. The distinction is that a harness can insulate tests from markup or styling changes that do not alter that contract.
When a harness is worth creating
Harnesses have the most value for reusable, interactive widgets used in many places, especially when multiple teams or suites test the same component. A one-off page has less need for a separate abstraction: if its tests and implementation are updated together, direct implementation-aware tests may be reasonable. Sharing the same harness between unit and end-to-end tests can also justify one even when the component is not widely reused. Angular’s harness authoring guidance
#1 Best Overall
| Situation | Practical choice |
|---|---|
| One-off page, one test environment | Direct tests may be simpler; there is less reuse benefit from a harness. |
| Shared widget used across the application | A component harness can provide a consistent supported surface for tests across consumers. |
| Tests run in both TestBed and WebDriver | Use a shared harness implementation with the corresponding built-in environments. |
| Tests need a new or specialized environment | Plan for custom HarnessEnvironment bindings and environment-specific interaction behavior. |
Choose based on reuse, the environments tests must run in, and whether existing tests are tied to private markup or event details. A harness adds an API to maintain, so it is most useful when that API replaces repeated implementation-specific knowledge.
How to use a CDK harness in a TestBed test
Install Angular CDK in the project if it is not already present; Angular’s guide includes ng add @angular/cdk as an installation route. Check the Angular and CDK versions in the project before applying version-sensitive setup, since the cited guide does not specify release-by-release compatibility. Angular’s harness guide
-
Configure TestBed for the component and create a fixture, as in the project’s ordinary component test.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.Rank #2
-
Create a loader rooted at that fixture with
TestbedHarnessEnvironment.loader(fixture). -
Use asynchronous loader methods such as
getHarness,getAllHarnesses,countHarnesses, orhasHarnessto locate harnesses beneath the loader’s root. -
Call the component-specific asynchronous methods on the harness, then make assertions about the resulting user-relevant state.
Harness operations are asynchronous. In TestBed, harnesses run change detection before reading DOM state and after interacting with the DOM by default. Await harness operations rather than assuming the DOM has already settled. Angular’s harness guide
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteFixture content versus overlays
TestbedHarnessEnvironment.loader(fixture) searches from the fixture root. Components such as menus or dialogs may render an overlay elsewhere in the document, outside that root. For such cases use TestbedHarnessEnvironment.documentRootLoader(fixture), which lets the loader query from the document root. Angular’s harness guide
Using the same harness in WebDriver end-to-end tests
Angular CDK documents built-in harness environments for both TestBed and WebDriver. For a WebDriver test, create a loader with SeleniumWebDriverHarnessEnvironment.loader(webDriverClient); the same concrete component harness can then be used through that loader. Angular’s harness guide
The documentation establishes WebDriver support but does not claim compatibility with every current WebDriver library, runner, or project configuration. Confirm that the relevant Angular/CDK and environment packages match the versions used by your project.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What a component harness author implements
Define a host and behavior-focused methods
A concrete harness extends ComponentHarness and declares a static hostSelector, usually matching the component or directive selector. The base class associates the harness with its host and supplies locator capabilities for the host’s elements and child harnesses. Add methods that describe behavior tests need to exercise—such as reading a selected value or activating a control—rather than exposing incidental class names or markup. Angular’s harness authoring guidance
Free tools Windows power users keep installed
One-click scans. No signup required.
Most harnesses should also expose a static with method that returns a HarnessPredicate. A predicate lets callers filter harnesses by relevant attributes when a test needs a particular instance. Concrete methods are component-specific; for example, a library’s slider harness may offer thumb accessors, so consult that component library’s documentation for its actual API.
Build a custom test environment only when needed
If tests must run in an environment without a built-in CDK implementation, the environment author subclasses HarnessEnvironment<E> for the environment’s raw element type, implements its abstract members, and provides a static loader entry point that returns a HarnessLoader. That implementation must define how DOM interaction works in the environment. Where CDK TestKey values do not match the environment’s key codes, the environment must map them appropriately. Angular’s guide to creating a harness environment
Custom environments that handle manual change detection and parallel APIs also need to integrate the automatic change-detection status handling described in the environment guide; otherwise harness synchronization behavior may not match the built-in environment expectations. Angular’s guide to creating a harness environment
Quick Recap
Common selection and setup mistakes
- Using the fixture loader for an external overlay: switch to
documentRootLoader(fixture)when the target is attached outside the fixture root. - Assuming harness methods are synchronous: await loader and harness operations because they return asynchronous results.
- Putting private markup into the harness API: expose user-relevant operations and state, not incidental CSS classes or DOM layout.
- Assuming every environment is supported: Angular documents TestBed and WebDriver environments; another environment requires its own implementation.
- Expecting a harness to prevent behavior-change failures: a harness reduces implementation coupling, but tests should still detect changed behavior that matters to users.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
