Add comprehensive documentation and demo tests for TestingRouterStore

Co-authored-by: LayZeeDK <[email protected]>

Author: Copilot

packages/router-component-store/README.md

@@ -208,3 +208,150 @@ export type StrictRouteParams = {
   readonly [key: string]: string | undefined;
 };
 ```
+
+## Testing
+
+Router Component Store provides testing utilities to make it easy to test components and services that depend on `RouterStore`.
+
+### TestingRouterStore
+
+`TestingRouterStore` is a testing implementation of the `RouterStore` interface that uses stubbed observables. This allows you to easily control router state in your tests without needing to set up complex routing configurations.
+
+#### Basic usage
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { provideTestingRouterStore, TestingRouterStore } from '@ngworker/router-component-store';
+
+describe('HeroDetailComponent', () => {
+  let routerStore: TestingRouterStore;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [HeroDetailComponent],
+      providers: [provideTestingRouterStore()],
+    });
+
+    routerStore = TestBed.inject(RouterStore) as TestingRouterStore;
+  });
+
+  it('should display hero ID from route param', () => {
+    const fixture = TestBed.createComponent(HeroDetailComponent);
+
+    // Set route parameter
+    routerStore.setRouteParam('id', '123');
+    fixture.detectChanges();
+
+    expect(fixture.nativeElement.textContent).toContain('Hero: 123');
+  });
+});
+```
+
+#### Testing different router states
+
+```typescript
+it('should handle various router states', () => {
+  // Set URL
+  routerStore.setUrl('/heroes/456?search=batman#details');
+  
+  // Set individual parameters
+  routerStore.setRouteParam('id', '456');
+  routerStore.setQueryParam('search', 'batman');
+  routerStore.setFragment('details');
+  
+  // Set route data
+  routerStore.setRouteDataParam('title', 'Hero Details');
+  routerStore.setRouteDataParam('breadcrumbs', ['Home', 'Heroes']);
+  
+  // Or set multiple values at once
+  routerStore.setRouteParams({ id: '456', type: 'superhero' });
+  routerStore.setQueryParams({ search: 'batman', page: '1' });
+  routerStore.setRouteData({ title: 'Hero Details', allowEdit: true });
+
+  fixture.detectChanges();
+  
+  // Your assertions here...
+});
+```
+
+#### Testing with services
+
+```typescript
+class HeroService {
+  private routerStore = inject(RouterStore);
+  
+  currentHeroId$ = this.routerStore.selectRouteParam('id');
+  searchQuery$ = this.routerStore.selectQueryParam('q');
+}
+
+describe('HeroService', () => {
+  let service: HeroService;
+  let routerStore: TestingRouterStore;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [HeroService, provideTestingRouterStore()],
+    });
+
+    service = TestBed.inject(HeroService);
+    routerStore = TestBed.inject(RouterStore) as TestingRouterStore;
+  });
+
+  it('should emit current hero ID', (done) => {
+    service.currentHeroId$.subscribe(id => {
+      expect(id).toBe('789');
+      done();
+    });
+
+    routerStore.setRouteParam('id', '789');
+  });
+});
+```
+
+#### Available testing methods
+
+| Method | Description |
+| --- | --- |
+| `setUrl(url: string)` | Set the current URL |
+| `setFragment(fragment: string \| null)` | Set the URL fragment |
+| `setTitle(title: string \| undefined)` | Set the resolved route title |
+| `setRouteParam(param: string, value: string \| undefined)` | Set a single route parameter |
+| `setRouteParams(params: StrictRouteParams)` | Set all route parameters |
+| `setQueryParam(param: string, value: string \| readonly string[] \| undefined)` | Set a single query parameter |
+| `setQueryParams(params: StrictQueryParams)` | Set all query parameters |
+| `setRouteDataParam(key: string, value: unknown)` | Set a single route data value |
+| `setRouteData(data: StrictRouteData)` | Set all route data |
+| `setCurrentRoute(route: MinimalActivatedRouteSnapshot)` | Set the complete current route |
+| `reset()` | Reset all values to their defaults |
+
+#### Integration with RouterTestingModule
+
+While `TestingRouterStore` is great for isolated unit tests, you might sometimes want to test the full routing behavior. You can still use `RouterTestingModule` with the actual `RouterStore` implementations:
+
+```typescript
+import { provideGlobalRouterStore } from '@ngworker/router-component-store';
+import { RouterTestingModule } from '@angular/router/testing';
+
+describe('Full routing integration', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [
+        RouterTestingModule.withRoutes([
+          { path: 'heroes/:id', component: HeroDetailComponent }
+        ])
+      ],
+      providers: [provideGlobalRouterStore()],
+    });
+  });
+
+  it('should work with actual navigation', async () => {
+    const router = TestBed.inject(Router);
+    const routerStore = TestBed.inject(RouterStore);
+    
+    await router.navigate(['/heroes', '123']);
+    
+    const heroId = await firstValueFrom(routerStore.selectRouteParam('id'));
+    expect(heroId).toBe('123');
+  });
+});
+```

