Skip to contentPorsche Design System
You are currently viewing an earlier release of the Porsche Design System.Switch to the latest Porsche Design System documentation.
SearchGitHub repository of Porsche Design SystemOpen settings sidebar
Angular Table of Contents Testing with Jest Jest uses jsdom and supports ShadowDOM since Version 12.2.0. However, it doesn't support JavaScript modules as described in this issue. Also, it doesn't support CSSStyleSheet.replace(), Intersection Observer, Element.prototype.scrollTo and others. As a workaround we provide a polyfill as part of the @porsche-design-system/components-angular package. The polyfill requires jsdom v30 or higher. On older versions it throws an explicit error on import. To apply the polyfill, simply import it in your setupTest.{js|ts} file. Certain modern browser APIs are not supported in the jsdom environment. See Unsupported APIs for more information. Setup file
// setupTest.{js|ts}

import '@porsche-design-system/components-angular/jsdom-polyfill';
Example component
// single-component.ts

import { ChangeDetectionStrategy, Component } from '@angular/core';
import type { TabsBarUpdateEventDetail } from '@porsche-design-system/components-angular';

@Component({
  selector: 'single-component',
  template: `
    <p-tabs-bar [activeTabIndex]="tabIndex" (update)="onUpdate($event)">
      <button data-testid="button1" type="button">Tab One</button>
      <button data-testid="button2" type="button">Tab Two</button>
      <button data-testid="button3" type="button">Tab Three</button>
    </p-tabs-bar>
    <div data-testid="debug">Active Tab: { tabIndex + 1 }</div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class SingleComponent {
  tabIndex: number = 0;

  onUpdate(e: CustomEvent<TabsBarUpdateEventDetail>) {
    this.tabIndex = e.detail.activeTabIndex;
  }
}
Test example component
// single-component.test.ts

import { componentsReady } from '@porsche-design-system/components-angular';
import { render } from '@testing-library/angular';
import userEvent from '@testing-library/user-event';
import '@porsche-design-system/components-angular/jsdom-polyfill';

it('should render Tabs Bar from Porsche Design System and use its events', async () => {
  const { getByTestId } = await render(SingleComponent);
  await componentsReady();

  const debug = getByTestId('debug');
  const button1 = getByTestId('button1');
  const button2 = getByTestId('button2');
  const button3 = getByTestId('button3');

  expect(debug.innerHTML).toBe('Active Tab: 1');

  await userEvent.click(button2);
  expect(debug.innerHTML).toBe('Active Tab: 2');

  await userEvent.click(button3);
  expect(debug.innerHTML).toBe('Active Tab: 3');

  await userEvent.click(button1);
  expect(debug.innerHTML).toBe('Active Tab: 1');
});
More test examples can be found at the componentsReady() documentation. Queries Porsche Design System components render their markup inside Shadow DOM. Standard Testing Library queries such as getByRole only search light DOM, so they never reach those elements and find nothing. Therefore the testing sub-package provides a Shadow counterpart for every Testing Library query. These search light DOM and Shadow DOM, including nested Shadow DOM. All 48 available queries: AltText: getByShadowAltText, getAllByShadowAltText, queryByShadowAltText, queryAllByShadowAltText, findByShadowAltText, findAllByShadowAltText DisplayValue: getByShadowDisplayValue, getAllByShadowDisplayValue, queryByShadowDisplayValue, queryAllByShadowDisplayValue, findByShadowDisplayValue, findAllByShadowDisplayValue LabelText: getByShadowLabelText, getAllByShadowLabelText, queryByShadowLabelText, queryAllByShadowLabelText, findByShadowLabelText, findAllByShadowLabelText PlaceholderText: getByShadowPlaceholderText, getAllByShadowPlaceholderText, queryByShadowPlaceholderText, queryAllByShadowPlaceholderText, findByShadowPlaceholderText, findAllByShadowPlaceholderText Role: getByShadowRole, getAllByShadowRole, queryByShadowRole, queryAllByShadowRole, findByShadowRole, findAllByShadowRole TestId: getByShadowTestId, getAllByShadowTestId, queryByShadowTestId, queryAllByShadowTestId, findByShadowTestId, findAllByShadowTestId Text: getByShadowText, getAllByShadowText, queryByShadowText, queryAllByShadowText, findByShadowText, findAllByShadowText Title: getByShadowTitle, getAllByShadowTitle, queryByShadowTitle, queryAllByShadowTitle, findByShadowTitle, findAllByShadowTitle
import { screen } from '@porsche-design-system/components-angular/testing';

it('should work for p-button', async () => {
  const fixture = TestBed.createComponent(SomeComponent);
  fixture.detectChanges();
  await componentsReady();

  expect(screen.getByShadowRole('button')).toBe(document.querySelector('p-button').shadowRoot.querySelector('button'));
});
Also exported: screen (every query above, bound to document), within, deepQuerySelector, deepQuerySelectorAll, getAllElementsAndShadowRoots, debug, logShadowDOM, prettyShadowDOM, logRoles, configure and getConfig. These queries need a DOM to search. Importing the testing sub-package where no DOM is available throws an error. Porsche Design System queries Before the queries above were available we shipped three helpers of our own. They are still exported and still supported, so existing tests keep working. For new tests prefer the shadow queries above, which cover every query family rather than three. OursEquivalent abovegetByRoleShadowedgetByShadowRolegetByLabelTextShadowedgetByShadowLabelTextgetByTextShadowedgetByShadowText Unlike the shadow queries, these three take an optional container as their first argument and fall back to the whole document when it is omitted. Unsupported APIs Certain modern browser APIs are not supported in the jsdom environment. Dialog API Affected Components: p-modal, p-flyout, p-sheet, p-drilldown Due to the lack of native support in jsdom, the Dialog API needs to be either manually polyfilled or mocked. You can use the available dialog-polyfill package or create a custom mock implementation. Example mock:
HTMLDialogElement.prototype.show = jest.fn();
HTMLDialogElement.prototype.showModal = jest.fn(function (this: HTMLDialogElement) {
  this.setAttribute('open', '');
});
HTMLDialogElement.prototype.close = jest.fn(function (this: HTMLDialogElement) {
  this.removeAttribute('open');
});
Element Internals API Affected Components: p-button, p-button-pure, p-checkbox, p-input-date, p-input-email, p-input-month, p-input-number, p-input-password, p-input-search, p-input-tel, p-input-text, p-input-time, p-input-url, p-input-week, p-multi-select, p-pin-code, p-radio-group, p-segmented-control, p-select, p-textarea Current polyfills for the Element Internals API are incompatible with Stencil. Therefore, the API must be mocked within the test setup. Example mock:
HTMLElement.prototype.attachInternals = jest.fn(
  () =>
    ({
      setFormValue: jest.fn(),
      setValidity: jest.fn(),
    }) as ElementInternals
);
animate API Affected Components: p-tabs-bar, p-tabs, p-drilldown The API must be mocked within the test setup. Example mock:
Element.prototype.animate = vi.fn(
  () =>
    ({
      onfinish: null,
      cancel: vi.fn(),
      finish: vi.fn(),
    }) as unknown as Animation
);
Global settingsColor SchemeAll color tokens use the light-dark() CSS function. Set the theme via the CSS color-scheme property: light for light mode, dark for dark mode, or light dark to follow the user's system preference.LightDarkLight DarkDirectionThe dir global attribute in HTML changes the direction of text and other content within an element. It's most often used on the <html> tag to set the entire page's direction, which is crucial for supporting languages that are written from right to left (RTL), such as Arabic and Hebrew. For example, using <html dir="rtl"> makes the entire page display from right to left, adjusting the layout and text flow accordingly.LTR (left-to-right)RTL (right-to-left)Text ZoomTo ensure accessibility and comply with WCAG 2.2 AA standards, it is mandatory for web content to support text resizing up to at least 200% without loss of content or functionality. Using relative units like rem is a best practice for achieving this, as they allow the text to scale uniformly based on the user's browser settings.100%130%150%200%