feat: adds mock implementation, docs explaining

Author: Krzysztof Borowy

docs/Jest-integration.md

@@ -0,0 +1,100 @@
+# Jest integration
+
+In order to use Async Storage in your Jest tests, you need to [add implementation of its Native Module.](https://jestjs.io/docs/en/manual-mocks) 
+This library comes with a *simple*  mock (no actual functionality) that you can use. To add a custom behavior to it, checkout [customizing mock logic](#Custom-Mock-logic) section.
+
+
+## Using Async Storage mock
+
+You can use mocked Async Storage in one of two ways:
+
+### Mock `node_modules`
+
+1. In your project root directory, create `__mocks__` directory.
+2. Inside that folder, create `react-native.js` file.
+3. Inside that file, import `AsyncStorageMock` and use it to mock `NativeModules`.
+
+
+```js
+
+import AsyncStorageMock from '@react-native-community/async-storage/jest/async-storage-mock';
+
+jest.doMock('react-native', () => {
+  const reactNative = require.requireActual('react-native');
+
+  reactNative.NativeModules.RNCAsyncStorage = AsyncStorageMock;
+
+  return reactNative;
+});
+
+// to contain all other exports from RN
+export * from 'react-native';
+
+```
+
+### Use Jest setup files
+
+1. In Jest config (probably in `package.json`) add setup files location:
+
+```json
+// ...
+  "jest": {
+    // other config
+    "setupFiles": "./path/to/jestSetupFile.js"
+  },
+// ...
+
+```
+
+2. Inside your setup file, set up Async Storage mocking:
+
+
+```js
+
+import AsyncStorageMock from '@react-native-community/async-storage/jest/async-storage-mock';
+
+jest.doMock('react-native', () => {
+  const reactNative = require.requireActual('react-native');
+
+  reactNative.NativeModules.RNCAsyncStorage = AsyncStorageMock;
+
+  return reactNative;
+});
+
+```
+
+## Custom Mock logic
+
+`AsyncStorageMock` is a simple mock, without implemented functionality. If your test case relies on a storage, you can add you custom logic to it. [Go over a sample implementation in example app](../example/__mocks__/react-native.js) or see the code below:
+
+
+```js
+// somewhere in your configuration files
+import AsyncStorageMock from '@react-native-community/async-storage/jest/async-storage-mock';
+
+AsyncStorageMock.multiGet = jest.fn(([keys], callback) => {
+  // call callback with "retrieved" value after .multiGet call
+  callback();
+})
+
+export default AsyncStorageMock;
+
+```
+
+You can [check mock itself](../jest/async-storage-mock.js) to see each method's signatures.
+
+
+## Troubleshooting
+
+
+1. **`SyntaxError: Unexpected token export` in async-storage/lib/index.js**
+
+This is likely because `Jest` is not transforming Async Storage. You can point it to do so, by adding line in Jest's configuration:
+
+```json
+  "jest": {
+    // ...
+    "transformIgnorePatterns": ["/node_modules/@react-native-community/async-storage/(?!(lib))"]
+    // ...
+  }
+```

example/__mocks__/react-native.js

@@ -0,0 +1,46 @@
+/**
+ * @format
+ */
+
+import AsyncStorageMock from '../../jest/async-storage-mock';
+
+jest.doMock('react-native', () => {
+  const reactNative = require.requireActual('react-native');
+
+  let STORAGE = {};
+
+  // Implementing simple multiGet functionality
+  AsyncStorageMock.multiGet = jest.fn((keys, cb) => {
+    const values = keys.map(key => [key, STORAGE[key]]);
+
+    cb(null, values);
+  });
+
+  // Implementing simple multiSet functionality
+  AsyncStorageMock.multiSet = jest.fn((keyValuePairs, cb) => {
+    keyValuePairs.forEach(keyValue => {
+      const key = keyValue[0];
+      const value = keyValue[1];
+
+      STORAGE[key] = value;
+    });
+
+    cb();
+  });
+
+  // Implementation of clear functionality
+  AsyncStorageMock.clear = jest.fn(cb => {
+    Object.keys(STORAGE).forEach(key => {
+      delete STORAGE[key];
+    });
+
+    cb();
+  });
+
+  // use mock
+  reactNative.NativeModules.RNCAsyncStorage = AsyncStorageMock;
+
+  return reactNative;
+});
+
+export * from 'react-native';

example/__tests__/App.js

@@ -1,15 +1,34 @@
 /**
  * @format
- * @lint-ignore-every XPLATJSCOPYRIGHT1
  */
 
+// "trigger" mocking
 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('Example of AsyncStorage', () => {
+  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();
+  });
 });

example/e2e/config.json

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

jest/async-storage-mock.js

@@ -0,0 +1,50 @@
+/**
+ * @format
+ * @flow
+ */
+
+type KeyValueType = Array<[string, any]>;
+
+type CallbackType = (error: ?Error) => void;
+
+type KeysType = Array<string>;
+
+type GetKeysType = (error: ?Error, keys: KeysType) => void;
+
+type MultiGetType = (error: ?Error, result: KeyValueType) => void;
+
+const AsyncStorageMock = {
+  /**
+   * Clears all keys in storage
+   */
+  clear: (cb: CallbackType) => cb(),
+
+  /**
+   * Returns an array of keys from storage
+   */
+  getAllKeys: (cb: GetKeysType) => cb(null, []),
+
+  /**
+   * Returns an array of array of key-value pair from storage
+   * i.e: [["name", "John"], ["age", 23]]
+   */
+  multiGet: (_: KeyValueType, cb: MultiGetType) => cb(null, []),
+
+  /**
+   * Saves key-values to storage, by accepting array of array of key-values
+   * i.e: [["name", "Sarah"], ["age", 32]]
+   */
+  multiSet: (_: KeyValueType, cb: CallbackType) => cb(null),
+
+  /**
+   * Removes entries with given keys from storage
+   */
+  multiRemove: (_: KeysType, cb: CallbackType) => cb(),
+
+  /**
+   * Merges existing and new values for a given set of keys.
+   */
+  multiMerge: (_: KeyValueType, cb: CallbackType) => cb(),
+};
+
+export default AsyncStorageMock;

lib/hooks.js

@@ -1,3 +1,7 @@
+/**
+ * @format
+ */
+
 import AsyncStorage from './AsyncStorage';
 
 type AsyncStorageHook = {

lib/index.js

@@ -1,2 +1,8 @@
-export default from './AsyncStorage';
-export { useAsyncStorage } from './hooks';
+/**
+ * @format
+ */
+
+import AsyncStorage from './AsyncStorage';
+
+export default AsyncStorage;
+export {useAsyncStorage} from './hooks';

package.json

@@ -54,7 +54,8 @@
     "semantic-release": "15.13.3"
   },
   "jest": {
-    "preset": "react-native"
+    "preset": "react-native",
+    "testMatch": [ "**/__tests__/**/*.[jt]s?(x)", "**/?(*.)+(test).[jt]s?(x)" ]
   },
   "detox": {
     "test-runner": "jest",