Add TestingRouterStore and enhanced injectTestingRouterStore to ease test setup and improve DX

[Copilot]

Implements testing utilities to simplify unit testing of components and services that depend on RouterStore, addressing the need for better testing support mentioned in issue #282.

Problem

Testing components and services that inject RouterStore currently requires complex setup with RouterTestingModule and full routing configuration, even for simple unit tests. This creates unnecessary complexity and coupling in test code.

// Current approach requires heavy setup
TestBed.configureTestingModule({
  imports: [
    RouterTestingModule.withRoutes([
      { path: 'entities/:id', component: SomeComponent }
    ])
  ],
  providers: [provideGlobalRouterStore()],
});

// Then navigate to set state
const router = TestBed.inject(Router);
await router.navigate(['/entities', '123']);

Solution

Introduces TestingRouterStore - a lightweight testing implementation of the RouterStore interface that uses stubbed observables, allowing precise control over router state without routing infrastructure. Also includes enhanced injectTestingRouterStore() function with advanced injection options.

// Simple setup with new testing utilities
TestBed.configureTestingModule({
  providers: [provideTestingRouterStore()],
});

// Option 1: Manual casting
const routerStore = TestBed.inject(RouterStore) as TestingRouterStore;
routerStore.setRouteParam('id', '123');

// Option 2: Enhanced injection helper (recommended)
TestBed.runInInjectionContext(() => {
  const routerStore = injectTestingRouterStore();
  routerStore.setRouteParam('id', '123'); // Direct access to testing methods
});

// Option 3: With injection options
TestBed.runInInjectionContext(() => {
  const routerStore = injectTestingRouterStore({ optional: true, host: true });
  routerStore?.setRouteParam('id', '123');
});

// Option 4: From component injector (for local router stores)
const routerStore = injectTestingRouterStore({
  component: HeroComponent,
  fixture,
  options: { host: true }
});

Key Features

TestingRouterStore Class

• Implements complete RouterStore interface with stubbed BehaviorSubject observables
• Provides default values for all router state properties
• Emits values synchronously for predictable test behavior

Enhanced injectTestingRouterStore Function

• Eliminates need for manual casting to TestingRouterStore
• Supports InjectOptions similar to Angular's inject() function (optional, skipSelf, self, host)
• Enables injection from specific component injectors for local router stores
• Provides direct access to testing methods with full TypeScript IntelliSense
• Multiple overloads for different testing scenarios

Testing Utility Methods

• setUrl(url), setFragment(fragment), setTitle(title) - Basic router state control
• setRouteParam(param, value) / setRouteParams(params) - Route parameter management
• setQueryParam(param, value) / setQueryParams(params) - Query parameter management
• setRouteDataParam(key, value) / setRouteData(data) - Route data manipulation
• setCurrentRoute(route) - Complete route snapshot control
• reset() - Restore all values to defaults

Provider Factory

• provideTestingRouterStore() replaces RouterStore DI token with TestingRouterStore
• Drop-in replacement for existing provider configurations
• Works with both component and service testing scenarios

Usage Examples

Basic Component Testing

@Component({
  template: '<p>Hero ID: {{ heroId$ | async }}</p>'
})
class HeroDetailComponent {
  private routerStore = inject(RouterStore);
  heroId$ = this.routerStore.selectRouteParam('id');
}

// Test becomes simple and focused
it('should display hero ID', () => {
  TestBed.runInInjectionContext(() => {
    const routerStore = injectTestingRouterStore();
    routerStore.setRouteParam('id', '456');
  });
  
  fixture.detectChanges();
  expect(fixture.nativeElement.textContent).toContain('456');
});

Local Router Store Testing

@Component({
  template: '<p>Hero: {{ heroId$ | async }}</p>',
  providers: [provideTestingRouterStore()], // Local provider
})
class HeroComponent {
  private routerStore = inject(RouterStore);
  heroId$ = this.routerStore.selectRouteParam('id');
}

