@formidable-webview/ersatz v2.1.3

@formidable-webview/ersatz

:rocket: Emulate and test WebView behaviors in node with jest and jsdom (written in Typescript :blue_heart:)

When Should I Use this Library?

The best use-case is when your application or library uses a WebView component with injected JavaScript. With Ersatz, you can mock the WebView, perform assertions on the DOM, and verify that your JS to native communication is behaving as expected. Fundamentally, you can now-on consider code injected in a WebView as part of the codebase and tested as deemed appropriate.

How to Use?

The easiest way to use Ersatz is in combination with jest, @formidable-webview/ersatz-testing and @testing-library/react-native. See examples here. Because there is no hard dependency on jest, You should be able to use Ersatz with any testing framework running on node, capable of mounting React components.

Compatibility Table

Emulated Features

Basic Props

All the props in common with ScrollView are supported.

• Deprecated props are ignored.
• Platform-specific props are ignored.

Other props which can influence the DOM or the WebView and their support are listed bellow. If a prop is not listed, it is probably irrelevant (related to visual rendering) and will be ignored:

DOM Event Handlers Props

To reproduce the logic behind the different event handlers, we based our assumptions on the doc, the original source code and manual testing in Android, at version 10.3.3 of react-native-webview. If you find a divergence in behaviors, you are welcome to open a bug report. Bellow is a list of event handler props with a description of our understanding of when this handler will be invoked.

Instance Methods

Additional Instance Methods specifics to Ersatz

Load Cycle

As per the manual tests we performed, a load cycle appears to start:

• When the component is mounted with a source prop;
• When an attribute of source changes (a deep-equal don't trigger);
• When the reload method is invoked;
• When the document.location.href is changed (internal navigation);
• When any event handler reference is changed;

FETCHING (0)   LOAD START (1)              PROGRESS (2)      LOAD END (3)
onHttpError -> onLoadStart              -> onLoadProgress -> onLoadEnd
               onNavigationStateChange                       onNavigationStateChange
                                                             onLoad (success)
                                                             onError (failure)

According to the documentation, injectedJavaScriptBeforeContentLoaded and injectedScript are loaded between (1) and (3), but injectedJavaScriptBeforeContentLoaded is run right after document object creation, while injectedScript is run after DOMContentLoaded event. Our manual tests found out that both scripts have access to window.ReactNativeWebView.

Edge cases

• When loaded with an undefined source prop, onLoadStart is triggered with loading: false.
• When loaded with an undefined source prop, injectedJavaScript and other scripts are still run.
• When loaded with a source.url prop, url in events is set to about:blank.

Caveats

• NativeSyntheticEvents types are respected, but outside of nativeEvent attribute, their content is meaningless.
• The mounting of the DOM is performed with jsdom. Thus, the assertions you can do on the DOM are constrained by this library capabilities. Notably:
  • because there is no real visual rendering performed, elements will have dimensions of size 0.
  • the absence of a Navigation API. A detailed list of caveats is available here.