From cbab19b93d1afa55ac926b04c06ca09c9e9e2a30 Mon Sep 17 00:00:00 2001 From: Zac-Smucker-Bryan Date: Thu, 30 Jul 2026 21:12:34 -0500 Subject: [PATCH 1/2] docs: improve standalone testing documentation Add context about using exported `componentOnReady` helper to make tests more accurate for custom-element builds. --- docs/angular/testing.md | 2 ++ docs/react/testing.md | 6 ++++++ docs/vue/testing.md | 6 ++++++ 3 files changed, 14 insertions(+) diff --git a/docs/angular/testing.md b/docs/angular/testing.md index 4e18351378e..15d3994a3ea 100644 --- a/docs/angular/testing.md +++ b/docs/angular/testing.md @@ -86,6 +86,8 @@ Tests for lazy loaded Ionic UI components should only be added under the `/lazy` Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation. +When testing Ionic components, use the exported `componentOnReady` helper from `@ionic/core` instead of calling `el.componentOnReady()` directly. The helper works with both lazy-loaded and custom-element builds, making it more likely the component has finished rendering before making assertions against its rendered DOM or running accessibility tests. + ## Adding New Test Apps As we add support for new versions of Angular, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: diff --git a/docs/react/testing.md b/docs/react/testing.md index 1c9da9c6829..e1e988c0eee 100644 --- a/docs/react/testing.md +++ b/docs/react/testing.md @@ -43,6 +43,12 @@ If you want to add a version-specific change, add the change inside of the appro If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. +### Testing Standalone Ionic Components + +Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation. + +When testing Ionic components, use the exported `componentOnReady` helper from `@ionic/core` instead of calling `el.componentOnReady()` directly. The helper works with both lazy-loaded and custom-element builds, making it more likely the component has finished rendering before making assertions against its rendered DOM or running accessibility tests. + ## Adding New Test Apps As we add support for new versions of React, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: diff --git a/docs/vue/testing.md b/docs/vue/testing.md index 268628f2ea5..43e227b2f94 100644 --- a/docs/vue/testing.md +++ b/docs/vue/testing.md @@ -46,6 +46,12 @@ If you want to add a version-specific change, add the change inside of the appro If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. +### Testing Standalone Ionic Components + +Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation. + +When testing Ionic components, use the exported `componentOnReady` helper from `@ionic/core` instead of calling `el.componentOnReady()` directly. The helper works with both lazy-loaded and custom-element builds, making it more likely the component has finished rendering before making assertions against its rendered DOM or running accessibility tests. + ## Adding New Test Apps As we add support for new versions of Vue, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps: From cf9ad82e17b442309d9488c0ecd3169d9d7cee9c Mon Sep 17 00:00:00 2001 From: Zac Smucker-Bryan <111775722+Zac-Smucker-Bryan@users.noreply.github.com> Date: Tue, 4 Aug 2026 21:04:38 -0500 Subject: [PATCH 2/2] Apply suggestions from code review Accept changes from code review, clarifying for each framework. Co-authored-by: Maria Hutt --- docs/react/testing.md | 6 +++--- docs/vue/testing.md | 6 ++++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/react/testing.md b/docs/react/testing.md index e1e988c0eee..0def2f136d3 100644 --- a/docs/react/testing.md +++ b/docs/react/testing.md @@ -43,11 +43,11 @@ If you want to add a version-specific change, add the change inside of the appro If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. -### Testing Standalone Ionic Components +### Testing Ionic Components -Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation. +`@ionic/react` imports every component through `defineCustomElement` from `@ionic/core/components`, so every test runs against the custom elements build. -When testing Ionic components, use the exported `componentOnReady` helper from `@ionic/core` instead of calling `el.componentOnReady()` directly. The helper works with both lazy-loaded and custom-element builds, making it more likely the component has finished rendering before making assertions against its rendered DOM or running accessibility tests. +These test apps are Cypress only, and Cypress retries assertions until they pass, so there is nothing to wait on manually today. If we add unit tests that assert against rendered DOM, use the `componentOnReady` helper exported from `@ionic/core` rather than calling `el.componentOnReady()` directly. That method does not exist on custom elements, so the direct call throws. The helper waits one animation frame instead, giving the component's inner contents a chance to render. ## Adding New Test Apps diff --git a/docs/vue/testing.md b/docs/vue/testing.md index 43e227b2f94..f65f3459591 100644 --- a/docs/vue/testing.md +++ b/docs/vue/testing.md @@ -46,9 +46,11 @@ If you want to add a version-specific change, add the change inside of the appro If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y. -### Testing Standalone Ionic Components +### Testing Ionic Components -Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation. +`@ionic/vue` imports every component through `defineCustomElement` from `@ionic/core/components`, so every test runs against the custom elements build. + +These test apps are Cypress only, and Cypress retries assertions until they pass, so there is nothing to wait on manually today. If we add unit tests that assert against rendered DOM, use the `componentOnReady` helper exported from `@ionic/core` rather than calling `el.componentOnReady()` directly. That method does not exist on custom elements, so the direct call throws. The helper waits one animation frame instead, giving the component's inner contents a chance to render. When testing Ionic components, use the exported `componentOnReady` helper from `@ionic/core` instead of calling `el.componentOnReady()` directly. The helper works with both lazy-loaded and custom-element builds, making it more likely the component has finished rendering before making assertions against its rendered DOM or running accessibility tests.