// Test with component-level router store
it('should work with local router store', () => {
  const fixture = TestBed.createComponent(ParentComponent);
  
  // Inject from specific component's injector
  const routerStore = injectTestingRouterStore({
    component: HeroComponent,
    fixture,
    options: { host: true }
  });
  
  routerStore.setRouteParam('id', '123');
  fixture.detectChanges();
  
  expect(fixture.nativeElement.textContent).toContain('Hero: 123');
});

Service Testing

class HeroService {
  private routerStore = inject(RouterStore);
  currentHeroId$ = this.routerStore.selectRouteParam('id');
}

// Test observable streams easily
it('should emit hero ID changes', (done) => {
  service.currentHeroId$.subscribe(id => {
    expect(id).toBe('789');
    done();
  });

  TestBed.runInInjectionContext(() => {
    const routerStore = injectTestingRouterStore();
    routerStore.setRouteParam('id', '789');
  });
});

Benefits

• Simplified Setup: No RouterTestingModule needed for unit tests
• No Manual Casting: Enhanced injectTestingRouterStore() provides direct access to testing methods
• Angular-Consistent API: Supports InjectOptions similar to Angular's inject() function
• Local Router Store Support: Can inject from component-level providers
• Precise Control: Set exact values for any router property
• Isolated Testing: Test components/services without routing dependencies
• Better Performance: No actual routing or navigation overhead
• Type Safety: Full TypeScript support with IntelliSense for testing methods
• Backward Compatible: Existing tests continue to work unchanged

Documentation

Added comprehensive testing section to README with:

• Basic usage patterns for components and services
• Examples showing manual casting, basic injection, and enhanced injection approaches
• Local router store testing with component injectors
• InjectOptions usage examples
• Complex scenarios with arrays and nested objects
• Integration examples with RouterTestingModule for full routing tests
• Migration guide from current testing approaches

Testing

• 55 new tests covering all TestingRouterStore and enhanced injectTestingRouterStore functionality
• Integration tests with real components and services
• Component injector testing for local router stores
• InjectOptions validation tests
• All existing tests continue to pass (318 total)
• Comprehensive demo tests showing practical usage scenarios

This implementation provides advanced testing utilities that go beyond the original issue requirements, making it significantly easier to test RouterStore-dependent code in all scenarios while maintaining full compatibility with existing patterns.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[LayZeeDK]

@copilot Add an injectTestingRouterStore function so consumers can avoid casting.

[Copilot]

@copilot Add an injectTestingRouterStore function so consumers can avoid casting.

Added the injectTestingRouterStore() function as requested. This eliminates the need for manual casting and provides direct access to TestingRouterStore methods:

// Before (manual casting)
const routerStore = TestBed.inject(RouterStore) as TestingRouterStore;

// After (injection helper)
TestBed.runInInjectionContext(() => {
  const routerStore = injectTestingRouterStore();
  routerStore.setRouteParam('id', '123'); // Direct access
});

The function follows Angular's injection conventions and provides better type safety with full IntelliSense support. Updated all documentation and examples to show both approaches. Implemented in commit 9668fcf.

[LayZeeDK]

@copilot The inject function should support InjectOptions similar to TestBed.inject. It should also be possible to pass a component and use its Injector to get a local router store.

[Copilot]

@copilot The inject function should support InjectOptions similar to TestBed.inject. It should also be possible to pass a component and use its Injector to get a local router store.

Enhanced the injectTestingRouterStore() function with full InjectOptions support and component injector capabilities:

InjectOptions support (similar to TestBed.inject):

// Basic usage
const routerStore = injectTestingRouterStore();

// With injection options
const routerStore = injectTestingRouterStore({ 
  optional: true, 
  host: true,
  skipSelf: false 
});

Component injector support (for local router stores):

// Inject from specific component's injector
const routerStore = injectTestingRouterStore({
  component: HeroComponent,
  fixture,
  options: { host: true } // Optional InjectOptions
});

The function now has multiple overloads with proper TypeScript typing, including null safety for optional injection. This is particularly useful for testing local router stores provided at the component level. Implemented in commit e07f738.