feat: Jest mocks, testing guidelines

* added mock implementation

* created docs for testing with JEst

Author: Krzysztof Borowy

.circleci/config.yml

@@ -271,8 +271,7 @@ jobs:
       - run:
           name: Wake device
           command: |
-            adb shell input keyevent
-            adb shell input keyevent 82 &
+            adb shell input keyevent 82
 
       - run:
           name: Run e2e tests

README.md

@@ -56,6 +56,10 @@ getData = async () => {
 
 See docs for [api and more examples.](docs/API.md)
 
+## Writing tests
+
+Using [Jest](https://jestjs.io/) for testing? Make sure to check out [docs on how to integrate it with this module.](./docs/Jest-integration.md)
+
 ## Contribution
 
 See the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out.

docs/Jest-integration.md

@@ -0,0 +1,87 @@
+# Jest integration
+
+Async Storage module is tighly coupled with its `NativeModule` part - it needs a running React Native application to work properly. In order to use it in tests, you have to provide its separate implementation. Follow those steps to add a mocked `Async Storage` module.
+
+## Using Async Storage mock
+
+You can use one of two ways to provide mocked version of `AsyncStorage`:
+
+### With __mocks__ directory
+
+1. In your project root directory, create `__mocks__/@react-native-community` directory.
+2. Inside that folder, create `async-storage.js` file.
+3. Inside that file, export `Async Storage` mock.
+
+```javascript
+export default from '@react-native-community/async-storage/jest/async-storage-mock'
+```
+
+### With Jest setup file
+
+1. In your Jest config (probably in `package.json`) add setup files location:
+
+```json
+"jest": {
+  "setupFiles": ["./path/to/jestSetupFile.js"]
+}
+```
+
+2. Inside your setup file, set up Async Storage mocking:
+
+```javascript
+import mockAsyncStorage from '@react-native-community/async-storage/jest/async-storage-mock';
+
+jest.mock('@react-native-community/async-storage', () => mockAsyncStorage);
+```
+## Testing with mock
+
+Each public method available from `Async Storage` is [a mock function](https://jestjs.io/docs/en/mock-functions), that you can test for certain condition, for example, if `.getItem` has been called with a specific arguments:
+
+```javascript
+it('checks if Async Storage is used', async () => {
+  await asyncOperationOnAsyncStorage();
+
+  expect(AsyncStorage.getItem).toBeCalledWith('myKey');
+})
+```
+
+## Overriding Mock logic
+
+You can override mock implementation, by replacing its inner functions:
+
+```javascript
+// somewhere in your configuration files
+import AsyncStorageMock from '@react-native-community/async-storage/jest/async-storage-mock';
+
+AsyncStorageMock.multiGet = jest.fn(([keys], callback) => {
+  // do something here to retrieve data
+  callback([]);
+})
+
+export default AsyncStorageMock;
+```
+
+You can [check its implementation](../jest/async-storage-mock.js) to get more insight into methods signatures.
+
+## Troubleshooting
+
+### **`SyntaxError: Unexpected token export` in async-storage/lib/index.js**
+
+**Note:** In React Native 0.60+, all `@react-native-community` packages are transformed by default.
+
+You need to point Jest to transform this package. You can do so, by adding Async Storage path to `transformIgnorePatterns` setting in Jest's configuration.
+
+
+```json
+"jest": {
+  "transformIgnorePatterns": ["node_modules/(?!(@react-native-community/async-storage/lib))"]
+}
+```
+
+Optionally, you can transform whole scope for `react-native-community` and `react-native`:
+
+```json
+"jest": {
+  "transformIgnorePatterns": ["node_modules/(?!(@react-native-community|react-native))"]
+}
+```

example/__tests__/App.js

@@ -1,15 +1,157 @@
 /**
  * @format
- * @lint-ignore-every XPLATJSCOPYRIGHT1
  */
+/* eslint-disable no-shadow */
 
 import 'react-native';
-import React from 'react';
-import App from '../App';
 
-// Note: test renderer must be required after react-native.
-import renderer from 'react-test-renderer';
+import AsyncStorage from '@react-native-community/async-storage';
 
-it('renders correctly', () => {
-  renderer.create(<App />);
+describe('Async Storage mock functionality', () => {
+  describe('Promise based', () => {
+    it('can read/write data to/from storage', async () => {
+      const newData = Math.floor(Math.random() * 1000);
+
+      await AsyncStorage.setItem('key', newData);
+
+      const data = await AsyncStorage.getItem('key');
+
+      expect(data).toBe(newData);
+    });
+
+    it('can clear storage', async () => {
+      await AsyncStorage.setItem('temp_key', Math.random() * 1000);
+
+      let currentValue = await AsyncStorage.getItem('temp_key');
+
+      expect(currentValue).not.toBeNull();
+
+      await AsyncStorage.clear();
+
+      currentValue = await AsyncStorage.getItem('temp_key');
+
+      expect(currentValue).toBeNull();
+    });
+
+    it('can clear entries in storage', async () => {
+      await AsyncStorage.setItem('random1', Math.random() * 1000);
+      await AsyncStorage.setItem('random2', Math.random() * 1000);
+
+      let data1 = await AsyncStorage.getItem('random1');
+      let data2 = await AsyncStorage.getItem('random2');
+
+      expect(data1).not.toBeNull();
+      expect(data2).not.toBeNull();
+
+      await AsyncStorage.removeItem('random1');
+      await AsyncStorage.removeItem('random2');
+      data1 = await AsyncStorage.getItem('random1');
+      data2 = await AsyncStorage.getItem('random2');
+      expect(data2).toBeNull();
+      expect(data1).toBeNull();
+    });
+
+    it('can use merge with current data in storage', async () => {
+      let originalPerson = {
+        name: 'Jerry',
+        age: 21,
+        characteristics: {
+          hair: 'black',
+          eyes: 'green',
+        },
+      };
+
+      await AsyncStorage.setItem('person', JSON.stringify(originalPerson));
+
+      originalPerson.name = 'Harry';
+      originalPerson.characteristics.hair = 'red';
+      originalPerson.characteristics.shoeSize = 40;
+
+      await AsyncStorage.mergeItem('person', JSON.stringify(originalPerson));
+
+      const currentPerson = await AsyncStorage.getItem('person');
+      const person = JSON.parse(currentPerson);
+
+      expect(person).toHaveProperty('name', 'Harry');
+      expect(person.characteristics).toHaveProperty('hair', 'red');
+      expect(person.characteristics).toHaveProperty('shoeSize', 40);
+    });
+  });
+
+  describe('Callback based', () => {
+    it('can read/write data to/from storage', done => {
+      const newData = Math.floor(Math.random() * 1000);
+
+      AsyncStorage.setItem('key', newData, function() {
+        AsyncStorage.getItem('key', function(_, value) {
+          expect(value).toBe(newData);
+          done();
+        }).catch(e => done.fail(e));
+      });
+    });
+    it('can clear storage', done => {
+      AsyncStorage.setItem('temp_key', Math.random() * 1000, () => {
+        AsyncStorage.getItem('temp_key', (_, currentValue) => {
+          expect(currentValue).not.toBeNull();
+          AsyncStorage.clear(() => {
+            AsyncStorage.getItem('temp_key', (_, value) => {
+              expect(value).toBeNull();
+              done();
+            }).catch(e => done.fail(e));
+          });
+        }).catch(e => done.fail(e));
+      });
+    });
+
+    it('can clear entries in storage', done => {
+      AsyncStorage.setItem('random1', Math.random() * 1000, () => {
+        AsyncStorage.setItem('random2', Math.random() * 1000, () => {
+          AsyncStorage.getItem('random1', (_, data1) => {
+            AsyncStorage.getItem('random2', (_, data2) => {
+              expect(data1).not.toBeNull();
+              expect(data2).not.toBeNull();
+
+              AsyncStorage.removeItem('random1', () => {
+                AsyncStorage.removeItem('random2', () => {
+                  AsyncStorage.getItem('random1', (_, value1) => {
+                    AsyncStorage.getItem('random2', (_, value2) => {
+                      expect(value1).toBeNull();
+                      expect(value2).toBeNull();
+                      done();
+                    }).catch(e => done.fail(e));
+                  });
+                });
+              });
+            }).catch(e => done.fail(e));
+          });
+        });
+      });
+    });
+
+    it('can use merge with current data in storage', done => {
+      let originalPerson = {
+        name: 'Jerry',
+        age: 21,
+        characteristics: {
+          hair: 'black',
+          eyes: 'green',
+        },
+      };
+
+      AsyncStorage.setItem('person', JSON.stringify(originalPerson), () => {
+        originalPerson.name = 'Harry';
+        originalPerson.characteristics.hair = 'red';
+        originalPerson.characteristics.shoeSize = 40;
+        AsyncStorage.mergeItem('person', JSON.stringify(originalPerson), () => {
+          AsyncStorage.getItem('person', (_, currentPerson) => {
+            const person = JSON.parse(currentPerson);
+            expect(person).toHaveProperty('name', 'Harry');
+            expect(person.characteristics).toHaveProperty('hair', 'red');
+            expect(person.characteristics).toHaveProperty('shoeSize', 40);
+            done();
+          }).catch(e => done.fail(e));
+        });
+      });
+    });
+  });
 });

example/e2e/asyncstorage.spec.js renamed to example/e2e/asyncstorage.e2e.js

@@ -1,4 +1,5 @@
 {
     "setupFilesAfterEnv": ["./init.js"],
-    "testEnvironment": "node"
+    "testEnvironment": "node",
+    "testMatch": [ "**/?(*.)+(e2e).[jt]s?(x)" ]
 }

example/e2e/config.json

@@ -0,0 +1,7 @@
+/**
+ * @format
+ */
+
+import mockAsyncStorage from '../jest/async-storage-mock';
+
+jest.mock('@react-native-community/async-storage', () => mockAsyncStorage);