Unit Testing IBM Websphere MQ with Fakes

.Net Projects that target the IBM Websphere MQ objects are often hard to unit test. Even with some amount of effort in isolating all the MQ objects through Dependency Injection and some tweaks around stubbing some of the common MQ classes, it’s easy to get into trouble with NullReferenceExceptions being thrown.

When targeting IBM MQ, there are two separate options: The native libraries (amqmdnet.dll) or the IBM.XMS library. I have found the JMS .Net implementation very problematic and hiding important queue options from the consuming classes, so I use mostly the native libraries and those are the focus of this post.

I won’t cover the basic principles of starting to use fakes, many people have covered that already and MSDN has a very nice series of articles on that. I will just highlight some common utility code and tricks I have learned along the way.

IBM MQ Design considerations

When I’m targeting IBM MQ, there’s a common set of design choices I make, and some of the code samples will reflect these options:

• I always browse messages first. Only after I have actually done what I need to do with the messages, I do a read on them.
• I use Rx right after the queues, this is why I always browse first. Once a message is browsed I push it through an IObservable, so that later I can do things like filter, sort, throttle, etc.
• I use System.Threading Timers to do pooling on the MQ queues. They do a very nice usage of threads and they also allow me to change the pooling frequency at run-time.
• Although I use several mocking frameworks, I tend to use only one per test class. On the test examples, everything will be going through Fakes, but I can easily argue that Fakes isn’t as mature as Moq or Rhino Mocks when it comes to fluent writing and API productivity.

IBM MQ id fields and properties

One common task around testing MQ objects is playing around with their Ids, either the object Id or other Ids like the correlation Id. These are always byte arrays and most times they are fixed size, so I wrote a nice utility method for creating fixed sized arrays:

	private static byte[] CreateByteArray(int size, byte b)
	{
	var array = new byte[size];
	for (var i = 0; i < array.Length; i++)
	{
	array[i] = b;
	}
	return array;
	}

view raw

gistfile1.cs

hosted with ❤ by GitHub

To assert the different Id fields just use CollectionAssert and use the ToList on both byte arrays.

CollectionAssert.AreEqual(messageId.ToList(), message.MessageId.ToList());

IBM MQ Shims tips and tricks

One of the problems you will see when you start using IBM.WMQ Shims is null references when instantiating some objects. This is easily fixed by overriding the constructors on the Shims:

ShimMQQueueManager.ConstructorStringHashtable = (_, __, ___) => { };
ShimMQMessage.ConstructorMQMessage = (_, __) => { };

Some of the objects in IBM.WMQ have a long inheritance chain. Shims don’t follow this, so for example, if you’re doing a Get on a queue with MQMessage and MQGetMessageOptions, this exists in MQDestination that MQQueue inherits from, so to be able to stub this method you need to write something like this:

ShimMQDestination.AllInstances.GetMQMessageMQGetMessageOptions = (_, message, options) =>
{
    Assert.AreEqual(MQC.MQGMO_NONE, options.Options);
    Assert.AreEqual(MQC.MQMO_MATCH_MSG_ID, options.MatchOptions);
    CollectionAssert.AreEqual(messageId.ToList(), message.MessageId.ToList());
};

Open Queue example with the corresponding tests

Here’s a full example of a method that Opens a Queue for reading and/or writing

	/// <summary>
	/// Opens this queue. Supports listening and writing options, if setup
	/// for listening it will do browse and not really reads from the queue
	/// as messages arrive to the queue.
	/// </summary>
	/// <param name="reading">True if we want to read from this queue, false otherwise.</param>
	/// <param name="writing">True if we want to write to this queue, false otherwise.</param>
	/// <returns>The Observable where all the messages read from this queue will appear.</returns>
	public IObservable<IServiceMessage> OpenConnection(bool reading = true, bool writing = false)
	{
	// create the properties HashTable
	var mqProperties = new Hashtable
	{
	{ MQC.TRANSPORT_PROPERTY, MQC.TRANSPORT_MQSERIES_MANAGED },
	{ MQC.HOST_NAME_PROPERTY, ConfigurationProvider.MQMessageListenerHostName },
	{ MQC.PORT_PROPERTY, ConfigurationProvider.MQMessageListenerPortNumeric },
	{ MQC.CHANNEL_PROPERTY, ConfigurationProvider.MQMessageListenerChannelName }
	};
	// create the queue manager
	_queueManager = new MQQueueManager(ConfigurationProvider.MQMessageListenerQueueManagerName, mqProperties);
	// deal with the queue open options
	var openOptions = MQC.MQOO_INPUT_AS_Q_DEF + MQC.MQOO_FAIL_IF_QUIESCING;
	if (reading)
	{
	openOptions += MQC.MQOO_BROWSE;
	}
	if (writing)
	{
	openOptions += MQC.MQOO_OUTPUT;
	}
	// create and start the queue, check for potential bad queue names
	try
	{
	Queue = _queueManager.AccessQueue(QueueName, openOptions);
	}
	catch (MQException ex)
	{
	if (ex.ReasonCode == 2085)
	{
	throw new ConfigurationErrorsException(string.Format(CultureInfo.InvariantCulture, "Wrong Queue name: {0}", QueueName));
	}
	throw;
	}
	if (reading)
	{
	StartListening();
	}
	return Stream.AsObservable();
	}

