Expose an NgReduxTestingModule to make unit testing easier. (angular-…

…redux#366)

6.2.0

* add testing module
* expose selector types as part of the API (see angular-redux#360)
* simplify unit test toolchain
* use `genDir` option to stop `ngsummary`, `ngfactory` files from polluting `src` locally

.gitignore

@@ -13,4 +13,5 @@ lib/
 .nyc_output/
 coverage/
 *.ngsummary.json
-.DS_STORE
+.DS_STORE
+.compiled

.npmignore

@@ -7,3 +7,7 @@ examples
 coverage/
 .vscode/
 docs/
+yarn.lock
+circle.yml
+npm-debug.log
+.compiled

CHANGELOG.md

@@ -1,3 +1,18 @@
+# 6.2.0 - NgReduxTestingModule
+
+## Features
+
+* Added `NgReduxTestingModule`, `MockNgRedux` to help unit test components and
+services that select from the store. See [here](docs/intro-tutorial.md#unit-testing-selections)
+for details.
+* Expose `PathSelector`, `FunctionSelector`, and `PropertySelector` types in `index.d.ts`.
+
+## Misc.
+
+* Simplified build toolchain
+* Simplified unit testing toolchain
+* Consolidated repo-specific examples in to the [example-app](https://github.com/angular-redux/example-app) repo.
+
 # 6.1.0 - Angular 4 Support
 
 Both version 2 and 4 of Angular are now supported. However Angular 2 support

docs/intro-tutorial.md

@@ -474,6 +474,77 @@ class MyComponent {
 > There's actually quite a lot more you can do with `@select` and `ngRedux.select`. Check out the
 > [API docs](https://github.com/angular-redux/store/blob/master/docs/api.md#selectkey--path--function) for more info.
 
+## Unit Testing Selections
+
+Suppose you wanted your unit test your component above. We
+expose a mock class that can help you. Just pull
+`NgReduxTestingModule` into your Angular `TestBed` configuration:
+
+`my-component.spec.ts`:
+```typescript
+import { NgReduxTestingModule, MockNgRedux } from '@angular-redux/store/testing';
+import { Subject } from 'rxjs/Subject';
+import 'rxjs/add/operator/toArray';
+
+import { MyComponent } from './my-component';
+import { IAppState } from '../store';
+
+describe('MyComponent', () => {
+  beforeEach(() => {
+    // Configure your testBed to use NgReduxTestingModule; this test the DI
+    // in the test environment to use mock versions of NgRedux and DevToolsExtension.
+    TestBed.configureTestingModule({
+      declarations: [MyComponent],
+      imports: [NgReduxTestingModule],
+    }).compileComponents();
+
+    // Reset the mock to start from a clean slate in each unit test.
+    MockNgRedux.reset();
+  });
+
+  it('Selects the current count value from Redux', done => {
+    // Create an instance of MyComponent using Angular's normal unit test features.
+    const fixture = TestBed.createComponent(MyComponent);
+    const componentUnderTest = fixture.debugElement.componentInstance;
+
+    // Get a stub we can use to drive the `@select('count')` observable used by
+    // MyComponent (above). This stub will be supplied to any relevant `.select`
+    // or `@select` calls used by the component under test by MockNgRedux.
+    const countStub: Subject<number> = MockNgRedux.getSelectorStub<IAppState, number>('count');
+
+    // Determine a sequence of values we'd like to test the Redux store with.
+    const expectedValues = [ 1, 2, 3, 4, 3, 4, 3, 2, 1];
+
+    // Drive those values through our stub.
+    expectedValues.forEach(value => countStub.next(value));
+
+    // Make sure MyComponent's selected count$ variable receives these values.
+    componentUnderTest.count$
+      .toArray()
+      .subscribe(
+        actualValues => expect(actualValues).toEqual(expectedValues),
+        null,
+        done);
+  });
+```
+
+## Unit Testing Action Dispatches
+
+For testing that actions are dispatched, I prefer to use Jasmine.spy. MockNgRedux will help you
+hook into this as well:
+
+```typescript
+it('dispatches INCREMENT when ...', () => {
+  const spy = spyOn(MockNgRedux.mockInstance, 'dispatch');
+
+  // Run your test code ...
+
+  // Perform your expectations
+  expect(spy).toHaveBeenCalledWith({type: CounterActions.INCREMENT });
+  // ... etc.
+});
+```
+
 ## The Redux Community
 
 The Redux community has a lot of powerful extensions that can be plugged into your store to

package.json

@@ -1,18 +1,18 @@
 {
   "name": "@angular-redux/store",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Angular 2 bindings for Redux",
-  "main": "./lib/index.js",
+  "main": "./lib/src/index.js",
   "scripts": {
     "prebuild": "rimraf ./lib",
-    "postbuild": "rimraf \"src/**/*.ngfactory.ts\"",
-    "build": "ngc -p tsconfig.json;",
-    "lint": "tslint 'src/**/*.ts' 'examples/counter/**.ts' --exclude 'examples/counter/node_modules'",
+    "build": "npm run build:src && npm run build:testing",
+    "build:src": "ngc -p tsconfig.json",
+    "build:testing": "ngc -p tsconfig.testing.json",
+    "lint": "tslint 'src/**/*.ts'",
     "prepublish": "npm test && npm run build",
-    "test": "karma start ./karma.conf.js --single-run",
-    "test:watch": "karma start ./karma.conf.js"
+    "test": "nyc node tests.js"
   },
-  "typings": "./lib/index.d.ts",
+  "typings": "./lib/src/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+ssh://[email protected]/angular-redux/store.git"
@@ -49,33 +49,43 @@
   },
   "homepage": "https://github.com/angular-redux/store#readme",
   "devDependencies": {
-    "@angular/common": "^4.0.0",
-    "@angular/compiler": "^4.0.0",
-    "@angular/compiler-cli": "^4.0.0",
-    "@angular/core": "^4.0.0",
-    "@angular/platform-browser": "^4.0.0",
-    "@angular/platform-browser-dynamic": "^4.0.0",
+    "@angular/animations": "^4.0.3",
+    "@angular/common": "^4.0.3",
+    "@angular/compiler": "^4.0.3",
+    "@angular/compiler-cli": "^4.0.3",
+    "@angular/core": "^4.0.3",
+    "@angular/http": "^4.0.3",
+    "@angular/platform-browser": "^4.0.3",
+    "@angular/platform-browser-dynamic": "^4.0.3",
+    "@angular/platform-server": "^4.0.3",
     "@types/jasmine": "2.5.38",
     "@types/node": "^6.0.36",
     "core-js": "^2.4.1",
-    "jasmine-core": "~2.5.2",
-    "karma": "~1.4.1",
-    "karma-chrome-launcher": "~2.0.0",
-    "karma-cli": "~1.0.1",
-    "karma-jasmine": "^1.1.0",
-    "karma-typescript": "^3.0.0",
-    "karma-typescript-angular2-transform": "^1.0.0",
+    "jasmine": "^2.5.3",
+    "nyc": "^10.2.0",
     "redux": "^3.5.0",
     "reflect-metadata": "0.1.3",
     "rimraf": "^2.5.2",
     "rxjs": "^5.0.1",
     "symbol-observable": "^1.0.1",
+    "ts-node": "^3.0.2",
     "tslint": "^3.11.0",
     "typescript": "^2.1.0",
     "zone.js": "^0.8.4"
   },
   "peerDependencies": {
     "@angular/core": "^2.4.0 || ^4.0.0",
     "redux": "^3.5.0"
+  },
+  "nyc": {
+    "extension": [
+      ".ts"
+    ],
+    "exclude": [
+      "spec/**/*.spec"
+    ],
+    "include": [
+      "src/**/*.ts"
+    ]
   }
 }

src/components/ng-redux.ts

@@ -34,6 +34,10 @@ const checkSelector = (s) => VALID_SELECTORS.indexOf(typeof s, 0) >= 0 ||
 export type PropertySelector = string | number | symbol;
 export type PathSelector = (string | number)[];
 export type FunctionSelector<RootState, S> = ((s: RootState) => S);
+export type Selector<RootState, S> = PropertySelector |
+    PathSelector |
+    FunctionSelector<RootState, S>;
+
 export type Comparator = (x: any, y: any) => boolean;
 
 // Workaround for Redux issue #1935 - remove once Redux 3.6.0 is
@@ -126,9 +130,7 @@ export class NgRedux<RootState> {
      * source Observable with distinct values.
      */
     select<S>(
-        selector?: PropertySelector |
-            PathSelector |
-            FunctionSelector<RootState, S>,
+        selector?: Selector<RootState, S>,
         comparator?: Comparator): Observable<S> {
 
         if (!selector) {

src/decorators/select.ts

@@ -1,7 +1,5 @@
 import {
-  PropertySelector,
-  PathSelector,
-  FunctionSelector,
+  Selector,
   Comparator,
   NgRedux,
 } from '../components/ng-redux';
@@ -20,7 +18,7 @@ export type PropertyDecorator = (target: any, propertyKey: string) => void;
  * @param { Comparator } comparer function for this selector
  */
 export function select<T>(
-  selector?: PropertySelector | PathSelector | FunctionSelector<any, T>,
+  selector?: Selector<any, T>,
   comparator?: Comparator): PropertyDecorator {
 
   return function decorate(target: any, key: string): void {

src/index.ts

@@ -1,11 +1,4 @@
-import { NgRedux } from './components/ng-redux';
-import { DevToolsExtension } from './components/dev-tools';
-import { select } from './decorators/select';
-import { NgReduxModule } from './ng-redux.module';
-
-export {
-  NgRedux,
-  NgReduxModule,
-  DevToolsExtension,
-  select,
-}
+export * from './components/ng-redux';
+export * from './components/dev-tools';
+export * from './decorators/select';
+export * from './ng-redux.module';

testing/dev-tools.mock.ts

@@ -0,0 +1,3 @@
+import { DevToolsExtension } from '@angular-redux/store';
+
+export class MockDevToolsExtension extends DevToolsExtension {}

testing/index.ts

@@ -0,0 +1,3 @@
+export * from './ng-redux-testing.module';
+export * from './dev-tools.mock';
+export * from './ng-redux.mock';

testing/ng-redux-testing.module.ts

@@ -0,0 +1,20 @@
+import { NgModule, ClassProvider } from '@angular/core';
+import { NgRedux, DevToolsExtension } from '@angular-redux/store';
+import { MockNgRedux } from './ng-redux.mock';
+import { MockDevToolsExtension } from './dev-tools.mock';
+
+// Needs to be initialized early so @select's use the mocked version too.
+const mockNgRedux = new MockNgRedux();
+
+export function _mockNgReduxFactory() {
+  return mockNgRedux;
+}
+
+@NgModule({
+  imports: [],
+  providers: [
+    { provide: NgRedux, useFactory: _mockNgReduxFactory },
+    { provide: DevToolsExtension, useClass: MockDevToolsExtension },
+  ],
+})
+export class NgReduxTestingModule {}