Skip to content

testing.md

Latest commit

 

History

History
151 lines (98 loc) · 9.49 KB

testing.md

File metadata and controls

151 lines (98 loc) · 9.49 KB
Raw

Angular Testing

Ionic Framework supports multiple versions of Angular. As a result, we need to verify that Ionic works correctly with each of these Angular versions.

Syncing Local Changes

The Angular test app supports syncing your locally built changes for validation. This allows you to test local changes like core without having to publish a new version of the package.

Tip

In the root directory, run npm unlink * to remove any previous links you have built.

  1. Build the core directory.
  2. Navigate to packages/angular and run npm run sync.
  3. Build packages/angular using npm run build.
  4. Navigate to packages/angular-server and run npm install && npm run build.
  5. Build the Angular test app.
  6. Navigate to the built test app directory (e.g. packages/angular/test/build/ng14).
  7. Install dependencies using npm install.
  8. Sync your local changes using npm run sync.

From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe or disable the application cache.

Note

Syncing is required to verify that the minimal supported Angular version is still compatible with the latest Ionic Framework changes. For example, Ionic Framework 9 supports Angular 18, but the latest version of Ionic Framework may not be compatible with Angular 18. Syncing allows you to verify that the latest changes are still compatible with the minimal supported version.

Support for the minimal version and maximum version can be found on the Support page of the Ionic Framework documentation.

Application Cache

Angular CLI creates a cache of several files on disk by default in the .angular directory. This decreases the time taken to build the test application. However, the cache makes it difficult to quickly sync and check local changes of Ionic. As a result, the .angular cache is disabled by default in the test app projects.

See https://angular.io/cli/cache for more information.

Disable Cache

ng cache disable

Note

You may need to manually remove the .angular directory once after running this command.

Enable Cache

ng cache enable

Note

You will need to delete the .angular cache and restart the dev server every time you want to sync local changes of Ionic.

Test App Build Structure

Note

Please confirm your current directory as packages/angular/test before proceeding with any of the following commands.

Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.

apps - This directory contains partial applications for each version of Angular we want to test. Typically these directories contain new package.json files, angular.json files, and more. If you have code that is specific to a particular version of Angular, put it in this directory.

base - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.

build - When the apps and base directories are merged, the final result is put in this directory. The build directory should never be committed to git.

build.sh - This is the script that merges the apps and base directories and places the built application in the build directory.

Usage:

# Build a test app using apps/ng14 as a reference
./build.sh ng14

How to modify test apps

To add new tests, components, or pages, modify the base project. This ensures that tests are run for every tested version.

If you want to add a version-specific change, add the change inside of the appropriate projects in apps. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called test.spec.ts in apps/ng14, make sure you place the file in apps/ng14/e2e/src/test.spec.ts.

Version-specific tests

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 Lazy Loaded Ionic Components

Tests for lazy loaded Ionic UI components should only be added under the /lazy route. This ensures the IonicModule is added.

Caution

The lazy loaded build, including IonicModule, is deprecated and will be removed in a future major version. New components should be tested as standalone components (see below). These lazy tests remain to verify that the deprecated build keeps working while it is still supported.

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.

Waiting for Ionic Components

Use the componentOnReady helper exported from @ionic/core rather than calling el.componentOnReady() directly. That method only exists on lazy loaded elements, so a direct call throws under the /standalone route. The helper covers both: under /lazy it awaits the element's own componentOnReady() promise, and under /standalone it waits one animation frame, giving the component's inner contents a chance to render.

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:

  1. Navigate to the built app for the most recent version of Angular that Ionic tests.
  2. Update the application by following the steps on https://update.angular.io/.
  3. Make note of any files that changed during the upgrade (package.json, package-lock.json, angular.json, etc).
  4. Copy the changed files to a new directory in apps.
  • Do NOT copy the entire directory. The test/base directory contains shared files between all major versions. Only files that are different than previous major versions should be copied to the new directory in apps.
  1. Add the new app to the apps matrix of the test-angular-e2e job in both ./github/workflows/build.yml and ./github/workflows/stencil-nightly.yml. This will allow the new test app to run against all PRs.
  2. Commit these changes and push.

Example:

In this example, we are going to add the Angular 14 test app.

  1. Build the Angular 13 test app using ./build.sh ng13.
  2. Navigate to build/ng13.
  3. Perform the upgrade steps on https://update.angular.io/. The "From" field should say "13.0" and the "To" field should say "14.0".

Note: You may encounter some other peer dependency issues not covered by the Angular Upgrade Guide. These peer dependency issues can be resolved manually by updating the installed version of each dependency.

  1. Observe that the output of the Angular upgrade indicates that the following files were modified:

angular.json package-lock.json package.json tsconfig.json src/app/form/form.component.ts src/app/modal-example/modal-example.component.ts

  1. Create a directory in apps named ng14.
  2. Copy the modified files to the apps/ng14 directory.
  3. Open ./github/workflows/build.yml and find the test-angular-e2e job.
  4. Find the apps field under matrix.
  5. Add "ng14" to the apps field.
  6. Open ./github/workflows/stencil-nightly.yml and find the test-angular-e2e job.
  7. Repeat steps 8 and 9.
  8. Commit these changes and push.

Variant Test Apps

Most apps in apps/ pin a different Angular version. A variant app pins the same version as an existing app and changes how it's configured, covering a combination that would otherwise go untested. The current example is ng22-zone: Angular 22 with Zone.js, the combination whose absence let #31406 ship.

Follow the steps above for adding a version app, with two differences:

  1. Name it ng<NN>-<variant>. The Vercel preview app is picked in core/scripts/vercel-build.sh with the filter '^ng[0-9]+$', so any suffixed name is excluded. A bare ng<NN> name is the trap: calling an Angular 22 variant ng23 would match the filter and silently become the deployed preview.
  2. Select change detection through providers, not polyfills. Angular 22 bootstraps zoneless even when Zone.js is loaded, so the mode is chosen by base/src/app/change-detection.providers.ts, which both app.module.ts and main-standalone.ts spread. Override that file in the variant app. It's empty in base/, which leaves Angular's own default. Omit src/polyfills.ts if the variant needs base's import 'zone.js'.

Shared pages under base/ must keep passing in every mode, so use the assertZoneContext() helper from base/src/app/zone-assert.util.ts rather than asserting an Angular zone unconditionally.

For the change detection rules that apply to the library itself, see Change Detection.