Skip to content

Commit dedac8d

Browse files
atscottthePunderWoman
atscott
authored and
thePunderWoman
committed
feat(router): Add test helper for trigger navigations in tests (#48552)
In order to test components and services which depend on router navigations, such as `ActivatedRoute` instances, tests currently need to provide a fair bit of boilerplate _or_ they can set up a stub for `ActivatedRoute` and list it in the `providers` to override it in `TestBed`. This approach of stubbing the `ActivatedRoute` creates a situation that can easily cause the test to break. The stub often only mocks out the dependencies that the component/service _currently_ needs. This dependencies might change over time and break the test in an unexpected way. In addition, it is difficult to get the structure of `ActivatedRoute` exactly correct. This change will allow unit tests to quickly set up routes, trigger real navigations in the Router, and get instances of component's to test along with real instances of `ActivatedRoute`. This all comes without needing to know that the component depends on `ActivatedRoute` at all. This becomes more important when considering that a component may be refactored in the future to use `@Input` rather than access data on the `ActivatedRoute` instance (see #18967). Tests which mock out `ActivatedRoute` would all break, but those which use `navigateForTest` would continue to work without needing any updates. resolves #15779 resolves #48608 PR Close #48552
1 parent 930020c commit dedac8d

File tree

10 files changed

+463
-0
lines changed

10 files changed

+463
-0
lines changed

‎goldens/public-api/router/testing/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
import { ChildrenOutletContexts } from '@angular/router';
88
import { Compiler } from '@angular/core';
9+
import { DebugElement } from '@angular/core';
910
import { ExtraOptions } from '@angular/router';
1011
import * as i0 from '@angular/core';
1112
import * as i1 from '@angular/router';
@@ -17,9 +18,20 @@ import { Router } from '@angular/router';
1718
import { RouteReuseStrategy } from '@angular/router';
1819
import { Routes } from '@angular/router';
1920
import { TitleStrategy } from '@angular/router';
21+
import { Type } from '@angular/core';
2022
import { UrlHandlingStrategy } from '@angular/router';
2123
import { UrlSerializer } from '@angular/router';
2224

25+
// @public
26+
export class RouterTestingHarness {
27+
static create(initialUrl?: string): Promise<RouterTestingHarness>;
28+
detectChanges(): void;
29+
navigateByUrl(url: string): Promise<null | {}>;
30+
navigateByUrl<T>(url: string, requiredRoutedComponentType: Type<T>): Promise<T>;
31+
get routeDebugElement(): DebugElement | null;
32+
get routeNativeElement(): HTMLElement | null;
33+
}
34+
2335
// @public
2436
export class RouterTestingModule {
2537
// (undocumented)

‎packages.bzl‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ DOCS_ENTRYPOINTS = [
7373
"examples/forms",
7474
"examples/platform-browser",
7575
"examples/router/activated-route",
76+
"examples/router/testing",
7677
"examples/service-worker/push",
7778
"examples/service-worker/registration-options",
7879
"examples/test-utils",

‎packages/examples/router/testing/BUILD.bazel‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
load("//tools:defaults.bzl", "jasmine_node_test", "karma_web_test_suite", "ts_library")
2+
3+
package(default_visibility = ["//visibility:public"])
4+
5+
ts_library(
6+
name = "test_lib",
7+
testonly = True,
8+
srcs = glob(["**/*.spec.ts"]),
9+
deps = [
10+
"//packages/common",
11+
"//packages/core",
12+
"//packages/core/testing",
13+
"//packages/router",
14+
"//packages/router/testing",
15+
],
16+
)
17+
18+
jasmine_node_test(
19+
name = "test",
20+
bootstrap = ["//tools/testing:node"],
21+
deps = [
22+
":test_lib",
23+
],
24+
)
25+
26+
karma_web_test_suite(
27+
name = "test_web",
28+
deps = [
29+
":test_lib",
30+
],
31+
)
32+
33+
filegroup(
34+
name = "files_for_docgen",
35+
srcs = glob([
36+
"**/*.ts",
37+
]),
38+
)

‎packages/examples/router/testing/test/router_testing_harness_examples.spec.ts‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
/**
2+
* @license
3+
* Copyright Google LLC All Rights Reserved.
4+
*
5+
* Use of this source code is governed by an MIT-style license that can be
6+
* found in the LICENSE file at https://angular.io/license
7+
*/
8+
9+
import {AsyncPipe} from '@angular/common';
10+
import {Component, inject} from '@angular/core';
11+
import {TestBed} from '@angular/core/testing';
12+
import {ActivatedRoute, CanActivateFn, provideRouter, Router} from '@angular/router';
13+
import {RouterTestingHarness} from '@angular/router/testing';
14+
15+
describe('navigate for test examples', () => {
16+
// #docregion RoutedComponent
17+
it('navigates to routed component', async () => {
18+
@Component({standalone: true, template: 'hello {{name}}'})
19+
class TestCmp {
20+
name = 'world';
21+
}
22+
23+
TestBed.configureTestingModule({
24+
providers: [provideRouter([{path: '', component: TestCmp}])],
25+
});
26+
27+
const harness = await RouterTestingHarness.create();
28+
const activatedComponent = await harness.navigateByUrl('/', TestCmp);
29+
expect(activatedComponent).toBeInstanceOf(TestCmp);
30+
expect(harness.routeNativeElement?.innerHTML).toContain('hello world');
31+
});
32+
// #enddocregion
33+
34+
it('testing a guard', async () => {
35+
@Component({standalone: true, template: ''})
36+
class AdminComponent {
37+
}
38+
@Component({standalone: true, template: ''})
39+
class LoginComponent {
40+
}
41+
42+
// #docregion Guard
43+
let isLoggedIn = false;
44+
const isLoggedInGuard: CanActivateFn = () => {
45+
return isLoggedIn ? true : inject(Router).parseUrl('/login');
46+
};
47+
48+
TestBed.configureTestingModule({
49+
providers: [
50+
provideRouter([
51+
{path: 'admin', canActivate: [isLoggedInGuard], component: AdminComponent},
52+
{path: 'login', component: LoginComponent},
53+
]),
54+
],
55+
});
56+
57+
const harness = await RouterTestingHarness.create('/admin');
58+
expect(TestBed.inject(Router).url).toEqual('/login');
59+
isLoggedIn = true;
60+
await harness.navigateByUrl('/admin');
61+
expect(TestBed.inject(Router).url).toEqual('/admin');
62+
// #enddocregion
63+
});
64+
65+
it('test a ActivatedRoute', async () => {
66+
// #docregion ActivatedRoute
67+
@Component({
68+
standalone: true,
69+
imports: [AsyncPipe],
70+
template: `search: {{(route.queryParams | async)?.query}}`
71+
})
72+
class SearchCmp {
73+
constructor(readonly route: ActivatedRoute, readonly router: Router) {}
74+
75+
async searchFor(thing: string) {
76+
await this.router.navigate([], {queryParams: {query: thing}});
77+
}
78+
}
79+
80+
TestBed.configureTestingModule({
81+
providers: [provideRouter([{path: 'search', component: SearchCmp}])],
82+
});
83+
84+
const harness = await RouterTestingHarness.create();
85+
const activatedComponent = await harness.navigateByUrl('/search', SearchCmp);
86+
await activatedComponent.searchFor('books');
87+
harness.detectChanges();
88+
expect(TestBed.inject(Router).url).toEqual('/search?query=books');
89+
expect(harness.routeNativeElement?.innerHTML).toContain('books');
90+
// #enddocregion
91+
});
92+
});

‎packages/router/src/private_export.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,4 @@ export {RestoredState as ɵRestoredState} from './navigation_transition';
1212
export {withPreloading as ɵwithPreloading} from './provide_router';
1313
export {ROUTER_PROVIDERS as ɵROUTER_PROVIDERS} from './router_module';
1414
export {flatten as ɵflatten} from './utils/collection';
15+
export {afterNextNavigation as ɵafterNextNavigation} from './utils/navigations';

‎packages/router/testing/BUILD.bazel‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ ng_module(
1111
"//packages/common",
1212
"//packages/common/testing",
1313
"//packages/core",
14+
"//packages/core/testing",
1415
"//packages/router",
1516
"@npm//rxjs",
1617
],

‎packages/router/testing/src/router_testing_harness.ts‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
/**
2+
* @license
3+
* Copyright Google LLC All Rights Reserved.
4+
*
5+
* Use of this source code is governed by an MIT-style license that can be
6+
* found in the LICENSE file at https://angular.io/license
7+
*/
8+
9+
import {Component, DebugElement, Injectable, Type, ViewChild} from '@angular/core';
10+
import {ComponentFixture, TestBed} from '@angular/core/testing';
11+
import {Router, RouterOutlet, ɵafterNextNavigation as afterNextNavigation} from '@angular/router';
12+
13+
@Injectable({providedIn: 'root'})
14+
export class RootFixtureService {
15+
private fixture?: ComponentFixture<RootCmp>;
16+
private harness?: RouterTestingHarness;
17+
18+
createHarness(): RouterTestingHarness {
19+
if (this.harness) {
20+
throw new Error('Only one harness should be created per test.');
21+
}
22+
this.harness = new RouterTestingHarness(this.getRootFixture());
23+
return this.harness;
24+
}
25+
26+
private getRootFixture(): ComponentFixture<RootCmp> {
27+
if (this.fixture !== undefined) {
28+
return this.fixture;
29+
}
30+
this.fixture = TestBed.createComponent(RootCmp);
31+
this.fixture.detectChanges();
32+
return this.fixture;
33+
}
34+
}
35+
36+
@Component({
37+
standalone: true,
38+
template: '<router-outlet></router-outlet>',
39+
imports: [RouterOutlet],
40+
})
41+
export class RootCmp {
42+
@ViewChild(RouterOutlet) outlet?: RouterOutlet;
43+
}
44+
45+
/**
46+
* A testing harness for the `Router` to reduce the boilerplate needed to test routes and routed
47+
* components.
48+
*
49+
* @publicApi
50+
*/
51+
export class RouterTestingHarness {
52+
/**
53+
* Creates a `RouterTestingHarness` instance.
54+
*
55+
* The `RouterTestingHarness` also creates its own root component with a `RouterOutlet` for the
56+
* purposes of rendering route components.
57+
*
58+
* Throws an error if an instance has already been created.
59+
* Use of this harness also requires `destroyAfterEach: true` in the `ModuleTeardownOptions`
60+
*
61+
* @param initialUrl The target of navigation to trigger before returning the harness.
62+
*/
63+
static async create(initialUrl?: string): Promise<RouterTestingHarness> {
64+
const harness = TestBed.inject(RootFixtureService).createHarness();
65+
if (initialUrl !== undefined) {
66+
await harness.navigateByUrl(initialUrl);
67+
}
68+
return harness;
69+
}
70+
71+
/** @internal */
72+
constructor(private readonly fixture: ComponentFixture<RootCmp>) {}
73+
74+
/** Instructs the root fixture to run change detection. */
75+
detectChanges(): void {
76+
this.fixture.detectChanges();
77+
}
78+
/** The `DebugElement` of the `RouterOutlet` component. `null` if the outlet is not activated. */
79+
get routeDebugElement(): DebugElement|null {
80+
const outlet = this.fixture.componentInstance.outlet;
81+
if (!outlet || !outlet.isActivated) {
82+
return null;
83+
}
84+
return this.fixture.debugElement.query(v => v.componentInstance === outlet.component);
85+
}
86+
/** The native element of the `RouterOutlet` component. `null` if the outlet is not activated. */
87+
get routeNativeElement(): HTMLElement|null {
88+
return this.routeDebugElement?.nativeElement ?? null;
89+
}
90+
91+
/**
92+
* Triggers a `Router` navigation and waits for it to complete.
93+
*
94+
* The root component with a `RouterOutlet` created for the harness is used to render `Route`
95+
* components. The root component is reused within the same test in subsequent calls to
96+
* `navigateForTest`.
97+
*
98+
* When testing `Routes` with a guards that reject the navigation, the `RouterOutlet` might not be
99+
* activated and the `activatedComponent` may be `null`.
100+
*
101+
* {@example router/testing/test/router_testing_harness_examples.spec.ts region='Guard'}
102+
*
103+
* @param url The target of the navigation. Passed to `Router.navigateByUrl`.
104+
* @returns The activated component instance of the `RouterOutlet` after navigation completes
105+
* (`null` if the outlet does not get activated).
106+
*/
107+
async navigateByUrl(url: string): Promise<null|{}>;
108+
/**
109+
* Triggers a router navigation and waits for it to complete.
110+
*
111+
* The root component with a `RouterOutlet` created for the harness is used to render `Route`
112+
* components.
113+
*
114+
* {@example router/testing/test/router_testing_harness_examples.spec.ts region='RoutedComponent'}
115+
*
116+
* The root component is reused within the same test in subsequent calls to `navigateByUrl`.
117+
*
118+
* This function also makes it easier to test components that depend on `ActivatedRoute` data.
119+
*
120+
* {@example router/testing/test/router_testing_harness_examples.spec.ts region='ActivatedRoute'}
121+
*
122+
* @param url The target of the navigation. Passed to `Router.navigateByUrl`.
123+
* @param requiredRoutedComponentType After navigation completes, the required type for the
124+
* activated component of the `RouterOutlet`. If the outlet is not activated or a different
125+
* component is activated, this function will throw an error.
126+
* @returns The activated component instance of the `RouterOutlet` after navigation completes.
127+
*/
128+
async navigateByUrl<T>(url: string, requiredRoutedComponentType: Type<T>): Promise<T>;
129+
async navigateByUrl<T>(url: string, requiredRoutedComponentType?: Type<T>): Promise<T|null> {
130+
const router = TestBed.inject(Router);
131+
let resolveFn!: () => void;
132+
const redirectTrackingPromise = new Promise<void>(resolve => {
133+
resolveFn = resolve;
134+
});
135+
afterNextNavigation(TestBed.inject(Router), resolveFn);
136+
await router.navigateByUrl(url);
137+
await redirectTrackingPromise;
138+
this.fixture.detectChanges();
139+
const outlet = this.fixture.componentInstance.outlet;
140+
// The outlet might not be activated if the user is testing a navigation for a guard that
141+
// rejects
142+
if (outlet && outlet.isActivated && outlet.activatedRoute.component) {
143+
const activatedComponent = outlet.component;
144+
if (requiredRoutedComponentType !== undefined &&
145+
!(activatedComponent instanceof requiredRoutedComponentType)) {
146+
throw new Error(`Unexpected routed component type. Expected ${
147+
requiredRoutedComponentType.name} but got ${activatedComponent.constructor.name}`);
148+
}
149+
return activatedComponent as T;
150+
} else {
151+
return null;
152+
}
153+
}
154+
}

‎packages/router/testing/src/testing.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,4 @@
1212
* Entry point for all public APIs of the router/testing package.
1313
*/
1414
export * from './router_testing_module';
15+
export {RouterTestingHarness} from './router_testing_harness';

‎packages/router/testing/test/BUILD.bazel‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
load("//tools:defaults.bzl", "jasmine_node_test", "karma_web_test_suite", "ts_library")
2+
3+
ts_library(
4+
name = "test_lib",
5+
testonly = True,
6+
srcs = glob(["**/*.ts"]),
7+
# Visible to //:saucelabs_unit_tests_poc target
8+
visibility = ["//:__pkg__"],
9+
deps = [
10+
"//packages/common",
11+
"//packages/common/testing",
12+
"//packages/core",
13+
"//packages/core/testing",
14+
"//packages/platform-browser",
15+
"//packages/platform-browser-dynamic",
16+
"//packages/platform-browser/testing",
17+
"//packages/private/testing",
18+
"//packages/router",
19+
"//packages/router/testing",
20+
"@npm//rxjs",
21+
],
22+
)
23+
24+
jasmine_node_test(
25+
name = "test",
26+
bootstrap = ["//tools/testing:node"],
27+
deps = [
28+
":test_lib",
29+
],
30+
)
31+
32+
karma_web_test_suite(
33+
name = "test_web",
34+
deps = [
35+
":test_lib",
36+
],
37+
)

0 commit comments

Comments
 (0)