Chapter 2 uses %UnitTest for unit tests

The second part of this tutorial shows you how to UnitTest InterSystems IRIS code using the %UnitTest package. After completing this part of the tutorial, you will be able to:

  • explain%UnitTestThe roles of the three main classes in the package.
  • Based on the listed%UnitTestPackage unit test class and method requirements.
  • Create and execute unit tests for methods.
  • browse%UnitTest.ManagerTest reports created.
  • When executing unit tests, use%UnitTest.TestCaseMethod to initialize and restore database data.

What is %UnitTest?

The %UnitTest package is a set of classes that provide a testing framework for IRIS. In structure, it is similar to the xUnit testing framework. %UnitTest provides classes and tools for creating and executing unit tests that:

  • Classes and methods
  • ObjectScript routines (routines)
  • InterSystems SQL script
  • Productions

Create and execute unit test suites

Here are the basic steps to create and execute a suite of unit tests:

  1. Create a class (or classes) that contains the methods to be tested.
  2. Create an extension%UnitTest.TestCaseTest classes (or more test classes) of
  3. Adds a method to the test class that will output the test method. Use at least one assertion in each method (AssertXMacro). Each test method name starts withTestAt the beginning.
  4. Export the test class to a file.
  5. Open the terminal and switch to the namespace containing the class to be tested. for^UnitTestRootAllocates a string containing the path to the parent directory of the directory containing the exported test class file.
  6. In the terminal, run%UnitTest.Manager.RunTestPass it the name of the (child) directory that contains the test class files.
  7. View the test report. The output in the terminal includes the URL of a web page that displays the results in an easy-to-read table.

% UnitTest class

This table describes the main %UnitTest classes used to create and execute unit tests for InterSystems IRIS classes and methods.

  • TestCaseExtend this class to create classes that contain test methods. If one or moreAssertXMethod returnsFalse, the test fails. Otherwise, the test passes. Will be invoked using the associated macroAssertXMethods. These methods and macros are:
    • AssertEqualsViaMacro– Returns if expressions are equalTRUE. use$$$AssertEqualsMacro calls.
    • AssertNotEqualsViaMacro– Returns if the expression is not equalTRUE. use$$$AssertNotEqualsMacro calls.
    • AssertStatusOKViaMacro– Returns if the returned status code is 1TRUE. use$$$AssertStatusOKMacro calls.
    • AssertStatusNotOKViaMacro– If the returned status code is 0, the value is returnedTRUE. use$$$AssertStatusNotOKMacro calls.
    • AssertTrueViaMacro– Returns TRUE if the expression is TRUE. use$$$AssertTrueMacro calls.
    • AssertNotTrueViaMacro– Returns if the expression is not TRUETRUE. use$$$AssertNotTrueMacro calls.
    • AssertFilesSameViaMacro– Returns if the two files are the sameTRUE. use$$$AssertFilesSameMacro calls.
    • LogMessage– Writes log messages^UnitTestLogThe global. use$$$LogMessageMacro calls.
    • Methods for setting and removing conditions include:
    • OnBeforeOneTest– Executed immediately before each test method in the test class.
    • OnBeforeAllTests– Executes once before any test method in the test class.
    • OnAfterOneTest– Executes immediately after each test method in the test class.
    • OnAfterAllTests– Executes once after all test methods in the test class have been executed.
  • ManagerUse this class to start tests. Its methods include:
    • RunTest– Executes a test or group of tests in a directory.
    • DebugRunTestCase– Executes a test or group of tests without loading or deleting any test classes.
  • ReportDefines a web page that reports the results of executing a test or set of tests.

Assert methods and macros

The main test operations for unit tests come from the AssertX method and its associated macros. The macro is called directly to test the output of the method. Macros test whether a method creates the desired output for a given input. As long as the AssertX macro returns FALSE(or ends with an error), the test that contains it will fail.

When you create code, plan the unit tests you will create to test your code. In the example here, a class named TestMe has been created that contains a method named Add. Now you want to test your new TestMe class to see if it works.

