Testing Angular Components by Properties with Playwright

yazar

Most Angular E2E tests look like this: 

await page.locator('[data-testid="submit-btn"]').click();
await page.locator('.user-card:nth-child(2) h2').textContent();

You end up fighting CSS specificity and fragile DOM structure instead of testing Angular behavior. What if you could do this instead? 

await page.locator('angular=app-button[label="Submit"]').click();
await page.locator('angular=app-user-card[user.role="admin"]').textContent();

That’s exactly what @playwright-labs/selectors-angular provides.

What Is It?

A custom Playwright selector engine that queries Angular components by their actual component properties — @Input() values, signals, and nested objects — rather than DOM attributes or CSS classes.

It hooks into Angular’s DevTools API (window.ng) which is available in development builds.

Installation

npm install -D @playwright-labs/selectors-angular

Setup

Register the engine in your playwright.config.ts: 

import { defineConfig } from "@playwright/test";
import { AngularEngine } from "@playwright-labs/selectors-angular";

export default defineConfig({
  use: {
    /* ... */
  },
});

// Register once at module level
import { selectors } from "@playwright/test";
selectors.register("angular", AngularEngine);

Or use the bundled test fixture which handles registration automatically: 

import { test, expect } from "@playwright-labs/selectors-angular";

test("my angular test", async ({ page, $ng }) => {
  // $ng and engine are auto-registered
});

The angular= Selector Syntax

The syntax mirrors CSS attribute selectors: 

angular=<component-tag>[property="value"][another="value"]

Operators

Operator Meaning Example
[prop] truthy check [disabled]
[prop="val"] exact match [label="Submit"]
[prop*="val"] contains [type*="ary"]
[prop^="val"] starts with [type^="prim"]
[prop$="val"] ends with [type$="ger"]
[prop~="val"] word in list [classes~="active"]
`[prop =”val”]` exact or hyphen-prefix

You can also use regex: 

page.locator('angular=app-button[label=/^Sub/i]')

And case-insensitive with i flag: 

page.locator('angular=app-button[label="submit" i]')

Nested Properties

Dot notation works for nested objects: 

page.locator('angular=app-user-card[user.role="admin"]')
page.locator('angular=app-card[config.theme.color="dark"]')

Multiple Conditions (AND)

Chain multiple attribute blocks — all must match: 

page.locator('angular=app-button[type="danger"][disabled]')

The $ng Fixture

The $ng fixture wraps standard Playwright locators with Angular-aware introspection methods: 

test("inspects component state", async ({ $ng }) => {
  // Read @Input value
  const label = await $ng("app-button").first().input<string>("label");
  expect(label).toBe("Submit");

  // Read WritableSignal value
  const count = await $ng("app-counter").first().signal<number>("count");
  expect(count).toBe(0);

  // List all @Input names
  const inputs = await $ng("app-button").first().inputs();
  expect(inputs).toContain("label");
  expect(inputs).toContain("disabled");

  // Check directives
  const directives = await $ng("router-outlet").directives();
  expect(directives.some((d) => d.includes("RouterOutlet"))).toBe(true);
});

Narrowing

const buttons = $ng("app-button");
const first = buttons.first();
const second = buttons.nth(1);
const last = buttons.last();

Custom Matchers

Import the extended expect from the package: 

import { expect } from "@playwright-labs/selectors-angular";

test("matchers", async ({ page }) => {
  const button = page.locator("app-button").first();

  // Is it an Angular component?
  await expect(button).toBeNgComponent();

  // Does it declare this @Input?
  await expect(button).toHaveNgInput("label");

  // Does the @Input hold this value?
  await expect(button).toBeNgInput("label", "Submit");

  // Does it declare this @Output?
  await expect(button).toHaveNgOutput("clicked");

  // Signal assertions
  const counter = page.locator("app-counter").first();
  await expect(counter).toHaveNgSignal("count");
  await expect(counter).toBeNgSignal("count", 0);
});

Real-World Example

Here’s a test that checks a disabled danger button exists and has the right label: 

test("danger button is disabled and labeled Delete", async ({ page, $ng }) => {
  await page.goto("/");

  // Use the selector engine to find it
  const btn = page.locator('angular=app-button[type="danger"][disabled]');
  await expect(btn).toHaveCount(1);

  // Use the fixture to read its label
  const label = await $ng('angular=app-button[type="danger"][disabled]').input<string>("label");
  expect(label).toBe("Delete");
});

Compare that to the equivalent DOM-based test: 

// Before: fragile, depends on implementation details
const btn = page.locator('[data-testid="delete-btn"]');
await expect(btn).toBeDisabled();

The Angular-aware test is self-documenting — it describes the component contract, not the DOM structure.

Requirements

  • Angular app running in development mode (ng serve or ng build --configuration=development)
  • Playwright 1.40+
  • Angular 14+ (DevTools API required)

Wrapping Up

@playwright-labs/selectors-angular closes the gap between how Angular apps are built (component trees with typed inputs) and how they’re tested (brittle CSS selectors). By querying components by their properties, your tests:

  • Break less when the DOM changes
  • Read like documentation
  • Test the Angular contract, not the DOM implementation

Check out the playwright-labs repository for more packages in the ecosystem.