Adds an abstraction layer / facade between Angular components and the ngrx store with powerful testing helpers
npm install @ngxp/store-serviceAdds an abstraction layer between Angular components and the @ngrx store and effects. This decouples the components from the store, selectors, actions and effects and makes it easier to test components.
* Installation
* Comparison
* Before
* After
* Documentation
* StoreService
* Selectors
* Actions
* Observers
* Observe multiple types
* Use objects with type property
* String action types
* Custom mapper
* Deprecated Annotations
* Testing
* Testing Components
* Testing Selectors
* Testing Actions
* Testing Observers
* Testing StoreService
* Testing StoreService Selectors
* Testing StoreService Actions
* Testing StoreService Observers
* Examples
* Example Store Service
* Example Tests
Get the latest version from NPM
``sh`
npm install @ngxp/store-service
> Component
`ts
import { Component } from '@angular/core';
import { Observable } from 'rxjs';
import { Book } from 'src/app/shared/books/book.model';
// Tight coupling to ngrx, state model, selectors and actions
import { Store } from '@ngrx/store';
import { Actions, ofType } from '@ngrx/effects';
import { AppState } from 'src/app/store/appstate.model';
import { getAllBooks, getBook } from 'src/app/store/books/books.selectors';
import { addBookAction, booksLoadedAction } from 'src/app/store/books/books.actions';
@Component({
selector: 'nss-book-list',
templateUrl: './book-list.component.html',
styleUrls: ['./book-list.component.scss']
})
export class BookListComponent {
books$: Observable
book$: Observable
booksLoaded: boolean = false;
constructor(
private store: Store
private actions: Actions
) {
this.books$ = this.store.select(getAllBooks);
this.book$ = this.store.select(getBook, { id: 0 });
this.actions
.pipe(
ofType(booksLoadedAction),
map(() => this.loaded = true)
)
.suscribe();
}
addBook(book: Book) {
this.store.dispatch(addBookAction({ book }));
}
}
`
> Component
`ts
import { Component } from '@angular/core';
import { Observable } from 'rxjs';
import { Book } from 'src/app/shared/books/book.model';
import { BookStoreService } from 'src/app/shared/books/book-store.service';
// Reduced to just one dependency. Loose coupling
@Component({
selector: 'nss-book-list',
templateUrl: './book-list.component.html',
styleUrls: ['./book-list.component.scss']
})
export class BookListComponent {
books$: Observable
book$: Observable
booksLoaded: boolean = false;
constructor(
private bookStore: BookStoreService // <- StoreService
) {
this.books$ = this.bookStore.getAllBooks(); // <- Selector
this.book$ = this.bookStore.getBook({ id: 0 }); // <- Selector
this.bookStore.booksLoaded$ // <-- Observer / Action stream of type
.pipe(
map(() => this.loaded = true)
)
.subscribe();
}
addBook(book: Book) {
this.bookStore.addBook({ book }); // <- Action
}
}
`
> BookStoreService
`ts
import { Injectable } from '@angular/core';
import { select, StoreService, dispatch, observe } from '@ngxp/store-service';
import { Book } from 'src/app/shared/books/book.model';
import { getBooks } from 'src/app/store/books/books.selectors';
import { State } from 'src/app/store/store.model';
import { addBookAction, booksLoadedAction } from 'src/app/store/books/books.actions';
@Injectable()
export class BookStoreService extends StoreService
getAllBooks = select(getBooks); // <- Selector
getBook = select(getBook); // <- Selector
addBook = dispatch(addBookAction); // <- Action
booksLoaded$ = observe([booksLoadedAction]); // <- Observer / Action stream
}
`
The BookStoreService Injectable class has to extend the StoreService class where State is your ngrx state model.
`ts
import { StoreService } from '@ngxp/store-service';
import { AppState } from 'app/store/state.model';
@Injectable()
export class BookStoreService extends StoreService
...
}
`
To use selectors you wrap the ngrx selector inside the select(...) function:
`ts
// Define the selector function
export const selectAllBooks = createSelector(
(state: State) => state.books;
};
//Or with props
export const selectBook = createSelector(
(state: State, props: { id: number }) => state.books[id];
};
...
// Use the selector function inside the select(...) function
allBooks = select(selectAllBooks); // () => Observable
book = select(selectBook); // (props: { id: number }) => Observable
`
The function automatically infers the correct typing according to the props and return type of the selector.
To dispatch actions add a property with the dispatch(...) function.
`ts
// Defined the Action as a class
export const loadBooksAction = createAction('[Books] Load books');
export const addBookAction = createAction('[Books] Add book' props<{ book: Book}>())
...
loadBooks = dispatch(loadBooksAction); // () => void
addBook = dispatch(addBookAction); // (props: { book: Book }) => void
`
The dispatch(...) function automatically infers the parameters according to the props of the action.
Observers are a way to listen for specific action types on the Actions stream from @ngrx/effects.
`ts`
booksLoaded$ = observe([booksLoadedAction]);
pipe.`ts
booksLoaded$ = observe([booksLoadedAction, booksLoadFailedAction]);
`$3
The function has an additional parameter to provide a custom customMapper mapping function.
Initially this will be:
`ts
action => action
`To use a custom mapper, provide it as second argument in the
function.`ts
export const toData = action => action.data;...
dataLoaded$ = observe([dataLoadedAction], toData);
`Deprecated Annotations
Before Version 12 the Store Service used annotations instead of functions. This old way still works but is deprecated and _will be removed in the future_.
ts
import { Select, StoreService, Dispatch, Selector, Dispatcher, Observe } from '@ngxp/store-service';@Select(getBooks)
getAllBooks: Selector;
@Dispatch(addBookAction)
addBook: Dispatcher;
@Observe([dataLoadedAction], toData)
dataLoaded$: Observable;
`Testing
Testing your components and the StoreService is easy. The package provides useful test-helpers to reduce testing friction.Testing Components
$3
To test selectors you provide the
StoreService using the provideStoreServiceMock method in the testing module of your component. Then get the StoreServiceMock instance using the getStoreServiceMock helper function.
`ts
import { provideStoreServiceMock, StoreServiceMock, getStoreServiceMock } from '@ngxp/store-service/testing';
...
let bookStoreService: StoreServiceMock;
...
TestBed.configureTestingModule({
declarations: [
BookListComponent
],
providers: [
provideStoreServiceMock(BookStoreService)
]
})
...
bookStoreService = getStoreServiceMock(BookStoreService);
`The
class replaces all selector functions on the store service class with a BehaviorSubject. So now you can do the following to emit new values to the observables:`ts
bookStoreService.getAllBooks().next(newBooks);
`The
is initialized with the value being undefined. If you want a custom initial value, the provideStoreServiceMock method offers an optional parameter. This is an object of key value pairs where the key is the name of the selector function, e.g. getAllBooks.`ts
import { provideStoreServiceMock, StoreServiceMock, getStoreServiceMock } from '@ngxp/store-service/testing';
...
let bookStoreService: StoreServiceMock;
...
TestBed.configureTestingModule({
declarations: [
BookListComponent
],
providers: [
provideStoreServiceMock(BookStoreService, {
getAllBooks: []
})
]
})
...
bookStoreService = getStoreServiceMock(BookStoreService);
`The
for getAllBooks is now initialized with an empty array instead of undefined.$3
To test if a component calls the dispatch methods you provide the
StoreService using the provideStoreServiceMock method in the testing module of your component. Then get the StoreServiceMock instance using the getStoreServiceMock helper function.You can then spy on the method as usual.
`ts
import { provideStoreServiceMock, StoreServiceMock } from '@ngxp/store-service/testing';
...
let bookStoreService: StoreServiceMock;
...
TestBed.configureTestingModule({
declarations: [
NewBookComponent
]
imports: [
provideStoreServiceMock(BookStoreService)
]
})
...
it('adds a new book', () => {
const book: Book = getBook();
const addBookSpy = jest.spyOn(bookStoreService, 'addBook'); component.book = book;
component.addBook();
expect(addBookSpy).toHaveBeenCalledWith({ book });
});
`$3
To test observers inside components you provide the
using the provideStoreServiceMock method in the testing module of your component. Then get the StoreServiceMock instance using the getStoreServiceMock helper function.
`ts
import { provideStoreServiceMock, StoreServiceMock, getStoreServiceMock } from '@ngxp/store-service/testing';
...
let bookStoreService: StoreServiceMock;
...
TestBed.configureTestingModule({
declarations: [
BookListComponent
],
providers: [
provideStoreServiceMock(BookStoreService)
]
})
...
bookStoreService = getStoreServiceMock(BookStoreService);
`The
class replaces all observer properties on the store service class with a BehaviorSubject. So now you can do the following to emit new values to the subscribers:`ts
bookStoreService.booksLoaded$().next(true);
`The
is initialized with the value being undefined. If you want a custom initial value, the provideStoreServiceMock method offers an optional parameter. This is an object of key value pairs where the key is the name of the observer property, e.g. booksLoaded$.`ts
import { provideStoreServiceMock, StoreServiceMock, getStoreServiceMock } from '@ngxp/store-service/testing';
...
let bookStoreService: StoreServiceMock;
...
TestBed.configureTestingModule({
declarations: [
BookListComponent
],
providers: [
provideStoreServiceMock(BookStoreService, {
booksLoaded$: false
})
]
})
...
bookStoreService = getStoreServiceMock(BookStoreService);
`The
for booksLoaded$ is now initialized with false instead of undefined.
Testing StoreService
To test the
StoreService itself you use the provided test helpers from @ngrx/store/testing and @ngrx/effects/testing.$3
You can provide mocks for selectors with the
provideMockStore from @ngrx/store/testing a. See (@ngrx/store Testing)[https://ngrx.io/guide/store/testing] for their documentation.Mock the selectors using the
provideMockStore function and check if the StoreService returns an Observable with the mocked value.`ts
import { MockStore, provideMockStore, getStoreServiceMock } from '@ngrx/store/testing';
import { BookStoreService } from 'src/app/shared/books/book-store.service';
import { selectBook, selectBooks } from '../../store/books/books.selectors';describe('BookStoreService', () => {
let bookStoreService: BookStoreService;
let mockStore: MockStore<{ books: BookState }>;
const books: Book[] = [
{
author: 'Joost',
title: 'Testing the StoreService',
year: 2019
}
];
beforeEach(waitForAsync(() => {
TestBed.configureTestingModule({
providers: [
BookStoreService,
provideMockStore({
selectors: [
{
selector: selectBooks,
value: books
},
{
selector: selectBook,
value: books[0]
}
]
})
]
});
}));
beforeEach(() => {
bookStoreService = getStoreServiceMock(BookStoreService);
mockStore = TestBed.inject(Mockstore);
});
it('executes the getBooks Selector', () => {
const expected = cold('a', { a: books });
expect(bookStoreService.getAllBooks()).toBeObservable(expected);
});
it('executes the getBook Selector', () => {
const expected = cold('a', { a: books[0] });
expect(bookStoreService.getBook({ id: 0 })).toBeObservable(expected);
});
});
`$3
You can provide mocks for selectors with the
from @ngrx/store/testing a. See (@ngrx/store Testing)[https://ngrx.io/guide/store/testing] for their documentation.Mock the selectors using the
provideMockStore function and check if the StoreService returns an Observable with the mocked value.To test if the
StoreService dispatches the correct actions the MockStore from @ngrx has a property called scannedActions$. This is an Observable of all dispatched actions to check if an action was dispatched correctly.`ts
import { MockStore, provideMockStore, getStoreServiceMock } from '@ngrx/store/testing';
import { cold } from 'jest-marbles';
import { BookStoreService } from 'src/app/shared/books/book-store.service';
import { addBookAction, loadBooksAction } from '../../store/books/books.actions';describe('BookStoreService', () => {
let bookStoreService: BookStoreService;
let mockStore: MockStore<{ books: BookState }>;
beforeEach(waitForAsync(() => {
TestBed.configureTestingModule({
providers: [
BookStoreService,
provideMockStore()
]
});
}));
beforeEach(() => {
bookStoreService = getStoreServiceMock(BookStoreService);
mockStore = TestBed.inject(MockStore);
});
it('dispatches a new addBookAction', () => {
const book: Book = getBook();
bookStoreService.addBook({ book });
const expected = cold('a', { a: addBookAction({ book }) });
expect(mockStore.scannedActions$).toBeObservable(expected);
});
it('dispatches a new loadBooksAction', () => {
bookStoreService.loadBooks();
const expected = cold('a', { a: loadBooksAction() });
expect(mockStore.scannedActions$).toBeObservable(expected);
});
});
`$3
To test the observers / actions stream, you import the
from @ngrx/effects/testing inside the testing module.
Then check if the Observer filters the correct actions.`ts
import { getStoreServiceMock } from '@ngxp/store-service/testing';
import { provideMockActions } from '@ngrx/effects/testing';
import { BehaviorSubject } from 'rxjs';
import { BookStoreService } from 'src/app/shared/books/book-store.service';
import { booksLoadedAction } from '../../store/books/books.actions';describe('BookStoreService', () => {
let bookStoreService: BookStoreService;
const mockActions = new BehaviorSubject(undefined);
beforeEach(waitForAsync(() => {
TestBed.configureTestingModule({
providers: [
BookStoreService,
provideMockActions(mockActions)
]
});
}));
beforeEach(() => {
bookStoreService = getStoreServiceMock(BookStoreService);
});
it('filters the BooksLoadedActions in booksLoaded$', () => {
const expectedValue: Book[] = [{
author: 'Author',
title: 'Title',
year: 2018
}];
const action = booksLoadedAction({ books: expectedValue });
mockActions.next(action);
const expected = cold('a', { a: action });
expect(bookStoreService.booksLoaded$()).toBeObservable(expected);
});
});
`Examples
For detailed examples of all this have a look at the Angular Project in the apps/store-service-sample folder.
Example Store Service
Have a look at the BookStoreService
Example Tests
For examples on Component Tests please have look at the test for the BookListComponent and the NewBookComponent
Testing the