Notifications

The following examples use Vitest to mock the relevant functions.

Please note these tests use JavaScript and not TypeScript like other tests documented in this wiki.

Form Notifications

Form notifications can be initialised using the UI (calling XrmMockGenerator.initialise). The following method will add a mock for the setFormNotification and clearFormNotification methods:

// To use the vitest.fn() method, include vitest in your imports.
import { describe, it, expect, beforeEach, vitest } from "vitest";

// define the eventContext and formContext
const context = XrmMockGenerator.getEventContext();
const formContext = context.getFormContext();

// Create a mock for setFormNotification and clearFormNotification.
formContext.ui.setFormNotification = vitest.fn();
formContext.ui.clearFormNotification = vitest.fn();

// Execute your test
// <YOUR TEST HERE>

// Assert that the setFormNotification function has been called
expect(formContext.ui.setFormNotification).toHaveBeenCalledWith(
  "This field is required.",
  "ERROR",
  "requiredFieldError"
);

Field Notifications

Sometimes you want to test a field notification. The process is similar to a form notification except the function call is made against a control rather than the form.

// To use the vitest.fn() method, include vitest in your imports.
import { describe, it, expect, beforeEach, vitest } from "vitest";

// Define the attribute and control
const exampleAttribute = XrmMockGenerator.Attribute.createString({
  name: "exampleAttribute",
  value: "12345",
});

const exampleControl = XrmMockGenerator.Control.createString({
  name: "exampleAttribute",
  attribute: exampleAttribute,
});

// define the eventContext and formContext
const context = XrmMockGenerator.getEventContext();
const formContext = context.getFormContext();

// Create a mock for setNotification and clearNotification.
exampleControl.setNotification = vitest.fn();
exampleControl.clearNotification = vitest.fn();

// Execute your test
// <YOUR TEST HERE>

// Assert the setNotification functions have been called
expect(exampleControl.setNotification).toHaveBeenCalledWith(
  "The ABN must only consist of 11 digits.",
  "abnValidationError"
);

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 value of the email field.
• sets a form notification using formContext.ui.setFormNotification if the email does not meet the specified REGEX requirements.
• clears the form notification using formContext.ui.clearFormNotification if the email meets the specified REGEX requirements.

contact.js

export default class Contact {
  // Table - in this example, we are working with the Contact table

  // OnLoad events
  static onLoad(executionContext) {
    "use strict";

    // On Load events - execute the validateEmailFormat function.
    Contact.validateEmailFormat(executionContext);
  }

  static validateEmailFormat(executionContext) {
    "use strict";
    var formContext = executionContext.getFormContext();
    var emailValue = formContext.getAttribute("emailField").getValue();
    var emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

    if (!emailPattern.test(emailValue)) {
      formContext.ui.setFormNotification(
        "Invalid email format.",
        "ERROR",
        "emailError"
      );
    } else {
      formContext.ui.clearFormNotification("emailError");
    }
  }
}

contact.test.js

import Contact from "../src/contact";
import { describe, it, expect, beforeEach, vitest } from "vitest";
import { XrmMockGenerator } from "xrm-mock";

describe("Contact", () => {
  beforeEach(() => {
    XrmMockGenerator.initialise();
  });

  // Test Case: Invalid Email Format
  it("should set a form notification for invalid email format", () => {
    // Create the email field with an invalid email value
    const emailAttribute = XrmMockGenerator.Attribute.createString({
      name: "emailField",
      value: "invalid-email", // No "@" or domain part, so invalid
    });
    const context = XrmMockGenerator.getEventContext();
    const formContext = context.getFormContext();

    formContext.ui.setFormNotification = vitest.fn();
    formContext.ui.clearFormNotification = vitest.fn();

    // Run the function to validate email format
    Contact.onLoad(context);

    // Check that the form notification for invalid email format was set
    expect(formContext.ui.setFormNotification).toHaveBeenCalledWith(
      "Invalid email format.",
      "ERROR",
      "emailError"
    );
  });

  // Test Case: Valid Email Format
  it("should clear the form notification for a valid email format", () => {
    // Create the email field with a valid email value
    const emailAttribute = XrmMockGenerator.Attribute.createString({
      name: "emailField",
      value: "[email protected]", // Properly formatted email
    });
    const context = XrmMockGenerator.getEventContext();
    const formContext = context.getFormContext();

    formContext.ui.setFormNotification = vitest.fn();
    formContext.ui.clearFormNotification = vitest.fn();

    // Run the function to validate email format
    Contact.onLoad(context);

    // Check that the form notification for invalid email format was cleared
    expect(formContext.ui.clearFormNotification).toHaveBeenCalledWith(
      "emailError"
    );
  });
});

Code explanation and walkthrough:

Import the relevant Vitest modules, in order to test and mock the notification functions.

import { describe, it, expect, beforeEach, vitest } from "vitest";

Import Contact module. This module is compiled to JavaScript and added to the Contact form in Dynamics.

import Contact from "../src/contact";

Import XrmMockGenerator to run tests.

import { XrmMockGenerator } from "xrm-mock";

Initialise a global Xrm object and create required attributes to the fake Xrm object.

XrmMockGenerator.initialise();

XrmMockGenerator.Attribute.createString("description");

// Create the email field with an invalid email value
const emailAttribute = XrmMockGenerator.Attribute.createString({
  name: "emailField",
  value: "invalid-email", // No "@" or domain part, so invalid
});

// OR

// Create the email field with a valid email value
const emailAttribute = XrmMockGenerator.Attribute.createString({
  name: "emailField",
  value: "[email protected]", // Properly formatted email
});

Define the eventContext and formContext.

const context = XrmMockGenerator.getEventContext();
const formContext = context.getFormContext();

Invoke Contact.onLoad and assert the expected outcome.

// Run the function to validate email format
Contact.onLoad(context);

// Check that the form notification for invalid email format was set
expect(formContext.ui.setFormNotification).toHaveBeenCalledWith(
  "Invalid email format.",
  "ERROR",
  "emailError"
);

// OR

// Check that the form notification for invalid email format was cleared
expect(formContext.ui.clearFormNotification).toHaveBeenCalledWith("emailError");

Author: maichopra