Chapter 1: X++ Unit Test Framework

CHAPTER 1: X++ UNIT TEST FRAMEWORK

Objectives
The objectives are:

• Create a test case.

• Add methods to a test case.
• Run a test case.
• Build a test project and suite.
• Isolate test cases appropriately.

Introduction
The X++ Unit Test framework allows for unit tests to be created along with the
code they are designed to test.

A unit test is code that verifies that some specific application code has been
implemented correctly. If you adhere to the principles of test-driven
development, it is best for the developer who is writing the application code to
write the unit tests either before or during development.

1-1
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Scenario
Isaac, the systems developer, is about to start a development project based on
some written specifications. Before he begins writing code, he has been asked to
create a Unit Test suite, to test the project during its lifecycle.

Creating Test Cases

A unit test, in the context of the Unit Test framework, includes test cases, how
test cases are staged with data, and the organization of test cases. A test case is a
class that extends the SysTestCase class. You can add test methods to test each
requirement of the feature code.

The following example is of how to create a test case. In this example you will be
testing an existing system class, so the results should be successful. You will test
the SysDictTable class, to make sure its methods to return the table name and
group for a given table name, are correct. The following is the test case class
declaration.

[SysTestTargetAttribute('SysDictTable',
UtilElementType::Class)]
class SysDictTableTest extends SysTestCase
{
SysDictTable sysDictTable;
}

Note the attribute used on the class. The SysTestTargetAttribute attribute is

attached to the test case to specify which element is being tested. In this case, it is
the SysDictTable class being tested. There are a number of predefined attributes
available in the Unit Test framework:

Attribute Description Applied to

SysTestMethodAttribute
SysTestCheckInAttribute
SysTestNonCheckInAttribute
Indicates that a method is Method
a unit test.
Indicates the test is a Method or Class
check-in unit test. A
check-in test is run when
checking in code to a
version control system to
ensure a proper level of
quality.
Indicates the test is not a Method
check-in test.

1-2
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 1: X++ Unit Test Framework

Attribute Description Applied to

SysTestTargetAttribute
SysTestInactiveTestAttribute
Indicates the application Class
object that is being tested
by the case. This attribute
takes two parameters:
Name of element, and
UtilElementType value.
Indicates the class or Method
method is inactive.

Another variable has been created in the ClassDeclaration, of the type of the class
being tested.

Adding Methods to Test Cases

The next step in creating a test case, is to add some methods to the test case class.
Each method should assert that one of the known requirements is true.

There are two new methods added in the following example: one to assert that
the table's name is as expected, and the other to assert that the table's group value
is as expected.

[SysTestMethodAttribute]
public void testTableName()
{
// Verify that the tables name is set correctly.
this.assertEquals("CustTable", sysDictTable.name());
}

[SysTestMethodAttribute]
public void testTableGroup()
{
// Verify that the tables group is set correctly.
this.assertEquals(TableGroup::Main,
sysDictTable.tableGroup());
}

A test method will typically contain several assertions that are required to hold
true, for the test to be successful.

Note the use of the assertEquals method. This method, and other assert methods,
are available as part of the SysTestCase framework. These methods also have an
optional string parameter called _message, to specify the message that would go
into the infolog, if the assertion fails. The following is a list of available methods:

Method Description
assertEquals Tests if two values are equal.
assertNotEqual Tests if two values are different.

1-3
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Method Description
assertTrue Tests if the value is true.
assertFalse Tests if the value is false.
assertNull Tests if the value is null.
assertNotNull Tests if the value is not null.
assertSame Tests if the objects referenced are the same.
assertNotSame Tests if the objects referenced are not the same.
assertRealEquals Tests if real values differ by the amount specified in
the delta.
assertExpectedInfolog Tests for an infolog message that is expected.
Message
fail Enables a developer to create custom validation
logic and then call the fail method to integrate with
the Unit Test framework.

Setup Method
The next step is to override the setUp method of the SysTestClass. This will tell
the Unit Test framework what parameters need to be setup before the test is run.
In this case, you need to instantiate the SysDictTable object using the table name.

public void setUp()

{
sysDictTable = new SysDictTable(TableNum(CustTable));
super();
}

The setUp method can also be used to insert or update any data necessary for the
test.

