Unit test Web API calls with xrm-mock and SinonJS

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)."

First, here's contact.ts, the script which will be run on the Contact form:

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.

Unit test your client-side customisations: xrm-mock v3 released!

Unit testing your client-side customisations for Dynamics 365 just got easier.

xrm-mock is a package that lets you generate a fake implementation of the Xrm object in your client-side code, allowing you to unit test your scripts.

How do I install it?

Simply download xrm-mock's npm package by running

npm install xrm-mock -D

Then import the XrmMockGenerator module and initialise a global Xrm object

import { XrmMockGenerator } from "xrm-mock";
XrmMockGenerator.initialise();

Now you have a global Xrm object, which you can add attributes to, to simulate a real form in Dynamics 365.

Here's how you add basic attributes:

Now for a lookup attribute:

And finally an option set attribute:

See xrm-mock's readme and Wiki for examples of how to unit test against your newly created attributes.

What's changed in v3?

As part of xrm-mock v3 release, attribute create methods only need two arguments: a schema name and a value, as shown in the above code snippet.

Why xrm-mock?

Faking Xrm is hard and time consuming: it has several nested objects which require a detailed understanding to fake correctly. xrm-mock is gaining traction with the open source community, and can expect to see more releases in the coming months. In fact, Daryl LaBar has become a contributor and he's already hit the ground running.