Tests take place in a controlled environment, allowing you to isolate agent behaviour and verify expected functionality. All tests take place in a TestKit; In the same way, our models run in AgentBasedModel our tests run in a TestKit.
\nFor the following section, we will be adding tests to the model created in the tutorial section. Don't worry if you have not compleated the tutorial; examples will be self-contained, for the interested reader you can find this tutorial here.
\nGiven all our tests require a TestKit it would be handy if we did not have to keep setting up the TestKit for each test we wanted to run. JUnit allows you to annotate methods with @Before. Code annotated in this fashion will be executed before each test.
\nCreating your first TestKit (Java)
\npublic class BankTest {\n\n private TestKit<MortgageModel.Globals> testKit;\n @Before\n public void init(){\n testKit = TestKit.create(MortgageModel.Globals.class);\n }\n}Notice that we have passed the user-defined globals object to TestKit.create(), which we discussed in the Global State. If our model uses the default GlobalState this argument can be omitted.
To carry out meaningful tests we have to add agents to the TestKit. We can add agents to a TestKit in a similar manner to adding agents to an AgentBasedModel. Agents added to the same Testkit do not have knowledge of each other; however, you may want to add multiple agents to a single TestKit to test different cases of the same functionality on different agents in one test.
\nAdding agents (Java)
\n@Test\npublic void creatingAgent(){\n Bank bank1 = testKit.addAgent(Bank.class); \n Bank bank2 = testKit.addAgent(Bank.class);\n}Of course, this is not much of a test, we have merely added an agent to our TestKit. Improving upon this, we can also create agents with data injectors. Because we are in a test environment, we can then assert that agents are created as expected.
\nAdding agents with data injector (Java)
\n@Test \npublic void agentShouldBeInitilisedWithInjectedArgs(){\n Bank bank = testKit.addAgent(Bank.class, b -> {\n b.debt = 9;\n });\n assertEquals(bank.debt, 9);\n}As mentioned, we test actions in isolation. After creating a TestKit and adding agents, we are ready to test. There are three ways to test an action has executed as expected. One is to examine how the action has mutated an agent. Another involves inspecting the return type (TestResult) of our testAction method. Finally, TestKit can hold accumulators which we can mutate; these need to be initialized for testing actions that mutate or use the value of accumulators.
Suppose we have a Household agent that has an age associated with it and an Action that increments its age by one.
Simple 'birthday' action (Java)
\npublic static Action<Household> birthday =\n Action.create(Household.class, h -> h.age += 1);Simple 'birthday' test (Java)
\n@Test\npublic void birthdayShouldIncrementAgeByOne() {\n Household household = testKit.addAgent(Household.class, h -> h.age = 49);\n\n testKit.testAction(household, Household.birthday);\n\n assertEquals(household.age, 50);\n}As well as being able to test for mutations on agents we can also use the returned TestResult object to check the following:
We will address the first two of these now and the final point after discussing how messaging works in the test environment.
\nSuppose the complexity of our birthday Action is extended slightly, to stop an agent if it reaches a certain age.
Simple 'birthday' action with 'death' (Java)
\npublic static Action<Household> birthday =\n Action.create(\n Household.class,\n h -> {\n if (h.age >= 99) {\n h.stop();\n } else {\n h.age += 1;\n }\n });We can use the result of testAction to check if the agent has been stopped. Notice that each action has a separate testResult, this highlights the isolated nature of actions in the TestKit and makes it easy to reason about them.
Simple 'birthday' test with 'death' (Java)
\n@Test\npublic void oldAgentsShouldStop() {\n Household household1 = testKit.addAgent(Household.class, h -> h.age = 49);\n Household household2 = testKit.addAgent(Household.class, h -> h.age = 99);\n\n TestResult testResult1 = testKit.testAction(household1, Household.birthday);\n TestResult testResult2 = testKit.testAction(household2, Household.birthday);\n\n assertFalse(testResult1.wasStopped());\n assertTrue(testResult2.wasStopped());\n}We can also create long accumulators in a test kit. These will need to be created to test actions that use the value of an existing accumulator, or action that add to accumulators. For example suppose we wanted to keep track of how many agents were dying in the model, and we were using an accumulator to gather this information from our model. We could test that our action is actually updating the accumulator.
\n// Action that updates accumulator on death\npublic static Action<Household> birthday =\n Action.create(\n Household.class,\n h -> {\n if (h.age >= 99) {\n h.getLongAccumulator(\"deaths\").add(1);\n h.stop();\n } else {\n h.age += 1;\n }\n });\n\n@Test\npublic void deadAgentShouldUpdateAccumulator() {\n Household household1 = testKit.addAgent(Household.class, h -> h.age = 100);\n\n long initialValue = 0;\n testKit.createLongAccumulator(\"deaths\", initialValue);\n\n TestResult result1 = testKit.testAction(household1, Household.birthday);\n\n assertEquals(initialValue + 1, result1.getLongAccumulator(\"deaths\").value());\n}It is important to note that updating an accumulator from within a tested action does not update the testKit accumulator, instead it returns a new updated accumulator with the TestResult that can be tested. This is so that multiple tests can be run using the same testKit without affecting the results of each other.
It is also possible to get the value of an accumulator
\nSuppose our households gave birth to new households based on some predicate, and adds a link from the new household back to the parent household.
\npublic static Action<Household> birthday =\n Action.create(\n Household.class,\n h -> {\n if (h.age == 35) {\n h.spawn(Household.class, newH -> newH.addLink(h.getID(), ParentLink.class))\n }\n });We can use the result of testAction to check if the agent has been spawned, and get details about these spawned agents.
@Test\npublic void agentsShouldCreateNewAgents() {\n Household household1 = testKit.addAgent(Household.class, h -> h.age = 35);\n Household household2 = testKit.addAgent(Household.class, h -> h.age = 99);\n\n TestResult testResult1 = testKit.testAction(household1, Household.birthday);\n TestResult testResult2 = testKit.testAction(household2, Household.birthday);\n\n assertTrue(testResult1.getSpawnedAgentsOfType(Household.class).size(), 1);\n assertTrue(testResult1.getSpawnedAgentsOfType(Household.class).size(), 0);\n\n Household newHousehold = testResult1.getSpawnedAgentsOfType(Household.class).get(0);\n assertTrue(newHousehold.getLinksTo(household1.getID()).size(), 1)\n}We have already mentioned how agents are tested in isolation. Given an integral component of the Simudyne architecture is message passing you may wonder how the test kit handles this. To test how actions process messages we must send agents messages before running an action. This is in contrast to our AgentBasedModel where message passing is between agents. This allows us to construct the exact message we wish to test on an agent.
\nSending a message to an agent (Java)
\n@Test\npublic void sendPayementMessagesTest(){\n Bank bank = testKit.addAgent(Bank.class);\n testKit.send(Messages.Payment.class, payment -> {\n payment.repayment=9;\n payment.amount=11;\n }).to(bank.getID());\n}We can think of this as putting a message directly into the inbox of the agent. On executing an action our bank agent will have this message to process. Let's take a look at a simple example where our bank processes payments by merely incrementing assets by the payment amount. For completeness, the Action is given below.
\nProcessing a message in an action (Java)
\npublic static Action<Bank> simplePaymentIncrement =\n new Action<>(\n Bank.class,\n bank ->\n bank.getMessagesOfType(Messages.Payment.class)\n .forEach(payment -> bank.assets += payment.amount));We can use the test kit to test this action is processing in the expected way.
\nTesting actions (Java)
\n@Test\npublic void sendPaymentMessagesTest() {\n Bank bank =\n testKit.addAgent(\n Bank.class,\n b -> {\n b.assets = 90;\n });\n\n testKit\n .send(\n Messages.Payment.class,\n payment -> {\n payment.repayment = 10;\n payment.amount = 10;\n })\n .to(bank.getID());\n\n testKit.testAction(bank, Bank.simplePaymentIncremement);\n\n assertEquals(bank.assets, 100);\n}If you find yourself sending multiple messages to the same agent, you can distinguish between senders by including the id of the sender. This is done by passing an extra parameter to the send() method; we will look at an example of this in the next section.
Processing received messages are only half the story. Agents must also be able to send messages, which we will want to test. Messages sent in an agents action are captured by the testResult object.
\nFor illustrative purposes, let's create an Action in the bank that sends an ApplicationSuccessful message to an agent with an id of one.
Simple action that sends a message to a fixed id (Java)
\npublic static Action<Bank> sendApplicationSuccessfulMessage =\n new Action<>(Bank.class, bank -> bank.send(Messages.ApplicationSuccessful.class).to(1L));We can use this action in testKit and test two things. Firstly, that a message is being sent, and secondly, that it is being sent to the correct agent.
Testing messages sent in an action (Java)
\n@Test\n public void captureSentMessage() {\n Bank bank = testKit.addAgent(Bank.class);\n TestResult result = testKit.testAction(bank, Bank.sendApplicationSuccessfulMessage);\n List<Messages.ApplicationSuccessful> messages =\n result.getMessagesOfType(Messages.ApplicationSuccessful.class);\n assertEquals(1, messages.size());\n assertEquals(1, messages.get(0).getTo());\n }