TearDown Method
At the completion of a test run, it may be necessary to "undo" any data created in
the setUp method. This can be done in the tearDown method, which is called at
the end of the test. The tearDown method can be overridden on any class
extending SysTestCase.

1-4
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 1: X++ Unit Test Framework

Running Test Cases

When the test class has methods added to it, and appropriate setUp and
tearDown methods, it can be run.

To run the test case, right click the SysDictTableTest class, click Add-Ins and
then Run tests. The Unit Test toolbar will appear, and the test case will be added
to the list of tests. The test will automatically be run, and the results displayed in
the toolbar, and in the infolog (if it failed).

FIGURE 1.1 UNIT TEST TOOLBAR

The SysDictTableTest test should pass on the first run. Try changing the
expected values in the test* methods, or the table id used in the setUp method, to
emulate a test that fails, then run the test again. To run the test again, click the
Run button on the Unit Test toolbar.

If the test fails, click the Details button to see more details of the results.

Reviewing Test Results

To review test results, the Test jobs form can be opened from the Tools menu
(Tools > Unit test > Test jobs).

The Test jobs form lists all previous runs of tests, and displays information about
the test.

FIGURE 1.2 TEST JOBS FORM

1-5
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Click the Tests button on the Test jobs form, to open another form where test
information is available at the method level.

FIGURE 1.3 TEST FORM SHOWS INFORMATION AT THE METHOD LEVEL

1-6
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 1: X++ Unit Test Framework

Listeners
Test results can be displayed in various formats, to suit the requirement. There
are several standard listeners that capture test results and format their results in
different ways. These can be configured on the Unit Test Parameters window,
as seen in the figure below.

FIGURE 1.4 LISTENER CONFIGURATION

Standard listeners include: Database, Infolog, Infolog (result only), Message

window, Print window, Progress bar, Text file, and XML file.

NOTE: It is also possible to create new listeners, by extending the

SysTestListener interface. This can be explored further on MSDN at this location
http://go.microsoft.com/fwlink/?LinkID=225151&clcid=0x409,by following the
"How to: Display Test Case Results" topic in the "Unit Test Framework" section.

Build Test Projects and Suites

Test classes can be organized in two ways:

• Test projects
• Test suites

Test Projects
Test projects are groupings of test classes and appear in the Development
Project tree along with other project types.

1-7
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Use the following procedure to create a new Test project:

1. Open the Project tree.

2. Right-click either the Private or Shared node, point to New, and
then click Test project. This creates a project with a test suite.
3. Open the AOT.
4. In the AOT, select one or more test classes to include in the test
project. Drag them to the TestSuite node in the Test project.

FIGURE 1.5 TEST PROJECT

Once test classes have been added to a Test project, the entire collection of tests
can be run at the same time, by right-clicking the root node of the project, and
clicking Run.

Test Suites
Collections of tests can also be created with X++ code. These collections extend
the SysTestSuite class, and are referred to as Suites.

Use the following procedure to create a test suite class:

1. In the AOT, create a new Class.

2. Open the new class in the Code Editor.
3. Edit the ClassDeclaration so that the class extends the SysTestSuite
class.
4. Override the new method on the class.
5. In the new method, call the add method to add test cases to the suite,
as shown.

public void new()

{
// Create an instance of a test suite.
SysTestSuite suiteDictTableTest = new
SysTestSuite(classstr(SysDictTableTest));
;
super();

1-8
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 1: X++ Unit Test Framework

this.add(suiteDictTableTest);
}

The setUp and tearDown methods can also be used in the scope of a Test Suite.
Both methods are available to override on any class extending the SysTestSuite
class. In this way, the setting up of data and variables can be done before the
entire suite of tests is run.

Isolation
The isolation level of a test case varies based on the changes that the test case
will make to the data. Each test case could have different needs for isolation
based on what data it will change. The Unit Test framework provides four test
suite base classes that provide different levels of isolation. The following table
describes the test suites by the level of isolation that they provide.

Test suite class Description

