Block on mobile unit tests fail and instructions on how to debug (#18454

)

* Make native mobile tests a required-to-succeed job

* Proper Node debugger flag on native mobile tests

* Documentation on how to debug native mobile tests

* Look in RN first so the `Platform` import picks up the correct one

Because there's also a Platform npm package installed too, running the
native mobile unit tests locally (at least on macOS) results in picking
up the wrong object. Putting the react-native/Libraries/Utilities first,
Jest manages to resolve the proper Platform import.

See
https://github.com/facebook/react-native/blob/v0.60.0/Libraries/react-native/react-native-implementation.js#L324-L326
for the import. The ambiguity seems fixed in RN v0.61.4 with
facebook/react-native@62c605e

* Fix typo

* Add additional way to launch the Chrome dev tools for mobile

* Move the native mobile testing steps to testing-overview.md

* Fix typo

* Move the instructions closer to the regular unit testing sections

.travis.yml

@@ -214,4 +214,4 @@ jobs:
           branch: master
 
   allow_failures:
-    - name: JavaScript native mobile tests
+    # nothing is allowed to fail at the moment

docs/contributors/native-mobile.md

@@ -4,3 +4,5 @@ Intertwined with the web codepaths, the Gutenberg repo also includes the [React
 The majority of the code shared with native mobile is in the very same JavaScript module and SASS style files. In the cases where the code paths need to diverge, a `.native.js` or `.native.scss` variant of the file is created. In some cases, platform specific files can be also found for Android (`.android.js`) or iOS (`.ios.js`).
 ## Mind the mobile
 Our tooling isn't as good yet as we'd like to and it's hard to have a good awareness of those native mobile files. That means that contributors need to manually pay attention to update the native mobile files during code refactorings. For example, renaming a function or a prop should also be performed in the native modules too, otherwise, the mobile client will break. We are in the process of putting some more safeguards in place in PRs, but we're still far from done. Please bear with us and thank you in advance. ❤️🙇‍
+## Debugging the native mobile unit tests
+Follow the instructions in [Native mobile testing](/docs/contributors/testing-overview.md#native-mobile-testing) to locally debug the native mobile unit tests when neeeded.

docs/contributors/testing-overview.md

@@ -342,6 +342,21 @@ test( 'should contain mars if planets is true', () => {
 
 It's tempting to snapshot deep renders, but that makes for huge snapshots. Additionally, deep renders no longer test a single component, but an entire tree. With `shallow`, we snapshot just the components that are directly rendered by the component we want to test.
 
+## Native mobile testing
+
+Part of the unit-tests suite is a set of Jest tests run exercise native-mobile codepaths, developed in React Native. Since those tests run on Node, they can be launched locally on your development machine without the need for specific native Android or iOS dev tools or SDKs. It also means that they can be debugged using typical dev tools. Read on for instructions how to debug.
+
+### Debugging the native mobile unit tests
+
+To locally run the tests in debug mode, follow these steps:
+0. Make sure you have ran `npm ci` to install all the packages
+1. Run `npm run test-unit:native:debug` inside the Gutenberg root folder, on the CLI. Node is now waiting for the debugger to connect.
+2. Open `chrome://inspect` in Chrome
+3. Under the "Remote Target" section, look for a `../../node_modules/.bin/jest ` target and click on the "inspect" link. That will open a new window with the Chrome DevTools debugger attached to the process and stopped at the beginning of the `jest.js` file. Alternatively, if the targets are not visible, click on the `Open dedicated DevTools for Node` link in the same page.
+4. You can place breakpoints or `debugger;` statements throughout the code, including the tests code, to stop and inspect
+5. Click on the "Play" button to resume execution
+6. Enjoy debugging the native mobile unit tests!
+
 ## End to end Testing
 
 If you're using the built-in [local environment](/docs/contributors/getting-started.md#local-environment), you can run the e2e tests locally using this command:

package.json

@@ -199,7 +199,7 @@
 		"test-unit-php": "wp-scripts env test-php",
 		"test-unit-php-multisite": "cross-env WP_MULTISITE=1 wp-scripts env test-php",
 		"test-unit:native": "cd test/native/ && cross-env NODE_ENV=test jest --config ./jest.config.js",
-		"test-unit:native:debug": "cd test/native/ && node --inspect ../../node_modules/.bin/jest --runInBand --config ./jest.config.js",
+		"test-unit:native:debug": "cd test/native/ && node --inspect-brk ../../node_modules/.bin/jest --runInBand --verbose --config ./jest.config.js",
 		"prestorybook:build": "npm run build:packages",
 		"storybook:build": "build-storybook -c ./storybook -o ./playground/dist",
 		"prestorybook:dev": "npm run build:packages",

test/native/jest.config.js

@@ -38,8 +38,9 @@ module.exports = {
 		'/__device-tests__/',
 	],
 	testURL: 'http://localhost/',
-	// Add the `Libraries/Utilities` subfolder to the module directories, otherwise haste/jest doesn't find Platform.js on Travis
-	moduleDirectories: [ 'node_modules', 'node_modules/react-native/Libraries/Utilities' ],
+	// Add the `Libraries/Utilities` subfolder to the module directories, otherwise haste/jest doesn't find Platform.js on Travis,
+	// and add it first so https://github.com/facebook/react-native/blob/v0.60.0/Libraries/react-native/react-native-implementation.js#L324-L326 doesn't pick up the Platform npm module.
+	moduleDirectories: [ 'node_modules/react-native/Libraries/Utilities', 'node_modules' ],
 	moduleNameMapper: {
 		// Mock the CSS modules. See https://facebook.github.io/jest/docs/en/webpack.html#handling-static-assets
 		'\\.(scss)$': '<rootDir>/' + configPath + '/__mocks__/styleMock.js',