Setting the scene
We write JavaScript to perform business logic client-side on Dynamics forms.
- Sometimes we want to dynamically alter the layout of a form (collapse tabs, hide sections etc.)
- Sometimes we want to update field values
- And sometimes we want to retrieve data from Dynamics using the Web API and then act on it
No matter why we're writing client-side scripts, we always want to write tests for them.
I've previously written in this blog post and others how basic Xrm functions can be tested against using xrm-mock. However, what about more advanced Xrm functions such as Xrm.WebApi?
Introducing the Web API with v9
Xrm.WebApi was introduced with Dynamics 365 version 9. In Microsoft's words, it: "Provides properties and methods to use Web API to create and manage records and execute Web API actions and functions in Customer Engagement".
My interpretation would be that it enables developers to interact with the Web API using shorthand code. For example, prior to version 9, one would write the following to create an account:
Now, using Xrm.WebApi this can be rewritten as:
Faking Web API calls using xrm-mock
XrmMockGenerator.initialise() initialises an empty Xrm.WebAPI object. Calls to its methods such as createRecord throw a not implemented error. The current recommended approach is to therefore stub any API methods being called in the code under test, and force their return values. This allows you to:
- control your test's expected behaviour
- prevent direct calls to the Dynamics database via XMLHttpRequest or similar
Here's an example
This example demonstrates a basic client-side script running on a Contact form in Dynamics. When the form is loaded, the script:
- gets the Id of the Contact's Parent Contact via Xrm.Page.getAttribute.getValue
- retrieves the Parent Contact's name via Xrm.WebApi.retrieveRecord
- sets the Contact's description to "My parent is called {parent contact's name}" via Xrm.Page.getAttribute.setValue
This example uses Sinon.JS to help create Web Api stubs.
"Standalone and test framework agnostic JavaScript test spies, stubs and mocks (pronounced "sigh-non", named after Sinon, the warrior)."
And here's contact.test.ts, the script we'll use to test contact.ts:
Walkthrough: Understand the Code
Testing in action with Wallaby.js
And that's it
Using the example above you can see how to:
- Create a fake Xrm object to use in client-side unit tests by using xrm-mock.
- Stub a call to Xrm.WebApi to control your test's behaviour and not directly call the Dynamics database.
- Write asynchronous TypeScript code for Dynamics.
This example and all its source code is available on xrm-mock's GitHub page here.