packages/router-component-store/src/lib/testing/testing-router-store-demo.spec.ts

@@ -0,0 +1,198 @@
+import { AsyncPipe, NgIf } from '@angular/common';
+import { Component, inject } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { firstValueFrom } from 'rxjs';
+import { RouterStore } from '../router-store';
+import { provideTestingRouterStore, TestingRouterStore } from '../testing';
+
+// Example component that uses RouterStore
+@Component({
+  standalone: true,
+  imports: [AsyncPipe, NgIf],
+  selector: 'demo-hero-detail',
+  template: `
+    <h1 [textContent]="title$ | async"></h1>
+    <div class="hero-info">
+      <p class="hero-id">Hero ID: <span [textContent]="heroId$ | async"></span></p>
+      <p class="search">Search: <span [textContent]="searchQuery$ | async"></span></p>
+      <p class="url">URL: <span [textContent]="url$ | async"></span></p>
+      <p class="allow-edit">Allow Edit: <span [textContent]="(allowEdit$ | async) ? 'Yes' : 'No'"></span></p>
+    </div>
+    <div class="breadcrumbs" *ngIf="breadcrumbs$ | async as breadcrumbs">
+      Breadcrumbs: {{ breadcrumbs.join(' > ') }}
+    </div>
+  `,
+})
+class DemoHeroDetailComponent {
+  private routerStore = inject(RouterStore);
+
+  title$ = this.routerStore.title$;
+  heroId$ = this.routerStore.selectRouteParam('id');
+  searchQuery$ = this.routerStore.selectQueryParam('search');
+  url$ = this.routerStore.url$;
+  allowEdit$ = this.routerStore.selectRouteDataParam('allowEdit');
+  breadcrumbs$ = this.routerStore.selectRouteDataParam('breadcrumbs');
+}
+
+// Example service that uses RouterStore
+class DemoHeroService {
+  private routerStore = inject(RouterStore);
+
+  currentHeroId$ = this.routerStore.selectRouteParam('id');
+  isEditMode$ = this.routerStore.selectQueryParam('edit');
+
+  async getCurrentHeroId(): Promise<string | undefined> {
+    return firstValueFrom(this.currentHeroId$);
+  }
+}
+
+describe('TestingRouterStore Demo', () => {
+  describe('Component Integration', () => {
+    let routerStore: TestingRouterStore;
+
+    beforeEach(() => {
+      TestBed.configureTestingModule({
+        imports: [DemoHeroDetailComponent],
+        providers: [provideTestingRouterStore()],
+      });
+
+      routerStore = TestBed.inject(RouterStore) as TestingRouterStore;
+    });
+
+    it('should demonstrate complete router state control', async () => {
+      const fixture = TestBed.createComponent(DemoHeroDetailComponent);
+
+      // Set up a complex router state
+      routerStore.setUrl('/heroes/123?search=batman&edit=true#details');
+      routerStore.setTitle('Batman Details');
+      routerStore.setRouteParam('id', '123');
+      routerStore.setQueryParams({ search: 'batman', edit: 'true' });
+      routerStore.setRouteData({
+        allowEdit: true,
+        breadcrumbs: ['Home', 'Heroes', 'Batman'],
+      });
+
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      const compiled = fixture.nativeElement;
+
+      // Verify the component displays all the router state correctly
+      expect(compiled.querySelector('h1')?.textContent?.trim()).toBe('Batman Details');
+      expect(compiled.querySelector('.hero-id span')?.textContent?.trim()).toBe('123');
+      expect(compiled.querySelector('.search span')?.textContent?.trim()).toBe('batman');
+      expect(compiled.querySelector('.url span')?.textContent?.trim()).toBe('/heroes/123?search=batman&edit=true#details');
+      expect(compiled.querySelector('.allow-edit span')?.textContent?.trim()).toBe('Yes');
+      expect(compiled.textContent).toContain('Breadcrumbs: Home > Heroes > Batman');
+    });
+
+    it('should handle state changes dynamically', async () => {
+      const fixture = TestBed.createComponent(DemoHeroDetailComponent);
+
+      // Start with default state
+      fixture.detectChanges();
+      expect(fixture.nativeElement.querySelector('.hero-id span')?.textContent).toBeFalsy();
+
+      // Update hero ID
+      routerStore.setRouteParam('id', '456');
+      fixture.detectChanges();
+      expect(fixture.nativeElement.querySelector('.hero-id span')?.textContent?.trim()).toBe('456');
+
+      // Reset and verify defaults are restored
+      routerStore.reset();
+      fixture.detectChanges();
+      await fixture.whenStable();
+      expect(fixture.nativeElement.querySelector('.hero-id span')?.textContent).toBeFalsy();
+    });
+  });
+
+  describe('Service Integration', () => {
+    let service: DemoHeroService;
+    let routerStore: TestingRouterStore;
+
+    beforeEach(() => {
+      TestBed.configureTestingModule({
+        providers: [DemoHeroService, provideTestingRouterStore()],
+      });
+
+      service = TestBed.inject(DemoHeroService);
+      routerStore = TestBed.inject(RouterStore) as TestingRouterStore;
+    });
+
+    it('should work with services that depend on RouterStore', async () => {
+      // Initially no hero ID
+      expect(await service.getCurrentHeroId()).toBeUndefined();
+
+      // Set hero ID and verify service picks it up
+      routerStore.setRouteParam('id', '789');
+      expect(await service.getCurrentHeroId()).toBe('789');
+    });
+
+    it('should handle observable streams', (done) => {
+      let emissionCount = 0;
+      const expectedValues = [undefined, 'first', 'second'];
+
+      service.currentHeroId$.subscribe(id => {
+        expect(id).toBe(expectedValues[emissionCount]);
+        emissionCount++;
+        
+        if (emissionCount === 3) {
+          done();
+        }
+      });
+
+      // Trigger emissions
+      routerStore.setRouteParam('id', 'first');
+      routerStore.setRouteParam('id', 'second');
+    });
+  });
+
+  describe('Complex Scenarios', () => {
+    let routerStore: TestingRouterStore;
+
+    beforeEach(() => {
+      TestBed.configureTestingModule({
+        providers: [provideTestingRouterStore()],
+      });
+
+      routerStore = TestBed.inject(RouterStore) as TestingRouterStore;
+    });
+
+    it('should handle array query parameters', async () => {
+      routerStore.setQueryParam('tags', ['action', 'superhero', 'dc']);
+      
+      const tags = await firstValueFrom(routerStore.selectQueryParam('tags'));
+      expect(tags).toEqual(['action', 'superhero', 'dc']);
+    });
+
+    it('should handle complex route data', async () => {
+      const complexData = {
+        permissions: ['read', 'write'],
+        metadata: { version: '1.0', author: 'test' },
+        settings: { theme: 'dark', language: 'en' },
+      };
+
+      routerStore.setRouteDataParam('config', complexData);
+      
+      const config = await firstValueFrom(routerStore.selectRouteDataParam('config'));
+      expect(config).toEqual(complexData);
+    });
+
+    it('should preserve independent parameter updates', async () => {
+      // Set initial state
+      routerStore.setRouteParams({ id: '1', type: 'hero' });
+      routerStore.setQueryParams({ search: 'batman', page: '1' });
+
+      // Update individual parameters
+      routerStore.setRouteParam('id', '2');
+      routerStore.setQueryParam('search', 'superman');
+
+      // Verify other parameters are preserved
+      const routeParams = await firstValueFrom(routerStore.routeParams$);
+      const queryParams = await firstValueFrom(routerStore.queryParams$);
+
+      expect(routeParams).toEqual({ id: '2', type: 'hero' });
+      expect(queryParams).toEqual({ search: 'superman', page: '1' });
+    });
+  });
+});