AcumatiCares
Introduction
Being part of the Acumatica MVP Developer group, there has been some valuable information shared amongst the group. There has been a lot of discussion around unit testing customizations on the Acumatica platform and the REST API. Building out testing frameworks on solutions requires a discipline that is needed to build successful solutions. In this post, I will be discussing how I leverage unit testing with REST API calls where I need to give the user feedback on errors.
One valuable tool mentioned by our Acumatica MVP Developer peers was the use of XUnit as being a valuable open source unit testing tool for the .NET Framework within Visual Studio.
Xunit
Xunit has allowed us to confidently test smaller fragments of code that is the critical path in our integrations and improve efficiency in delivering these solutions in a more reliable time frame. Once the XUnit project has been created, it is valuable to use when troubleshooting those same sections of code. To start using the project, you can find it in the template section of your Visual Studio environment. Once the project is created, be sure to reference the library you need to test in your Unit Test project.
As I began using the unit testing tool, I was relying on adding all my credentials to an appSettings.json file with connections to various clients. Ideally, you don’t want to save this information in this file and strongly recommend moving it to a User Secrets file. Visual Studio now makes this fairly easy by simply right clicking on the project to access this. The user secrets file remains on your local development environment and does not get pushed up to your local Github (or equivalent) repository.
For each unit class you create, be sure to make the connection in the constructor of the class to avoid creating a new connection for each unit test. Also note the use of user secrets in the configuration object. Be sure to include the Microsoft.Extensions.Configuration.UserSecrets NuGet package along with Microsoft.Extensions.Configuration and related packages to take advantage of this feature.
GIST: https://gist.github.com/kulvirTAC/c1c64f4dde29f20f3f0c0d465f5d2184
When implementing API solutions, error handling becomes a key factor in helping our end users know when integrations break down. Faulty error handling or lack of information can cause a lot of unnecessary time spent on troubleshooting. One test in our Unit Testing project is to see if an inventory item is missing from Acumatica. The small snippet of code outlines the test.
GIST: https://gist.github.com/kulvirTAC/b5b9b5a11a46930f5a158e24245870f8
The returning error from this code via Acumatica’s REST API shows the following. For clarity, I removed the blank or non-relevant fields from the payload. At the top level, the error message states the Unit conversion is missing. This is a misleading error statement and we’ll need to traverse through the rest of the code to find the details behind this error.
GIST: https://gist.github.com/kulvirTAC/005cd15ecb8042efa2b79105497ffe15
At the detail level, we find the following error tags in the JSON payload. Again the data is stripped down to the relevant parts only:
GIST: https://gist.github.com/kulvirTAC/efe804d350959683085961d6918296ba
As we collect the error tags in the payload, we can then return a more informative message for our clients:
Unit conversion is missing.; Unit conversion is missing. Details.InventoryID: 'Inventory ID' cannot be empty. Details.UOM: 'UOM' cannot be empty.
If there are multiple lines in the orders, we’ll need to decipher which inventory ID was indeed missing. Acumatica REST API does a good job returning the complete order data where the remaining lines are shown in a valid format. This is just one example of how you can leverage the unit testing tools in the marketplace with your Acumatica customizations.
Summary
Adding unit tests to your solutions allows you to troubleshoot situations a lot faster than trying to reproduce all the intermediary steps when you run the full project. Any updates to the code allow you to regression test the baseline functionality. In some cases, a test driven development approach can be taken to further improve the code quality. I particularly find it useful when I need to improve the error handling for integration projects.
Happy Coding!
