CI/CD configure

Definition

This document describes the guidelines to use the CI/CD API of MTA in a pipeline.

Configuration

Create CI/CD user

In order to prepare MTA for integration with your CI/CD pipeline you need to create a user in MTA with only the Testautomator and CiCdApiUser roles.

• First, login as an MTA Manager. Do not login with an account that has Administrator rights!
• Navigate to MTA management and then to MTA Users. Create a New local MTA user.
• Then, fill in the form like this:

This is the username and password you will connect with to the API.

• Save and logout.
• Then, login with the CI/CD user, click the user icon on the top right and fill in the API key and PAT.
• Finally, if you also want MTA to push CI/CD testrun results to your own API endpoint, enter the Endpoint and Secret key.
  Read more about it on the CI/CD result handling page.

Enable CI/CD

Where regular test runs are executed on the Test Configuration level, CI/CD enabled test runs are executed on the Application level. When testing an Application, all Test Configurations that use that Application, and are CI/CD enabled are executed. Keep in mind, that also other Test Applications could be affected, if one of those Test Configurations use more than one.

If you want to include a Test configuration in testing, you need to enable it by editing it from the Test design page.

• Edit the Test Configuration that you want to execute and set "CI/CD enabled" to TRUE.
• Now open the Test Settings for the Test Configuration and set a Test Setting as My Preference.

Check App status

The CI/CD API can be used in a pipeline that performs deployments of a Mendix Application. But the CI/CD API does not check if the deployment is done.

info

Before executing a CI/CD testrun, check that the deployment is completed and the status of the Application Instance is "Running".

Execute a testrun from CI/CD

The base URL for the CI/CD API is:

{your mta node}/rest/cicdservice/v1/CiCd/

The CI/CD API knows two REST requests.

1. POST testruns
   This request executes a new CI/CD testrun
2. GET testrunsresult
   This request returns the result for a previously executed CI/CD testrun

The contents of these requests are described next.

POST testruns

Executes a new CI/CD testrun asynchronously and immediately returns an ExecutionId that can be used to poll for results.

To use this request you need a Project ID for your Mendix App. You can find this by navigating to Applications and clicking on the icon for the respective app.

info

As of MTA version 2.0, MTA will no longer detect and download a matching revision from Teamserver. Therefore it is advisable to always download the revision in the MTA frontend, before the CI/CD run starts.

URL

/rest/cicdservice/v1/CiCd/testruns

Example: https://mta-menditect-9fo2p.mendixcloud.com/rest/cicdservice/v1/CiCd/testruns

Authorization

Authorization	Basic
Username:	[the CiCd username in MTA]
Password:	[the CiCd password in MTA]

Input body

Parameter
ProjectId	[the Mendix project ID for the Mendix App you want to execute]

Example:

{
   "ProjectId":"48224593-2187-448d-abe9-9202e1b3a870"
}

info

As of MTA version 2.0, you only have to provide the Project ID. MTA will determine which Application Instance to execute on, by the Test Setting that is set as Preferred by the provided CI/CD user.

Output (if http response = 200/OK)

Parameter
ExecutionId	[an ID that is generated by MTA to uniquely identify the test run]

Example: {"ExecutionId":"ddf0954e-b5df-40cd-879a-eeaa74a19013"}

GET testrunsresult

info

As of MTA version 2.0, this request will also show detailed information and not just whether the run has passed or failed.

After a CiCd execute, use this request to poll MTA to check if the testrun is finished.

This request returns the result for a previously executed CI/CD testrun, in a JSON format.

URL

/rest/cicdservice/v1/CiCd/testrunsresult

Example: https://mta-menditect-9fo2p.mendixcloud.com/rest/cicdservice/v1/CiCd/testrunsresult

Authorization

Authorization	Basic
Username:	[the CiCd username in MTA]
Password:	[the CiCd password in MTA]

Input parameters

Parameter
ExecutionId	[the Execution ID for a previously created CiCd testrun]

Example: https://mta-menditect-9fo2p.mendixcloud.com/rest/cicdservice/v1/CiCd/testrunsresult?ExecutionId=ddf0954e-b5df-40cd-879a-eeaa74a19013

Output (if http response = 200/OK)

Parameter
Result	{} if the test is still running, otherwise a JSON containing results]

Example:

{
    "ExecutionId": "53138dae-3f52-462a-8c29-03868fedca9a",
    "Result": "Pass",
    "TestRunResults": [{
            "TestConfigurationName": "Test",
            "TestRunResult": "Pass",
            "TestRunUrl": "http://mta-menditect-9fo2p.mendixcloud.com/link/testrun/3",
            "TestSuiteRunResults": [{
                    "TestSuiteSequence": 1,
                    "TestSuiteName": "Test",
                    "TestSuiteRunResult": "Pass",
                    "TestsuiteRunUrl": "http://mta-menditect-9fo2p.mendixcloud.com/link/testsuiterun/3",
                    "TestCaseRunResults": [{
                            "TestCaseSequence": 1,
                            "TestCaseName": "Test",
                            "TestCaseRunResult": "Pass",
                            "TestCaseRunResultMessage": "",
                            "TestCaseRunUrl": "http://mta-menditect-9fo2p.mendixcloud.com/link/testcaserun/3"
                        }
                    ]
                }
            ]
        }
    ]
}

Powershell script

It is possible to invoke the CI/CD REST service via a Powershell script in Windows if you have local Administrative privileges.
That script looks like this:

# --------------- Configuration ------------------
#
# ALTER PARAMETERS BELOW FOR YOUR CI/CD CONFIGURATION

$TestAppProjectId = "yourprojectidhere"
$MtaUrl = "yourmtaurlhere"
$MtaCiCdUser = "yourusernamehere"
$MtaCiCdUserPassword = "yourpasswordhere$"

#  --------------- Script ---------------
#
# DO NOT ALTER CODE BELOW

$Body = @{
    ProjectId = $TestAppProjectId
}
 
$Parameters = @{
    Method = "POST"
    Uri =  $MtaUrl + "/rest/cicdservice/v1/CiCd/testruns"
    Body = ($Body | ConvertTo-Json)
    ContentType = "application/json"
}

$Pass = ConvertTo-SecureString $MtaCiCdUserPassword -AsPlainText -Force

$Cred = New-Object System.Management.Automation.PSCredential ($MtaCiCdUser, $Pass)

Invoke-RestMethod @Parameters -Credential $Cred

To use above script:

1. open Notepad or another text exitor
2. copy above script with the copy button on the top right, and paste it into the text editor
3. replace the 4 parameters with your own settings
4. save the file as cicd.ps1
5. open Windows Powershell to the folder that you saved the file to
6. execute the file using this command powershell -ExecutionPolicy Bypass -File cicd.ps1

Cleanup testruns

Currently, every night a scheduled event cleans CI/CD test runs. MTA only keeps CI/CD test runs associated with the last two executions for a single Application.

Troubleshooting

• Problem: I have configured everything but the CI/CD run does not execute or raises an error message.
• Solution: make sure that the Test Application Instance is running and that the provided CI/CD user credentials are correct. Also make sure that the CI/CD user has both roles as desribed (CI/CD user and TestAutomator).

• Problem: the CI/CD run executes with an ExecutionID, but also raises an error message.
• Solution: make sure that all the Test Configurations that are CI/CD enabled for the ProjectID that is passed, have a Prefered Test Setting, and also make sure that there is at least one Test Configuration with CI/CD enabled=TRUE.

Feedback?

Missing anything? Let us know!

Last updated 9 december 2022