BizTalk Server: Demystifying the Test Map operation in Visual Studio

Posted: January 7, 2014 in BizTalk
Tags: , , , , , ,

In the past I wrote a series of post on Basics principles of Maps where I stated that testing should be a continuous process as you build your map, not only at the end of development, but when necessary or when an important mapping block is complete.

And the good thing is that this feature is available to developers in an easy manner and directly from our favorite development tool – Visual Studio – without the need to build and deploy the maps or even create and configure ports and test them in runtime.

Note that Visual Studio allows you also to Validate and Debug maps at design time.

For this we need to:

  • Open the Solution Explorer windows
  • And execute the test by right-clicking the map name and selecting “Test Map” option
  • Verify the results in the Output window.

By default an instance of the input schema is generated automatically with dummy values, according to their type, and tested in the selected map. At the end, the generated result or the errors that occurred are displayed in the output window.


However this scenario provably is not the ideal one and what we want is to test the map with an existing and real message and not a dummy one. And the good news is that, again, BizTalk Mapper allows us to specify a source document.

In addition, it also supports instances as native (CSV, EDI …) or Extensible Markup Language (XML) as input or output according to the scenarios.

For this we only need to configure the properties of the map before we execute the test:

  • Right-clicking the map name and select Properties option;
  • In the Properties window set “TestMap Input Instance” property with the path to the input instance message file to be used while testing the map.


Other important properties that you can specify are:

  • TestMap Output Instance: Specifies the location where the Test Map should generate the output message.
  • TestMap Input: Specifies the format of the input instance message.
  • TestMap Output: Specifies the format for the output instance message.
  • Validate TestMap Input: Specifies whether you want to validate input instance messages against the source schema before you test the map.
  • Validate TestMap Output: Specifies whether you want to validate output instance messages against the destination schema after you test the map.

This last option, “Validate TestMap Output”, of the map properties is extremely important for the partial tests of maps. By setting this property as "False", allows us to test an incomplete map without being shown errors due lack of mandatory data, many of them associated with areas still to map.

This is nothing new, despite we often forget some of these properties. However I find myself constantly hear that, despite being easy to test one-to-one maps inside Visual Studio at design time, when we have multiple inputs to the map, many-to-one or many-to-many transformations, the same doesn’t happen, and it’s impossible to test this type of maps inside Visual Studio at design time because we only can specify an input message… and that it’s not true!

How can we test many-to-one or many-to-many maps inside Visual Studio?

Testing one-to-one maps is extremely simple and straightforward, however, many-to-one or many-to-many maps, despite being simple to test, it will required some additional steps.

First you have to understand that, Visual Studio doesn’t let us define multiple native instances in the “TestMap Input Instance” property, it only allows one instance message. But when a map has multiple source schemas, they are wrapped in a hierarchy multi-part message created by BizTalk.

So the only way for us to test this type of maps is to provide with an instance of the message in the “TestMap Input Instance” property that matched with the hierarchy multi-part message created by BizTalk.

The question here is how we can easily create an instance of multi-part message?

And the question is simple, by using the default behavior of the Test Map operation to make this work for us!

Let’s explain better, when we create a new map the “TestMap Input” and “TestMap Input Instance” proprieties are defined by default as: “Generate Instance” and “” (empty) respectively:


This means, as I explained earlier that if we test the map without changing this properties, one instance message will be generated automatically with dummy values. However in this scenarios, it will generate a dummy instance of the multi-part message expected by the map! AWESOME!

So what we need to do is:

  • Right-clicking the map name and selecting “Test Map” option
  • In the Output window the BizTalk Mapper will provide a link to the test’s output XML file and also to the input XML file.


  • Through the File Explorer, go to the directory folder specified folder in the Output window to have access to the dummy input file:
    • In this case: “C:\Users\Administrator\AppData\Local\Temp\1”
  • Copy the file to your project folder, in this case: “inputfile.xml”

This is a sample of this file:


As you can see, all the different input messages are there, with the write namespaces and so on… So what we need to do now is to:

  • Edit this file and put the User and Address messages that you want (you can do this easily with notepad)
  • And then specify the “TestMap Input Instance” property with this file.

As said earlier … we need some additional steps … but it is extremely easy to accomplish!

  1. jglisson73 says:

    Great tip…thanks!

  2. Ed Jones says:

    Reblogged this on Extremely Talented Monkeys and commented:
    Great article on map testing!

  3. Mireille1980@ says:

    How would you automate this scenario in continous integration? VS out of the box unit testing is not that helpful….The above works for a dev to validate the map for sanity check….

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s