{"id":11275,"date":"2024-03-15T07:58:20","date_gmt":"2024-03-15T07:58:20","guid":{"rendered":"https:\/\/www.anamata.nl\/?p=11275"},"modified":"2024-05-29T09:53:42","modified_gmt":"2024-05-29T09:53:42","slug":"exploring-the-mendix-client-api-for-testing","status":"publish","type":"post","link":"https:\/\/www.anamata.eu\/nl\/11275\/","title":{"rendered":"Exploring the Mendix Client API for Testing"},"content":{"rendered":"
<\/div>
\n
<\/div><\/div>\n<\/div><\/div><\/div>\n\n\n\n
Introductie<\/strong><\/h5><\/div><\/div><\/div>\n\n\n\n

When testing applications, I always want to know more about the technology used in the application stack. I strongly believe that having knowledge of the technology used ‘under the hood’ can greatly contribute to more efficient testing. <\/p>\n\n\n\n

When it comes to low-code applications like Mendix, knowing what happens below the surface is at least as interesting for testers. The created applications may look different and have different functionalities, they do share common interfaces and functionalities under that hood. Knowing these interfaces and functionalities as a tester, can help in increasing the test efficiency and team collaboration.<\/p>\n\n\n\n

<\/div><\/div><\/div>\n\n\n\n
The Client API<\/strong><\/h5><\/div><\/div><\/div>\n\n\n\n

In October last year, I was part of a team of Anamateers during the Mendix hackathon, aka P0wn Party. Besides the great experience and challenging puzzles, it also triggered my curiosity around the Client API<\/a>. This JavaScript API forms the basis for communications between frontend (browser) and backend (microflows, database objects). During the hackathon, I learned how this API could be used to create objects and trigger microflows from the browser console. This got me thinking: if triggering microflows through the console is so easy, how easy is it to incorporate this functionality into a test automation framework and use it for testing purposes?<\/p>\n\n\n\n

In this article, I will not go into the exact operation of the APIs – there is a lot of information on this on the Mendix (community) websites -. Instead, I will share my learning process for incorporating Client API calls into an automation framework for the purpose of testing.<\/p>\n\n\n\n

Playwright<\/strong><\/h5><\/div><\/div><\/div>\n\n\n\n

At first, I had to decide which tool I would use for my framework. I wanted to use a tool that supported the JavaScript language, was open-source and can be used to create extensive test automation frameworks.<\/p>\n\n\n\n

Based on these requirements, I chose to go for Playwright<\/a>. I had never used Playwright before and my knowledge of Javascript was also limited. So, this was an opportunity for me to learn a lot of new things!<\/p>\n\n\n\n

The Demo app<\/strong><\/h5><\/div><\/div><\/div>\n\n\n\n

To check whether I was able to add the Client API calls to the framework, I first needed to create an app. Wanting to control the ability to create objects and associations and execute microflows, I created a simple app in Mendix with only these functionalities.<\/p>\n\n\n\n

\"\"
My App and the corresponding data model<\/figcaption><\/figure>\n\n\n\n
Creating an Object<\/strong><\/h5><\/div><\/div><\/div>\n\n\n\n

To create an object via the Client API, a couple of things need to be considered.<\/p>\n\n\n\n

    \n
  1. The caller needs to have write access to the object<\/li>\n\n\n\n
  2. To be able to call the API, you need to have an active -logged in – browser session.<\/li>\n<\/ol>\n\n\n\n

    So to use this functionality, you must first be logged into the application with an appropriate user. With an active user session, you can trigger the mx.data.create<\/a> functionality to create an object.<\/p>\n\n\n\n

    As a first step, I logged in as an Admin user and ran the following JavaScript snippet manually in my JavaScript console:<\/p>\n\n\n\n

    mx.data.create({\n    entity: \"MyFirstModule.Person\",\n    callback: function(mxObject) {\n        mxObject.set(\"FirstName\", 'test');\n        mx.data.commit({\n            mxobj: mxObject,\n            callback: () => {}\n        })\n    }\n})<\/code><\/pre>\n\n\n\n
    As a result, a new person with FirstName = test<\/em> was created in the app. The next step was to add the same functionality in the Playwright framework.<\/p>\n\n\n\n
    Integrating object creation in the automation framework<\/strong><\/h5><\/div><\/div><\/div>\n\n\n\n
    When running a Playwright test, the scripts run in its own ‘Playwright environment’ and triggers actions on a page of the target application. The Client API runs in the target application. These environments remain distinct; they operate in separate virtual machines, processes, and potentially even on different computers. So, to run a JavaScript command in the context of a target application, we need to trigger an action in Playright which executes JavaScript on the target page.<\/p>\n\n\n\n
    PlayWright has the function page.evaluate<\/a> <\/strong>to do exactly that: run JavaScript in the context of the web page.<\/p>\n\n\n\n
    So, to be able to create a person object via Playwright, I created the following code in Playwright (note that the login steps are not included in the test; these steps are placed in the Before hook<\/em><\/a>).<\/p>\n\n\n\n
    await page.evaluate(() => {\n  mx.data.create(\n  {\n    entity: \"MyFirstModule.Person\",\n    callback: function(mxObject)\n    {\n      mxObject.set(\"FirstName\", '1');\n      mx.data.commit(\n      {\n        mxobj: mxObject,\n        callback: () => {}\n      })\n    }\n  })\n})<\/code><\/pre>\n\n\n\n
    This created a person object in the database.<\/p>\n\n\n\n
    The next step for me, was to check if it would be possible to create a generic funcion for the creation of a database object. So, instead of defining the entity and attributes inside the evaluate function, add them as input variables.<\/p>\n\n\n\n
    First, I created a JavaScript Object for person (note that the naming of the keys is identical to the attribute names in the domain model):<\/p>\n\n\n\n
    const person = { FirstName: 'test1', LastName: 'testbas1', BirthDate: new Date('2000-01-01'), Gender: 'Male' };<\/code><\/pre>\n\n\n\n
    In the end, I added theModule name (moduleName<\/strong>), Entity name (objectName<\/strong>) and the content<\/strong> above as input parameter for the evaluate-function. This way, I was able to create a generic function for creating an object, where the input parameter content represents the JavaScript object as above:<\/p>\n\n\n\n
    await page.evaluate(({ moduleName, objectName, content }) => {\n   var entityName = moduleName + \".\" + objectName;\n   mx.data.create(\n     {\n         entity: entityName,\n         callback: function (mxObject) {\n             for (let i = 0; i < Object.keys(content).length; i++) {\n                 const key = (Object.keys(content)[i]);\n                 const value = (Object.values(content)[i]);\n                 mxObject.set(key, value);\n             }\n             const guid = mx.session.sessionData.user.guid;\n             mx.data.commit(\n                 {\n                     mxobj: mxObject, guids: [guid],\n                     callback: () => { }\n                 })\n         }\n     })\n}, ({ moduleName, objectName, content }))<\/code><\/pre>\n\n\n\n
    Since the keys in the content object are equal to the attribute names, I was able to update all values with a simple loop.<\/p>\n\n\n\n
    Adding an association<\/strong><\/h5><\/div><\/div><\/div>\n\n\n\n
    My next step was to figure out how to add an association in a generic way. As shown in the domain model above, the goal was to create an association from person to address.<\/p>\n\n\n\n
    As the association points from person to address, the attribute should be stored on the person object. When the association is created via a microflow, we can see the following:<\/p>\n\n\n\n
    \"\"
    Change Person object: add association to address<\/figcaption><\/figure>\n\n\n\n
    My strategy for the steps in framework was the following:<\/p>\n\n\n\n
      \n
    1. Create Person object<\/li>\n\n\n\n
    2. Create Address object<\/li>\n\n\n\n
    3. Change Person object: add association<\/li>\n<\/ol>\n\n\n\n
      This way, I was able to re-use the previously described Create Object<\/em> functionality for the first two steps and create only one new function for the association.<\/p>\n\n\n\n
      This association function consisted out of 3 steps itself:<\/p>\n\n\n\n
        \n
      1. Find ID of address object<\/li>\n\n\n\n
      2. Find Person object<\/li>\n\n\n\n
      3. Change person object with addressID<\/li>\n<\/ol>\n\n\n\n
        It took me a while to figure this out, mainly because I was struggling with the asynchronous behavior of the mx.data functionalities. The only way I was able to solve it, was to add the subsequent function in the callback of the previous one. Eventually, I was able to create the following:<\/p>\n\n\n\n
        await page.evaluate((\n{\n  associationKey,\n  xpathExpressionOriginalObject,\n  xpathExpressionAssociatedObject\n}) =>\n{\n  mx.data.get(\n  {\n    xpath: xpathExpressionOriginalObject,\n    callback: function(OriginalObjects)\n    {\n      if (OriginalObjects.length > 0)\n      {\n        var OriginalObject = OriginalObjects[0];\n      }\n      mx.data.get(\n      {\n        xpath: xpathExpressionAssociatedObject,\n        callback: function(associationObjects)\n        {\n          if (associationObjects.length > 0)\n          {\n            OriginalObject.set(associationKey,  \n               associationObjects[0]._guid);\n          }\n          const guid = mx.session.sessionData.user.guid;\n          mx.data.commit(\n          {\n            mxobj: OriginalObject,\n            guids: [guid],\n            callback: () => { }\n          })\n\n        }\n      })\n    }\n  })\n}, (\n{\n  associationKey,\n  xpathExpressionOriginalObject,\n  xpathExpressionAssociatedObject\n}))<\/code><\/pre>\n\n\n\n
        Where the input parameters are defined as follows:<\/p>\n\n\n\n