view raw

gistfile1.cs

hosted with ❤ by GitHub

And the unit tests that test it

	/// <summary>
	/// Tests that OpenConnection creates the proper MQQueueManager and accesses the
	/// queue with the right set of options.
	/// </summary>
	[TestMethod]
	public void Test_OpenConnection_GoesThrough()
	{
	const string host = "some random host";
	const string channel = "some random channel";
	const string manager = "some random manager";
	const string queueName = "some random queue";
	const int port = 1234;
	var startListeningCall = false;
	using (ShimsContext.Create())
	{
	var configShim = new ShimConfigurationProvider
	{
	MQMessageListenerChannelNameGet = () => channel,
	MQMessageListenerHostNameGet = () => host,
	MQMessageListenerPortNumericGet = () => port,
	MQMessageListenerQueueManagerNameGet = () => manager
	};
	ShimMQQueueManager.ConstructorStringHashtable = (_, s, options) =>
	{
	Assert.AreEqual(manager, s);
	Assert.AreEqual(host, options[MQC.HOST_NAME_PROPERTY]);
	Assert.AreEqual(channel, options[MQC.CHANNEL_PROPERTY]);
	Assert.AreEqual(port, options[MQC.PORT_PROPERTY]);
	Assert.AreEqual(MQC.TRANSPORT_MQSERIES_MANAGED, options[MQC.TRANSPORT_PROPERTY]);
	};
	ShimMQQueueManager.AllInstances.AccessQueueStringInt32 = (_, s, options) =>
	{
	Assert.AreEqual(MQC.MQOO_INPUT_AS_Q_DEF + MQC.MQOO_FAIL_IF_QUIESCING, options);
	Assert.AreEqual(queueName, s);
	return null;
	};
	var mqShim = new ShimMQMessageQueue
	{
	InstanceBehavior = ShimBehaviors.Fallthrough,
	ConfigurationProviderGet = () => configShim.Instance,
	QueueNameGet = () => queueName,
	StreamGet = () => new Subject<IServiceMessage>(),
	StartListening = () => { startListeningCall = true; }
	};
	mqShim.Instance.OpenConnection(false);
	Assert.IsFalse(startListeningCall);
	}
	}
	/// <summary>
	/// Tests the OpenConnection options in the queue access when the queue is setup to read.
	/// It also ensures that StartListening is called if the queue is opened for reading.
	/// </summary>
	[TestMethod]
	public void Test_OpenConnection_ForReading()
	{
	const string queueName = "some random queue";
	var startListeningCall = false;
	using (ShimsContext.Create())
	{
	ShimMQQueueManager.ConstructorStringHashtable = (_, __, ___) => { };
	ShimMQQueueManager.AllInstances.AccessQueueStringInt32 = (_, s, options) =>
	{
	Assert.AreEqual(MQC.MQOO_INPUT_AS_Q_DEF + MQC.MQOO_FAIL_IF_QUIESCING + MQC.MQOO_BROWSE, options);
	Assert.AreEqual(queueName, s);
	return null;
	};
	var mqShim = new ShimMQMessageQueue
	{
	InstanceBehavior = ShimBehaviors.Fallthrough,
	ConfigurationProviderGet = () => new ShimConfigurationProvider().Instance,
	QueueNameGet = () => queueName,
	StreamGet = () => new Subject<IServiceMessage>(),
	StartListening = () => { startListeningCall = true; }
	};
	mqShim.Instance.OpenConnection();
	Assert.IsTrue(startListeningCall);
	}
	}
	/// <summary>
	/// Tests the OpenConnection options in the queue access when the queue is setup to write.
	/// </summary>
	[TestMethod]
	public void Test_OpenConnection_ForWriting()
	{
	const string queueName = "some random queue";
	var startListeningCall = false;
	using (ShimsContext.Create())
	{
	ShimMQQueueManager.ConstructorStringHashtable = (_, __, ___) => { };
	ShimMQQueueManager.AllInstances.AccessQueueStringInt32 = (_, s, options) =>
	{
	Assert.AreEqual(MQC.MQOO_INPUT_AS_Q_DEF + MQC.MQOO_FAIL_IF_QUIESCING + MQC.MQOO_OUTPUT, options);
	Assert.AreEqual(queueName, s);
	return null;
	};
	var mqShim = new ShimMQMessageQueue
	{
	InstanceBehavior = ShimBehaviors.Fallthrough,
	ConfigurationProviderGet = () => new ShimConfigurationProvider().Instance,
	QueueNameGet = () => queueName,
	StreamGet = () => new Subject<IServiceMessage>(),
	StartListening = () => { startListeningCall = true; }
	};
	mqShim.Instance.OpenConnection(false, true);
	Assert.IsFalse(startListeningCall);
	}
	}
	/// <summary>
	/// Tests the OpenConnection options in the queue access when the queue is setup to
	/// read and write at the same time.
	/// It also ensures that StartListening is called if the queue is opened for reading.
	/// </summary>
	[TestMethod]
	public void Test_OpenConnection_ForReadingAndWriting()
	{
	const string queueName = "some random queue";
	var startListeningCall = false;
	using (ShimsContext.Create())
	{
	ShimMQQueueManager.ConstructorStringHashtable = (_, __, ___) => { };
	ShimMQQueueManager.AllInstances.AccessQueueStringInt32 = (_, s, options) =>
	{
	Assert.AreEqual(MQC.MQOO_INPUT_AS_Q_DEF + MQC.MQOO_FAIL_IF_QUIESCING + MQC.MQOO_BROWSE + MQC.MQOO_OUTPUT, options);
	Assert.AreEqual(queueName, s);
	return null;
	};
	var mqShim = new ShimMQMessageQueue
	{
	InstanceBehavior = ShimBehaviors.Fallthrough,
	ConfigurationProviderGet = () => new ShimConfigurationProvider().Instance,
	QueueNameGet = () => queueName,
	StreamGet = () => new Subject<IServiceMessage>(),
	StartListening = () => { startListeningCall = true; }
	};
	mqShim.Instance.OpenConnection(true, true);
	Assert.IsTrue(startListeningCall);
	}
	}
	/// <summary>
	/// Ensure that opening a connection with a Bad Queue Name will throw a proper
	/// <see cref="ConfigurationErrorsException"/>.
	/// </summary>
	[TestMethod]
	[ExpectedException(typeof(ConfigurationErrorsException))]
	public void Ensure_OpenConnection_ThrowsBadQueueName()
	{
	const int nameReasonCode = 2085;
	using (ShimsContext.Create())
	{
	ShimMQQueueManager.ConstructorStringHashtable = (_, __, ___) => { };
	ShimMQQueueManager.AllInstances.AccessQueueStringInt32 = (_, __, ___) =>
	{
	throw new MQException(1, nameReasonCode);
	};
	var mqShim = new ShimMQMessageQueue
	{
	InstanceBehavior = ShimBehaviors.Fallthrough,
	ConfigurationProviderGet = () => new ShimConfigurationProvider().Instance,
	QueueNameGet = () => "something",
	StreamGet = () => new Subject<IServiceMessage>(),
	};
	mqShim.Instance.OpenConnection();
	}
	}
	/// <summary>
	/// Ensure that any exception besides Bad Queue Name will be re-thrown
	/// and bubble out of the OpenConnection method.
	/// </summary>
	[TestMethod]
	[ExpectedException(typeof(MQException))]
	public void Ensure_OpenConnection_ThrowsOthersExceptBadName()
	{
	using (ShimsContext.Create())
	{
	ShimMQQueueManager.ConstructorStringHashtable = (_, __, ___) => { };
	ShimMQQueueManager.AllInstances.AccessQueueStringInt32 = (_, __, ___) =>
	{
	throw new MQException(1, 1);
	};
	var mqShim = new ShimMQMessageQueue
	{
	InstanceBehavior = ShimBehaviors.Fallthrough,
	ConfigurationProviderGet = () => new ShimConfigurationProvider().Instance,
	QueueNameGet = () => "something",
	StreamGet = () => new Subject<IServiceMessage>(),
	};
	mqShim.Instance.OpenConnection();
	}
	}

view raw

gistfile1.cs

hosted with ❤ by GitHub