Writing_Tests

Writing Unit Tests in GAML

Unit testing is an essential instrument in GAMA. It allows the modeler to define a set of assertions that will be tested. Before the execution of the embedded set of instructions, if a setup is defined in the species, model or experiment, it is executed. In a test, if one assertion fails, the evaluation of other assertions continue.

In this unit testing tutorial, we intend to show how to write unit tests in GAML using the statement test.

What is test in GAML?

In GAML, the statement test allows to write a part of code to verify if portions of our GAML model are doing exactly what they are written for. This is done independently from other parts.

To write a typical GAML unit test, we can follow three steps:

1. Define a set of attributes to use within the test.
2. Write initialisation instructions
3. Write assertions.

The aim of using unit test is to observe the resulting behaviour of some parts of our model. If the observed behaviour is consistent with the expectations, the unit test passes, otherwise, it fails, indicating that there is a problem concerning the tested part of the model.

How to write a GAML test?

To write a unit test in GAML, we start by add an experiment with type set to test. The following code shows an example.

experiment MyTest type: test autorun: true { 
	setup {
		/** Insert any initialization to run before each of the tests */
	}
}

Let's consider the following GAML code:

model TestModel

global {

	init {
		create test_agent number: 1;
	}

}

species test_agent {

	aspect default {
		draw circle(1) color: #red;
	}

	action isGreater (int p1, int p2) {
		if (p1 > p2) {
			return true;
		} else {
			return false;
		}
	}

	test {
		assert isGreater(5, 6) = false;
		assert isGreater(6, 6) = false;
		assert isGreater(6, 5) = true;
	}
}

experiment MyTest type: test autorun: true {

}

In this example, the defined action, isGreater, returns true if a parameter p1 is greater than a parameter p2 and false if not. So to test it, we declare a a unit test by test. This is done by mean of the statement assert. For instance, assert isGreater(5, 6) = false; will return true if really the result of isGreater(5, 6) is false and false if not. So, if the action isGreater is well defined, it should return false.

It is also possible to write a test in the experiment. Let's consider the following GAML code, which aim to test several GAML operators, related to the graphs:

model TestGraphs

global {
	graph the_graph;

	init {
		int i <- 10;
		create node_agent number: 7 {
			location <- {i, i + ((i / 10) mod 2) * 10};
			i <- i + 10;
		}

		the_graph <- as_distance_graph(node_agent, 30.0);
	}

}

species edge_agent {

	aspect default {
		draw shape color: #black;
	}

}

species node_agent {

	init {
	}

	aspect default {
		draw circle(1) color: #red;
		loop neigh over: the_graph neighbors_of self {
			draw line([self.location, agent(neigh).location]) color: #black;
		}

	}

}

experiment loadgraph type: gui {
	output {
		display map type: opengl {
			species edge_agent;
			species node_agent;
		}

	}

}

experiment MyTest type: test autorun: true {
	setup {
	/** Insert any initialization to run before each of the tests */
	}

	test "MyFirstTest" {
		write the_graph;
		write (node_agent[2]);
		write ("Degrees");
		write (the_graph in_degree_of (node_agent[2]));
		write (the_graph out_degree_of (node_agent[2]));
		write (the_graph degree_of (node_agent[2]));
		assert the_graph in_degree_of (node_agent[2]) = 4;
		write (the_graph out_degree_of (node_agent[2]));
		assert the_graph out_degree_of (node_agent[2]) = 4;
		assert the_graph degree_of (node_agent[2]) = 8;
		write ("out_edges_of");
		write (the_graph out_edges_of (node_agent[2]));
		write (the_graph in_edges_of (node_agent[2]));
		assert length(the_graph out_edges_of (node_agent[2])) = 4;
		write ("neighbors of node");
		write (the_graph neighbors_of (node_agent[2]));
		assert length(the_graph neighbors_of (node_agent[2])) = 8;
		assert length(remove_duplicates(the_graph neighbors_of (node_agent[2]))) = 4;
		write (the_graph predecessors_of (node_agent[2]));
		assert length(the_graph predecessors_of (node_agent[2])) = 4;
		write (the_graph successors_of (node_agent[2]));
		assert length(the_graph successors_of (node_agent[2])) = 4;
		point node8 <- {50.0, 50.0};
		write (the_graph add_node (node8));
		write (node_agent[4] remove_node_from (the_graph));
		write ("");
		write ("Contains edges");
		write (the_graph contains_vertex (node_agent[2]));
		assert the_graph contains_vertex (node_agent[2]);
		write (the_graph contains_edge (link(node_agent[2], node_agent[5])));
		write (the_graph contains_edge (link(node_agent[2], node_agent[4])));
		write (the_graph contains_edge (link(node_agent[2], node_agent[3])));
		assert the_graph contains_edge (link(node_agent[2], node_agent[5])) = false;
		assert the_graph contains_edge (link(node_agent[2], node_agent[3]));
		write (the_graph contains_vertex (node_agent[4]));
		assert the_graph contains_vertex (node_agent[4]) = false;
		write (the_graph source_of (link(node_agent[2], node_agent[3])));
		assert the_graph source_of (link(node_agent[2], node_agent[3])) = node_agent[2];
		assert the_graph target_of (link(node_agent[2], node_agent[3])) = node_agent[3];
	}

}