feat: improve, document module testability (#587)

* feat: prep for improving module testability

* fix tests

* tests, docs

* docs

* add link to examples

* fix ci checks

* fix TOC

Author: vonovak

README.md

@@ -83,6 +83,7 @@ React Native date & time picker component for iOS, Android and Windows.
     - [`style` (`optional`, `iOS only`)](#style-optional-ios-only)
     - [`disabled` (`optional`, `iOS only`)](#disabled-optional-ios-only)
     - [`onError` (`optional`, `Android only`)](#onError-optional-android-only)
+  - [Testing with Jest](#testing-with-jest)
   - [Migration from the older components](#migration-from-the-older-components)
   - [Contributing to the component](#contributing-to-the-component)
   - [Manual installation](#manual-installation)
@@ -146,8 +147,8 @@ export const App = () => {
       value: date,
       onChange,
       mode: currentMode,
-      is24Hour: true
-    })
+      is24Hour: true,
+    });
   };
 
   const showDatepicker = () => {
@@ -160,16 +161,12 @@ export const App = () => {
 
   return (
     <View>
-      <View>
-        <Button onPress={showDatepicker} title="Show date picker!" />
-      </View>
-      <View>
-        <Button onPress={showTimepicker} title="Show time picker!" />
-      </View>
+      <Button onPress={showDatepicker} title="Show date picker!" />
+      <Button onPress={showTimepicker} title="Show time picker!" />
       <Text>selected: {date.toLocaleString()}</Text>
     </View>
   );
-}
+};
 ```
 
 ### Component usage on iOS / Android / Windows
@@ -187,7 +184,10 @@ export const App = () => {
   };
 
   const showMode = (currentMode) => {
-    setShow(true);
+    if (Platform.OS === 'android') {
+      setShow(false);
+      // for iOS, add a button that closes the picker
+    }
     setMode(currentMode);
   };
 
@@ -201,12 +201,8 @@ export const App = () => {
 
   return (
     <View>
-      <View>
-        <Button onPress={showDatepicker} title="Show date picker!" />
-      </View>
-      <View>
-        <Button onPress={showTimepicker} title="Show time picker!" />
-      </View>
+      <Button onPress={showDatepicker} title="Show date picker!" />
+      <Button onPress={showTimepicker} title="Show time picker!" />
       <Text>selected: {date.toLocaleString()}</Text>
       {show && (
         <DateTimePicker
@@ -219,12 +215,11 @@ export const App = () => {
       )}
     </View>
   );
-}
+};
 ```
 
 </details>
 
-
 ## Localization note
 
 By localization, we refer to the language (names of months and days), as well as order in which date can be presented in a picker (month/day vs. day/month) and 12 / 24 hour-format.
@@ -241,16 +236,15 @@ There is also the iOS-only locale prop that can be used to force locale in some
 
 For Expo, follow the [localization docs](https://docs.expo.dev/distribution/app-stores/#localizing-your-ios-app).
 
-
 ### Android imperative api
 
 On Android, you have a choice between using the component API (regular React component) or an imperative api (think of something like `ReactNative.alert()`).
 
-While the component API has the benefit of writing the same code on all platforms, to start we recommend using the imperative API on Android.
+While the component API has the benefit of writing the same code on all platforms, for start we recommend using the imperative API on Android.
 
 The `params` is an object with the same properties as the component props documented in the next paragraph. (This is also because the component api internally uses the imperative one.)
 
-```js
+```ts
 import { DateTimePickerAndroid } from '@react-native-community/datetimepicker';
 
 DateTimePickerAndroid.open(params: AndroidNativeProps)
@@ -294,7 +288,7 @@ List of possible values for Android
 List of possible values for iOS (maps to [preferredDatePickerStyle](https://developer.apple.com/documentation/uikit/uidatepicker/3526124-preferreddatepickerstyle?changes=latest_minor&language=objc))
 
 - `"default"` - Automatically pick the best style available for the current platform & mode.
-- `"spinner"` - the usual appearance with a wheel from which you choose values
+- `"spinner"` - the usual pre-iOS 14 appearance with a wheel from which you choose values
 - `"compact"` - Affects only iOS 14 and later. Will fall back to "spinner" if not supported.
 - `"inline"` - Affects only iOS 14 and later. Will fall back to "spinner" if not supported.
 
@@ -350,7 +344,7 @@ We strongly recommend avoiding this prop on android because of known issues in t
 
 #### `timeZoneOffsetInSeconds` (`optional`, `Windows only`)
 
-Allows changing of the time zone of the date picker. By default it uses the device's time zone.
+Allows changing of the time zone of the date picker. By default, it uses the device's time zone.
 
 ```js
 // UTC+1
@@ -423,7 +417,7 @@ Prefer localization as documented in [Localization note](#localization-note).
 
 #### `is24Hour` (`optional`, `Windows and Android only`)
 
-Allows changing of the time picker to a 24 hour format. By default, this value is decided automatcially based on the locale and other preferences.
+Allows changing of the time picker to a 24-hour format. By default, this value is decided automatically based on the locale and other preferences.
 
 ```js
 <RNDateTimePicker is24Hour={true} />
@@ -473,7 +467,7 @@ Sets style directly on picker component. By default, the picker height is determ
 
 Please note that by default, picker's text color is controlled by the application theme (light / dark mode). In dark mode, text is white and in light mode, text is black.
 
-This means that eg. if the device has dark mode turned on, and your screen background color is white, you will not see the picker. Please use the `Appearance` api to adjust the picker's background color so that it is visible, as we do in the [example App](/example/App.js).
+This means that e.g. if the device has dark mode turned on, and your screen background color is white, you will not see the picker. Please use the `Appearance` api to adjust the picker's background color so that it is visible, as we do in the [example App](/example/App.js).
 Alternatively, use the `themeVariant` prop or [opt-out from dark mode (discouraged)](https://stackoverflow.com/a/56546554/2070942).
 
 ```js
@@ -488,6 +482,16 @@ If true, the user won't be able to interact with the view.
 
 Callback that is called when an error occurs inside the date picker native code (such as null activity).
 
+## Testing with Jest
+
+If you're rendering the picker component (using the `@testing-library/react-native` or similar), you need to mock the native module:
+
+```
+"setupFiles": ["./node_modules/@react-native-community/datetimepicker/jest/setup.js"]
+```
+
+For examples of how you can write your tests, look [here](/test/userlandTestExamples.test.js).
+
 ## Migration from the older components
 
 Please see [migration.md](/docs/migration.md)

example/App.js

@@ -99,6 +99,7 @@ export const App = () => {
     if (Platform.OS === 'android') {
       setShow(false);
     }
+
     if (event.type === 'neutralButtonPressed') {
       setDate(new Date(0));
     } else {

jest.config.js

@@ -4,5 +4,6 @@ module.exports = {
   transform: {
     '^.+\\.js$': require.resolve('react-native/jest/preprocessor.js'),
   },
-  setupFiles: ['./test/setup.js'],
+  setupFiles: ['./jest/setup.js'],
+  testRegex: '(/__tests__/.*|(\\.|/)(test))\\.[jt]sx?$',
 };

jest/index.js

@@ -0,0 +1,44 @@
+/**
+ * @format
+ * @flow strict-local
+ */
+import * as androidUtils from '../src/androidUtils';
+import {DATE_SET_ACTION, DISMISS_ACTION} from '../src/constants';
+import type {PresentPickerCallback} from '../src/androidUtils';
+
+export const mockAndroidDialogDateChange = (datePickedByUser: Date) => {
+  jest.spyOn(androidUtils, 'getOpenPicker').mockImplementation(() => {
+    async function fakeDateTimePickerAndroidOpener({
+      value: timestampFromPickerValueProp,
+    }) {
+      const pickedDate = new Date(timestampFromPickerValueProp);
+      pickedDate.setFullYear(
+        datePickedByUser.getFullYear(),
+        datePickedByUser.getMonth(),
+        datePickedByUser.getDate(),
+      );
+
+      return {
+        action: DATE_SET_ACTION,
+        year: pickedDate.getFullYear(),
+        month: pickedDate.getMonth(),
+        day: pickedDate.getDate(),
+        hour: pickedDate.getHours(),
+        minute: pickedDate.getMinutes(),
+      };
+    }
+    return (fakeDateTimePickerAndroidOpener: PresentPickerCallback);
+  });
+};
+
+export const mockAndroidDialogDismissal = () => {
+  jest.spyOn(androidUtils, 'getOpenPicker').mockImplementation(() => {
+    async function fakeDateTimePickerAndroidOpener() {
+      return {
+        action: DISMISS_ACTION,
+      };
+    }
+    // $FlowExpectedError - the typings actually don't 100% reflect the native module behavior
+    return (fakeDateTimePickerAndroidOpener: PresentPickerCallback);
+  });
+};

jest/setup.js

@@ -0,0 +1,8 @@
+import {NativeModules} from 'react-native';
+NativeModules.RNDateTimePickerManager = {
+  getDefaultDisplayValue: jest.fn(() =>
+    Promise.resolve({
+      determinedDisplayValue: 'spinner',
+    }),
+  ),
+};

package.json

@@ -10,7 +10,12 @@
     "src",
     "flow-typed",
     "windows",
-    "RNDateTimePicker.podspec"
+    "RNDateTimePicker.podspec",
+    "!android/build",
+    "!ios/build",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__"
   ],
   "publishConfig": {
     "access": "public"
@@ -20,8 +25,7 @@
     "start:android": "react-native run-android --no-jetifier",
     "start:ios": "react-native run-ios --project-path example/ios",
     "start:windows": "react-native start --use-react-native-windows",
-    "test": "jest ./test",
-    "posttest": "npm run lint",
+    "test": "jest",
     "lint": "eslint {example,src,test}/**/*.js src/index.d.ts",
     "flow": "flow check",
     "detox:ios:build:debug": "detox build -c ios.sim.debug",
@@ -60,14 +64,14 @@
   },
   "homepage": "https://github.com/react-native-community/datetimepicker#readme",
   "devDependencies": {
-    "@babel/core": "^7.12.9",
-    "@babel/runtime": "^7.12.5",
+    "@babel/core": "^7.17.8",
+    "@babel/runtime": "^7.17.8",
     "@react-native-community/eslint-config": "^2.0.0",
     "@react-native-segmented-control/segmented-control": "^2.4.0",
     "@semantic-release/git": "^10.0.1",
-    "@testing-library/react-native": "^8.0.0",
-    "babel-jest": "^27.4.4",
-    "detox": "19.5.3",
+    "@testing-library/react-native": "^9.0.0",
+    "babel-jest": "^27.5.1",
+    "detox": "19.5.7",
     "eslint": "^7",
     "eslint-plugin-prettier": "^4.0.0",
     "flow-bin": "^0.158.0",
@@ -78,7 +82,7 @@
     "moment": "^2.24.0",
     "patch-package": "^6.4.7",
     "postinstall-postinstall": "^2.1.0",
-    "prettier": "^2.5.1",
+    "prettier": "^2.6.0",
     "react": "17.0.2",
     "react-native": "^0.66.4",
     "react-native-localize": "^2.2.0",

src/DateTimePickerAndroid.android.js

@@ -9,18 +9,21 @@ import {
   NEUTRAL_BUTTON_ACTION,
   ANDROID_DISPLAY,
   ANDROID_MODE,
-  ANDROID_EVT_TYPE,
-  EVENT_TYPE_SET,
 } from './constants';
 import invariant from 'invariant';
 
-import type {DateTimePickerEvent, AndroidNativeProps} from './types';
+import type {AndroidNativeProps} from './types';
 import {
   getOpenPicker,
   timeZoneOffsetDateSetter,
   validateAndroidProps,
 } from './androidUtils';
 import pickers from './picker';
+import {
+  createDateTimeSetEvtParams,
+  createDismissEvtParams,
+  createNeutralEvtParams,
+} from './eventCreators';
 
 function open(props: AndroidNativeProps) {
   const {
@@ -30,9 +33,7 @@ function open(props: AndroidNativeProps) {
     is24Hour,
     minimumDate,
     maximumDate,
-    positiveButtonLabel,
     neutralButtonLabel,
-    negativeButtonLabel,
     minuteInterval,
     timeZoneOffsetInMinutes,
     onChange,
@@ -42,54 +43,51 @@ function open(props: AndroidNativeProps) {
   invariant(originalValue, 'A date or time must be specified as `value` prop.');
 
   const valueTimestamp = originalValue.getTime();
-  const openPicker = getOpenPicker({
-    mode,
-    value: valueTimestamp,
-    display,
-    is24Hour,
-    minimumDate,
-    maximumDate,
-    minuteInterval,
-    timeZoneOffsetInMinutes,
-    positiveButtonLabel,
-    neutralButtonLabel,
-    negativeButtonLabel,
-  });
+  const openPicker = getOpenPicker(mode);
 
   const presentPicker = async () => {
     try {
-      const {action, day, month, year, minute, hour} = await openPicker();
-      let date = new Date(valueTimestamp);
-      let event: DateTimePickerEvent = {
-        type: EVENT_TYPE_SET,
-        nativeEvent: {},
-      };
+      const {action, day, month, year, minute, hour} = await openPicker({
+        value: valueTimestamp,
+        display,
+        is24Hour,
+        minimumDate,
+        maximumDate,
+        neutralButtonLabel,
+        minuteInterval,
+        timeZoneOffsetInMinutes,
+      });
 
       switch (action) {
-        case DATE_SET_ACTION:
+        case DATE_SET_ACTION: {
+          let date = new Date(valueTimestamp);
           date.setFullYear(year, month, day);
           date = timeZoneOffsetDateSetter(date, timeZoneOffsetInMinutes);
-          event.nativeEvent.timestamp = date.getTime();
+          const [event] = createDateTimeSetEvtParams(date);
           onChange?.(event, date);
           break;
+        }
 
-        case TIME_SET_ACTION:
+        case TIME_SET_ACTION: {
+          let date = new Date(valueTimestamp);
           date.setHours(hour, minute);
           date = timeZoneOffsetDateSetter(date, timeZoneOffsetInMinutes);
-          event.nativeEvent.timestamp = date.getTime();
+          const [event] = createDateTimeSetEvtParams(date);
           onChange?.(event, date);
           break;
+        }
 
-        case NEUTRAL_BUTTON_ACTION:
-          event.type = ANDROID_EVT_TYPE.neutralButtonPressed;
+        case NEUTRAL_BUTTON_ACTION: {
+          const [event] = createNeutralEvtParams(originalValue);
           onChange?.(event, originalValue);
           break;
-
+        }
         case DISMISS_ACTION:
-        default:
-          event.type = ANDROID_EVT_TYPE.dismissed;
+        default: {
+          const [event] = createDismissEvtParams(originalValue);
           onChange?.(event, originalValue);
           break;
+        }
       }
     } catch (error) {
       onError && onError(error);

src/DateTimePickerAndroid.js

@@ -1,3 +1,7 @@
+/**
+ * @format
+ * @flow strict-local
+ */
 import {Platform} from 'react-native';
 
 const warn = () => {