Testing your Extension

Prerequisites

• Node.js and npm installed. (Downloading and installing Node.js and npm | npm Docs (npmjs.com))
• An existing Extension you want to test. (How to create an Extension)
• Docker Desktop installed. (Software Requirements for the Extension Test Studio)

Setup your Tests

To write tests you first need to setup your local environment:

1. Inside your Configuration Project you want to create the following folder structure:
   
   Config\Files\Tests
    
2. Use npm to create a package.json inside the Tests folder.

   > npm init
   

3. Install testcafe as a development dependency using npm.

   > npm i -D testcafe

4. Optionally install the test runtime for common logic and utilities.

   > npm i @matrix42/extensions-test-runtime
   

Writing your first Test

In the following you will find an example test file which includes one test to verify the existance of the "Home" navigation item in the Self Service Portal.

You can read more about how to write tests using testcafe here.

import { Selector } from 'testcafe'
import * as runtime from '@matrix42/extensions-test-runtime'

fixture`Example Tests`.beforeEach(async (t) => {
  // this call ensures that there is a valid access token for the current test session
  await runtime.ensureSessionToken()
})

test('Home button exists in Self Service Portal', async (t) => {
  // navigate to the Self Service Portal
  await t.navigateTo(`https://${runtime.executionContext.dwpHost}/wm/app-SelfServicePortal`)
  
  // get the text value of home navigation item
  const result = await Selector('.mx-shell-nav-item__item-text.mx-nav-item--auto-home2').innerText
  
  // expect the text value to be "Home"
  await t.expect(result).eql('Home')
})

Running your Tests locally

To run your tests locally and see if they succeed you can use the Matrix42 Command-Line Interface (CLI).

1. Install the CLI using npm.

   > npm i -g @matrix42/cli
   

2. Navigate to your Tests folder and run the CLI.

   > m42 run-extension-tests .\*.test.js -h <host> -t <token> [-b <browsers>] [-o <output>] [-s] [-l]

host: The hostname of the DWP Environment you want to run the tests against.

token: The API token of the DWP principal you want to run the tests with.

browsers: A comma seperated list of browsers you want to run the tests on.

output: The output path where the test reports are saved.

s: If specified screenshots will be recorded on failure of a test and saved to in the /screenshots folder in the output path.

l: If specified the tests will not run in docker containers but rather on the executing machine.

You can now see the results of your tests in the console or you can inspect the *_report.json files in the output path.

> m42 run-extension-tests ... -b chrome:95,firefox,edge:96

> 1%
last 2 versions
not dead

Prepare the Test Studio for your Tests in the DWP

To run your tests on a DWP Server and see if they succeed you can install the Matrix42 Extension Test Studio via the Matrix42 Extension Gallery.

The Test Studio needs a valid API Token for the environment to login for the Test Runs.
Write the valid API Token to a new config.json File:

{
  "ApiToken": "<token>"
}

and place this file on the DWP Server at

"Matrix42 Workplace Management\ExtensionTestStudio\config.json"

The Extension Test Studio is now ready to execute your Tests on the DWP.

How to package Tests into an Extension

To run your tests on a DWP Server your Extension Tests need to be stored on the DWP. There are 2 ways how you can create an installable Extension package:

param (
    [string] $basePackagePath,
    [string] $buildId
)

if(Test-Path -Path "$basePackagePath\package.json"){
    #read required information from extension package.json
    $content = Get-Content -Raw -Path "$basePackagePath\package.json" | ConvertFrom-Json
    $packageID = $content.ID
    $version = $content.Version

    #if given a build-Id which will also be added to the version in the later pipeline steps, we also need to add it to the version folder name
    if($buildId){
        $version+=".$buildId"
    }

    #if there is a packageID-directory already, we want to delete it, because the package should only contain the current test files
    $packageFolder = "$basePackagePath\Config\Files\Extensions\${packageID}"
    if(Test-Path -Path $packageFolder){
        Remove-Item $packageFolder -Force -Recurse
    }

    #create the necessary directory structure
    $testsFolder = "$packageFolder\${version}\Tests"
    New-Item -Path $testsFolder -ItemType Directory

    #copy all test files and then remove tests folder, so it won't be stored on the server twice  
    Copy-Item -Path "$basePackagePath\Config\Files\Tests\*" -Destination "$testsFolder" -Recurse
    Remove-Item "$basePackagePath\Config\Files\Tests" -Force -Recurse
}

steps:
- task: PowerShell@2
  displayName: 'Create Tests Folder for installation'
  inputs:
    targetType: filePath
    filePath: ./scripts/createTestsFolderStructure.ps1
    arguments: '-basePackagePath "BasePackage" -buildId $(Build.BuildId)'