SysTestSuite Default test suite. No isolation.
SysTestSuiteCompanyIsolate Constructs an empty company account for
Class each test class. All test methods on the class
are run within the company, then it is
deleted.
SysTestSuiteCompanyIsolate Constructs an empty company account for
Method each test method, and then deletes it at the
end of the method.
SysTestSuiteTTS Wraps each test method in a transaction.
After the method is complete, the transaction
is aborted.
Note: Tests that need to commit data will not
work in this suite. Also, the
ParmExceptionExpected exception is not
supported in this suite.
SysTestSuiteCompIsolate This is a combination of
ClassWithTts SysTestSuiteCompanyIsolateClass and
SysTestSuiteTTS.

To apply a specific test suite to a test class, override the createSuite method on
the test class, and return an object of the type of the suite required.

1-9
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

The following example demonstrates how a test suite can be applied to a test
class.

class SysTestSuite createSuite()

{
// Isolation level: construct a company account for the
entire test class.
return new SysTestSuiteCompanyIsolateClass(this);
}

1-10
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 1: X++ Unit Test Framework

Lab 1.1 - Create a Test Case

During this lab, you will create a test case and add it to a test suite.

Scenario

Isaac is about to start a development project based on some written

specifications. Before he begins writing code, he has been asked to create a Unit
Test suite, to test the project during its lifecycle.

Challenge Yourself!
Create a test case class, and add a test method to it. The test case should check
that when an address record's Zip code is changed, the correct City is
automatically updated. Once complete, create a test suite class that enforces TTS
isolation, and link the test case class to it. Finally, run the test.

Step by Step

1. Open the AOT.

2. Create a new class.
3. Rename the class to MyTestSuite.
4. Edit the ClassDeclaration so that it extends the SysTestCase class,
and add a variable logisticsPostalAddress of type
LogisticsPostalAddress.
5. Add a public method called testCity.
6. Add a line of code to the method: this.assertEquals("New York",
logisticsPostalAddress.City);
7. Override the setUp method on the class. It should look like the
following code.

public void setUp()

{
ttsBegin;

select firstonly forupdate logisticsPostalAddress

where logisticsPostalAddress.City != "New York"
&& logisticsPostalAddress.CountryRegionId == "USA";

logisticsPostalAddress.validTimeStateUpdateMode(ValidTimeSt
ateUpdate::EffectiveBased);
logisticsPostalAddress.ZipCode = "10001";
logisticsPostalAddress.ZipCodeRecId = 0;

logisticsPostalAddress.LogisticsPostalAddressMap::modifiedF
ieldZipCode();

1-11
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

logisticsPostalAddress.update();

ttsCommit;

super();
}

8. Create a new class.

9. Name the class MyTestSuiteTTS.
10. Edit the ClassDeclaration so that it extends SysTestSuiteTTS.
11. Go back to the MyTestSuite class, and override its createSuite
method.
12. Change the method to read: return new MyTestSuiteTTS(this);
13. Run the test class.

1-12
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 1: X++ Unit Test Framework

Summary
This lesson explains how to use the Unit Test framework to test X++ code during
the development lifecycle.

The concepts of test cases, assertions, projects, suites and isolation are
introduced, demonstrating the rich features available to build robust logic tests.

1-13
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Test Your Knowledge

Test your knowledge with the following questions.

1. What class does a test class need to extend?

2. What is the setUp method on the SysTestCase class used for?

1-14
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 1: X++ Unit Test Framework

3. Where can the Test jobs form be opened from?

4. What is meant by "isolation" in the context of the Unit Test framework?

1-15
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

Quick Interaction: Lessons Learned

Take a moment and write down three key points you have learned from this
chapter

1.

2.

3.

1-16
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
 Chapter 1: X++ Unit Test Framework

Solutions
Test Your Knowledge
1. What class does a test class need to extend?

MODEL ANSWER:

SysTestCase

2. What is the setUp method on the SysTestCase class used for?

MODEL ANSWER:

It is used to prepare variables and data that are required for the test.

3. Where can the Test jobs form be opened from?

MODEL ANSWER:

Tools > Unit test > Test jobs.

4. What is meant by "isolation" in the context of the Unit Test framework?

MODEL ANSWER:

Isolation refers to the scope in which company data should be created and
destroyed during a test run.

1-17
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2012

1-18
Microsoft Official Training Materials for Microsoft Dynamics®
Your use of this content is subject to your current services agreement