Writing Unit Tests for a Variable

By convention, there are a set of ``unit tests'' for every Opus variable , and for every Opus model. These tests check that the variable or model is doing the right thing, and were useful to uncover bugs when we wrote the tests. In addition, the innards of the Opus system also include many unit tests to check that the framework works.

Here are some guidelines to writing unit tests:

• Create just enough data for the test. For instance, create three gridcells with two attributes on each gridcell. This makes it easier to write, understand and modify tests.
• Use data that has interesting differences; the test data does not have to be realistic.
• Use different test data for each test. Otherwise, changing the data to better serve one test can cause problems with a different test.

The urbansim package contains many examples of variables and their tests. For instance, see the Python modules in urbansim.gridcell.

When writing a variable, be careful about forcing the values of a variable's computation to be within a specified range. This can hide errors. For instance, when we were developing UrbanSim, we initially used numpy's clip function to force the vacant_industrial_sqft variable values to be at least zero. However, it turned out that there was a bug in our code that led to more industrial jobs being allocated to a gridcell than the gridcell's industrial sqft could support. This sometimes led to a negative value of vacant_industrial_sqft for that gridcell. Since these negative values were being forced to zero, however, we saw an un-intuitive result where the number of industrial jobs was going up at the same time as the vacant_industrial_sqft, even though no new industrial sqft was being built. Removing the clip made it easier to diagnose the problem.