state-decorator 6.6.3 → 6.7.0

package/README.md

@@ -76,19 +76,19 @@ type Props = {
 // Initial state & actions
 
 export const getInitialState = (): State => ({
-  selectedUser: null,
+  selectedUserId: null,
   user: null,
 });
 
 export const userAppActions: StoreActions<State, Actions, Props> = {
   // synchronous action (simple form)
-  selectUser: ({ state, args: [id] }) => ({ ...state, selectedUser: id }),
+  selectUser: ({ state, args: [id] }) => ({ ...state, selectedUserId: id }),
 
   // a synchronous action with side effects
   selectAndLoadUser: {
     // same as simple form, using aliases (use short context alias 's' instead of 'state')
     // effects contain only immutable state changes
-    effects: ({ s, args: [id] }) => ({ ...s, selectedUser: id }),
+    effects: ({ s, args: [id] }) => ({ ...s, selectedUserId: id }),
     // side effects (ie. other effects than state changes), using "actions" alias
     sideEffects: ({ a }) => {
       a.loadUser();
@@ -812,42 +812,138 @@ function Container(props: Props) {
 # Unit testing
 
 - The state decorator provides a testing framework for stores.
-- The base principle is that a mock store is immutable. A new store is created is setting state/props. It allows to share mock store across tests.
-- On each test, reuse/setup store or store action and:
-  - call the action and test state, side effect calls,...
-  - calls have no effects on mock store
-  - test prop changes
+- The base principle is that a mock store is immutable:
+  - a new store is created each time state or props are set.
+  - it allows to share mock store across tests.
+- The API is chainable: functions are returning a mock store, excepting test functions.
+- On a mock store, we can test the store internals after initialiation, after inbound props have changed, after actions are called.
 
 ## Getting started
 
+1. Create and setup a mock store (_createMockFromStore_)
+2. Test store after initialization (_onInit_)
+3. Test store after props changes (_onPropsChange_)
+4. Test each action:
+   1. Get mock store action (_getAction_)
+   2. setup store state/prop (_setPartialState_, _setPartialProps_)
+   3. if action is asynchronous, you can mock promise (_promiseResolves_, _promiseRejects_)
+   4. call action with params (_call_)
+   5. await response to test state/actions called...
+
+## Example
+
+The store definition is available at [TodoStore.ts](https://github.com/GlobalSport/state-decorator/blob/develop/tests/fixtures/TodoStore.ts).
+
+The test is available at [Todo.test.ts](https://github.com/GlobalSport/state-decorator/blob/develop/tests/Todo.test.ts).
+
 ```typescript
 import { createMockFromStore } from 'state-decorator/test';
 
-import { todoStore, TodoItem } from './Todos';
+import todoStore from './fixtures/TodoStore';
 
 describe('Todo', () => {
   // create a mock store and setup initial state
-  // state / props can be set in full form or partial form
   // this store can be shared accross tests because it is immutable
-  const store = createMockFromStore(todoStore, {}).setPartialState({
-    idCount: 3,
-    todoIds: ['id', 'id2'],
-    todoMap: {
-      id: {
-        id: 'id',
-        completed: true,
-        title: 'todo',
-      },
-      id2: {
-        id: 'id2',
-        completed: false,
-        title: 'todo 2',
+  const store = createMockFromStore(todoStore)
+    // or
+    //   const store = createMockStore(getInitialState, actions, props, options)
+    // initial state / props can be set in full form or partial form
+    .setPartialState({
+      idCount: 3,
+      todoIds: ['id', 'id2'],
+      todoMap: {
+        id: {
+          id: 'id',
+          completed: true,
+          title: 'todo',
+        },
+        id2: {
+          id: 'id2',
+          completed: false,
+          title: 'todo 2',
+        },
       },
-    },
+    });
+
+  describe('Initialization', () => {
+    it('if not initial todo => load list', () => {
+      store
+        .setPartialState({
+          todoIds: [],
+          todoMap: {},
+        })
+        .onInit({ initialTodos: null })
+        .test(({ state, actions }) => {
+          // test state after initialization, ie:
+          // - options.onPropsChange with onMount: true
+          // - options.onMount
+          expect(state.todoIds).toEqual([]);
+          expect(state.todoMap).toEqual({});
+
+          // test derived state
+          expect(state.todos).toEqual([]);
+
+          // test side effects also
+          expect(actions.loadRemoteList).toHaveBeenCalled();
+        });
+    });
+
+    it('initial todos => setup state and do not load list', () => {
+      store
+        .setPartialState({
+          todoIds: [],
+          todoMap: {},
+        })
+        .onInit({
+          initialTodos: [
+            {
+              id: 'item1',
+              title: 'Item 1',
+              completed: false,
+            },
+          ],
+        })
+        .test(({ state, actions }) => {
+          // test state after initialization, ie:
+          // - options.onPropsChange with onMount: true
+          // - options.onMount
+          expect(state.todoIds).toEqual(['item1']);
+          expect(state.todoMap).toEqual({
+            item1: {
+              id: 'item1',
+              title: 'Item 1',
+              completed: false,
+            },
+          });
+
+          // test derived state
+          expect(state.todos).toEqual([
+            {
+              id: 'item1',
+              title: 'Item 1',
+              completed: false,
+            },
+          ]);
+
+          // test side effects also
+          expect(actions.loadRemoteList).not.toHaveBeenCalled();
+        });
+    });
+  });
+
+  it('onSetNewTitle', async () => {
+    // always return a promise whatever if the action is asynchronous or not
+    const { state, prevState } = await store.getAction('onSetNewTitle').call('new Title');
+
+    // previous state is available for comparison
+    expect(prevState.newTitle).toEqual('');
+    expect(state.newTitle).toEqual('new Title');
   });
 
   it('onCreate', async () => {
-    await store
+    const {
+      state: { todoIds, todoMap, todos },
+    } = await store
       // set partial state and return new store, source store is untouched
       .setPartialState({
         newTitle: 'new todo',
@@ -855,37 +951,69 @@ describe('Todo', () => {
       // get a mock action that can be shared too !
       .getAction('onCreate')
       // Invokes action. It has no side effect on state of mock action
-      .call()
-      // always return a promise whatever if the action is asynchronous or not
-      .then(({ state: { todoIds, todoMap } }) => {
-        // assert state
-        expect(todoIds).toEqual(['id', 'id2', 'id3']);
-        expect(todoMap).toEqual({
-          id: {
-            id: 'id',
-            completed: true,
-            title: 'todo',
-          },
-          id2: {
-            id: 'id2',
-            completed: false,
-            title: 'todo 2',
-          },
-          id3: {
-            id: 'id3',
-            completed: false,
-            title: 'new todo',
-          },
-        });
-      });
+      .call();
+
+    // assert state
+    expect(todoIds).toEqual(['id', 'id2', 'id3']);
+    expect(todoMap).toEqual({
+      id: {
+        id: 'id',
+        completed: true,
+        title: 'todo',
+      },
+      id2: {
+        id: 'id2',
+        completed: false,
+        title: 'todo 2',
+      },
+      id3: {
+        id: 'id3',
+        completed: false,
+        title: 'new todo',
+      },
+    });
+
+    // assert derived state
+    //
+    // export const todoOptions: StoreOptions<State, Actions, Props, DerivedState> = {
+    //     derivedState: {
+    //       todos: {
+    //         getDeps: ({ s }) => [s.todoIds, s.todoMap],
+    //         get: ({ s }) => s.todoIds.map((id) => s.todoMap[id]),
+    //       },
+    //     },
+    //   };
+
+    expect(todos).toEqual([
+      {
+        id: 'id',
+        completed: true,
+        title: 'todo',
+      },
+      {
+        id: 'id2',
+        completed: false,
+        title: 'todo 2',
+      },
+      {
+        id: 'id3',
+        completed: false,
+        title: 'new todo',
+      },
+    ]);
   });
 
-  it('onToggle', async () => {
-    // this mock action is shared
+  describe('onToggle', () => {
+    // this mock action is shared in two tests but they can run in parallel
     const onToggle = store.getAction('onToggle');
 
-    // arguments of call() depend on the Store action signature, use auto completion!
-    await onToggle.call('id2').then(({ state: { todoIds, todoMap } }) => {
+    it('toggle false => true', async () => {
+      // arguments of call() depend on the Store action signature, use auto completion!
+      const {
+        state: { todoIds, todoMap },
+        actions,
+      } = await onToggle.call('id2');
+
       expect(todoIds).toEqual(['id', 'id2']);
       expect(todoMap).toEqual({
         id: {
@@ -899,9 +1027,18 @@ describe('Todo', () => {
           title: 'todo 2',
         },
       });
+
+      // if there are some side effects calling store actions, you can test them
+      // as mock actions are injected instead of real actions.
+      expect(actions.updateRemoteList).toHaveBeenCalled();
     });
 
-    await onToggle.call('id').then(({ state: { todoIds, todoMap } }) => {
+    it('toggle true => false', async () => {
+      const {
+        state: { todoIds, todoMap },
+        actions,
+      } = await onToggle.call('id');
+
       expect(todoIds).toEqual(['id', 'id2']);
       expect(todoMap).toEqual({
         id: {
@@ -915,53 +1052,103 @@ describe('Todo', () => {
           title: 'todo 2',
         },
       });
+
+      // if there are some side effects calling store actions, you can test them
+      // as mock actions are injected instead of real actions.
+      expect(actions.updateRemoteList).toHaveBeenCalled();
     });
   });
 
   // Another store / action
-  it('getList', async () => {
-    await store
-      .getAction('getList')
-      // override default promise result
-      .promiseResolves([])
-      // simulate error
-      //.promiseRejects(new Error('boom'))
-      .call()
-      .then((res) => {
-        // if there are some side effects calling store action, you test them
-        // as mock actions are injected instead of real actions.
-        expect(res.actions.sideEffectAction).toHaveBeenCalledWith('sideEffect');
-        expect(res.state).toEqual({
-          //  state...
-        });
+  describe('loadRemoteList', () => {
+    // action is shared
+    const action = store.getAction('loadRemoteList');
+
+    it('success', async () => {
+      const { state } = await action
+        // override default promise result
+        .promiseResolves([
+          {
+            id: 'item1',
+            title: 'item title',
+            completed: true,
+          },
+        ])
+        .call();
+
+      expect(state.error).toBeFalsy();
+      expect(state.todoIds).toEqual(['item1']);
+      expect(state.todoMap).toEqual({
+        item1: {
+          id: 'item1',
+          title: 'item title',
+          completed: true,
+        },
       });
+    });
+
+    it('error', async () => {
+      const { state } = await action
+        // override default promise result with error
+        .promiseRejects(new Error('boom'))
+        .call();
+
+      expect(state.error).toBeTruthy();
+    });
   });
 
-  // Another store
+  // Test effects and side effect when props are changing
+  //
+  // Here:
+  //   export const todoOptions: StoreOptions<State, Actions, Props, DerivedState> = {
+  //     onPropsChange: [
+  //       {
+  //         getDeps: (p) => [p.initialTodos],
+  //         effects: ({ s, p }) => ({ ...s, ...splitList(p.initialTodos) }),
+  //         onMount: true,
+  //       },
+  //     ],
+  //   };
   it('onPropsChange', () => {
     store
       // onPropsChange allows to test prop change, no side effect on original store
       // to create a new store with new props, use setProps or setPartialProps
       .onPropsChange({
-        prop: 'new_prop',
+        initialTodos: [
+          {
+            id: 'item1',
+            title: 'Item 1',
+            completed: false,
+          },
+        ],
       })
-      .test((res) => {
-        // test side effects
-        expect(res.actions.sideEffectAction).toHaveBeenCalledWith('sideEffect');
-        // test store props
-        expect(res.props.prop).toEqual('new_prop');
-        //
-        expect(res.state).toEqual({
-          prop1: 'new_prop',
-          derived: '', // derived state is updated
+      .test(({ state, actions }) => {
+        // test state after prop has changed
+        expect(state.todoIds).toEqual(['item1']);
+        expect(state.todoMap).toEqual({
+          item1: {
+            id: 'item1',
+            title: 'Item 1',
+            completed: false,
+          },
         });
+
+        // test derived state after prop has changed
+        expect(state.todos).toEqual([
+          {
+            id: 'item1',
+            title: 'Item 1',
+            completed: false,
+          },
+        ]);
+
+        // test side effects also
+        expect(actions.loadRemoteList).not.toHaveBeenCalled();
       });
   });
 });
 ```
 
-[![Edit Todo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/todo-forked-ml0z6?file=/src/TodoApp.tsx)
-
 ## Error testing
 
 ### Managed error
@@ -1083,10 +1270,9 @@ TypeError: Cannot set property 'crash' of null
 ### MockStore
 
 | Function        | Arguments                            | Returns             | Description                                                                                 |
-| --------------- | ------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------- |
+| --------------- | ------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------- | --- |
 | getAction       | actionName: keyof A                  | MockStoreAction     | Get a mock action instance                                                                  |
-| init            | props?: Partial<P>                   | MockResult          | Test store initialization (onPropsChanged marked onMount + onMount)                         |
-| onMount         | props: P                             | MockResult          | Test onMount. Does not change internal props.                                               |
+| onInit          | props?: Partial<P>                   | MockResult          | Test store initialization (onPropsChanged marked onMount + onMount)                         |     |
 | onPropsChange   | props: P, init?: boolean             | MockResult          | Test prop changes. Does not change internal props. Init allows to test onMount prop changes |
 | setPartialProps | props: Partial<P>                    | new mock store      | Create a new store with the merge of current props and partial props                        |
 | setPartialState | state: Partial<S>                    | new mock store      | Create a new store with the merge of current state and partial state                        |

package/index.d.ts

@@ -48,6 +48,11 @@ export declare type StoreApi<S, A extends DecoratedActions, P, DS = {}> = {
      * A function that takes a list of action names or a tuple of [action name, promiseId] and returns <code>true</code> if any action is loading.
      */
     isLoading: IsLoadingFunc<A>;
+    getConfig: () => {
+        getInitialState: (p: P) => S;
+        options: StoreOptions<S, A, P, DS>;
+        actions: StoreActions<S, A, P, DS>;
+    };
 };
 export declare type StateListenerContext<S, DS, A extends DecoratedActions> = S & DS & A & Pick<StoreApi<S, A, any, DS>, 'loading' | 'loadingMap' | 'isLoading' | 'abortAction'>;
 export declare type StateListener<S, DS, A extends DecoratedActions> = (ctx: StateListenerContext<S, DS, A>) => void;