The following command runs the AssertEquals macro to test whether the input to the Add method (2,2) is equal to 4.

 Do $$$AssertEquals(##class(MyPackage.TestMe).Add(2, 2), 4,"Test Add(2, 2)=4")
Copy the code

The AssertEquals macro compares two values and accepts three arguments:

  1. # # class (MyPackage. TestMe). The Add (2, 2)– The first value is2, 2A method of testing as input.
  2. 4– Second value.
  3. "Test the Add (2, 2) = 4"– Text instructions written on the results page. (This parameter does not affect testing. If no test description is included, the class creates a test description using the evaluated expression.

The following is an example of the AssertStatusOK macro used to test whether an object is saved correctly.

 Do $$$AssertStatusOK(contact.%Save(),"Saving a Contact")
Copy the code

This AssertStatusOk macro calculates the state returned by the method. If it is 1, the test passes.

  1. Contact.%Save– Returns an expression for the status code.
  2. "Saving a Contact"– Text description. This is the documentation of the test report. This will not affect the test.

Create the class to use in the example

To complete the following hands-on example, use Atelier to create the following classes: mypackage.testme and mypackage.Contact.

  • MyPackage.TestMe
Class MyPackage.TestMe Extends %RegisteredObject
{

ClassMethod Add(arg1 As %Integer, arg2 As %Integer) As %Integer
{

    Return arg1 + arg2
}

ClassMethod CreateContact(name As %String, type As %String) As MyPackage.Contact
{

    Set contact = ##class(MyPackage.Contact%).New(a)Set contact.Name=name
    Set contact.ContactType=type
    Return contact
}

ClassMethod GetContactsByType(type As %String) As %ListOfObjects
{

    Set list=##class(%Library.ResultSet%).New()}}Copy the code
  • MyPackage.Contact
Class MyPackage.Contact Extends (%Persistent, %Populate, %XML.Adaptor)
{

/// Describe the nature of the contact: : Personal or Business
Property ContactType As %String(TRUNCATE = 1, VALUELIST = ",Business,Personal");

/// Indicates the contact name
Property Name As %String(POPSPEC = "Name()", TRUNCATE = 1) [ Required ];

Query ByContactType(type As %String) As %SQLQuery(CONTAINID = 1)
{
    SELECT %ID FROM Contact
    WHERE (ContactType = :type)
    ORDER BY Name
}

Storage Default
{
<Data name="ContactDefaultData">
<Value name="1">
<Value>%%CLASSNAME</Value>
</Value>
<Value name="2">
<Value>ContactType</Value>
</Value>
<Value name="3">
<Value>Name</Value>
</Value>
</Data>
<DataLocation>^MyPackage.ContactD</DataLocation>
<DefaultData>ContactDefaultData</DefaultData>
<IdLocation>^MyPackage.ContactD</IdLocation>
<IndexLocation>^MyPackage.ContactI</IndexLocation>
<StreamLocation>^MyPackage.ContactS</StreamLocation>
<Type>%Storage.Persistent</Type>
}

}

Copy the code

Example: Create and export a test class

The class mypackage.testme contains a method called Add that adds two integers. In this example, unit tests are created and run to check that the Add method correctly adds two integers.

Create the test class that will contain the unit tests. Here’s how:

  1. Use the Atelier inMyPackageCreate a package namedTestsA new class. Tests must be extended%UnitTest.TestCase.
  2. Add the following nameTestAddAnd compile the test method:
Class MyPackage.Tests Extends %UnitTest.TestCase
{

Method TestAdd(a)
{
 do $$$AssertEquals(##class(MyPackage.TestMe).Add(2, 2), 4,"Test Add(2, 2)=4") do $$$AssertNotEquals (# # class (MyPackage. TestMe). The Add (2, 2), 5,"Test Add(2.2)'=5")}}Copy the code
  1. Export the class tests to an XML file in the unit tests directory. If you have not already created a test directory, create one. This example uses’ C: unittests\mytests\.

A. In Atelier, choose File > Export.

B. Under Atelier, click Old XML File. Click Next

C. Select project test. CLS and c: unittests\mytests\ directory.

D. Click Finish.

E. Atelier export the test class to C:\ UnitTests \ myTests \ CLS \MyPackage

Note that the directory name (mytest in this case) is the name of a set of tests and a child of the directory specified by ^UnitTestRoot. Run manager.runtest (” mytest “) to run all tests stored in the mytest directory.

Note: You can also export test classes as.clS files instead of XML files. You can also simply copy them from your Atelier workspace instead of exporting them.

The source code