[Qgis-developer] Testing friday

[Tim Sutton]

Hi All

I thought it might be fun to add a few tests to QGIS every friday as a
new tradition. So tomorrow I will start  :-)

I would like to invite, encourage, beg and bribe others out there to
write tests too! You don't have to be a code guru - if you can write a
python plugin you are already more than qualified!

Here are the 4 simple steps to writing a new python test:

1) ------------------------------------ Write test code

I put mine into tests/src/python/test_qgsgeometry.py as I wanted to
start a new test case - but you could just as easily extend an
existing one. Lets look at the source:

  1 import unittest
  2
  3 from qgis.core import (QgsGeometry, QGis)
  4
  5 # Convenience instances in case you may need them but
  6 # not used in this test
  7 #from utilities import getQgisTestApp
  8 #QGISAPP, CANVAS, IFACE, PARENT = getQgisTestApp()
  9
 10 class TestQgsGeometry(unittest.TestCase):
 11
 12     def testWktPointLoading(self):
 13         myWKT='POINT(10 10)'
 14         myGeometry = QgsGeometry.fromWkt(myWKT)
 15         myMessage = ('Expected:\n%s\nGot:\n%s\n' %
 16                       (QGis.Point, myGeometry.type()))
 17         assert myGeometry.type() == QGis.Point, myMessage
 18
 19
 20 if __name__ == '__main__':
 21     unittest.main()

Here is a walkthrough:

So on line 1 we are importing unittest since we are using the python
unittest framework.
On line 3 I import the two QGIS classes I need for my test.
Lines 5-8 are there for info only - they provide a mechanism to test
application and plugin space code too, and also to create a map
canvase instance if you want to test rendering things. These lines are
disabled for the test.

Line ten declares my test class which inherits from unittest.TestCase

Each test unit you want to implement gets written in its own method.
In this case we are going to see if we can create a point from a wkt
and then test that the geometry type is correct after loading it.

Lines 13-14 create the point geometry from a WKT string

Lines 15-16 compose an error message with some diagnostic info for if
the test fails.

Line 17 asserts that the loaded geometry is indeed a point.

Lines 20-21  are just plumbing so that you can run the test standalone
if you want to

2) ------------------------------------------ Register your test

To register your test, you simply add a new entry to
tests/src/python/CMakeLists.txt Like this:

ADD_PYTHON_TEST(PyQgsGeometry test_qgsgeometry.py)

3) ------------------------------------------ Running your test individually

Now you can run it simply by doing this (I am using a regex match on
the test name):

ctest -R PyQgsGeom -V

Make sure you are in your build dir when you run it. You should get an
output like this:

test 23
    Start 23: PyQgsGeometry

23: Test command: /usr/bin/cmake "-P"
"/home/timlinux/dev/cpp/Quantum-GIS/build-master-qtcreator/tests/src/python/PyQgsGeometry.cmake"
23: Test timeout computed to be: 1500
23: LD_LIBRARY_PATH:NOTFOUND:/home/timlinux/dev/cpp/Quantum-GIS/build-master-qtcreator/output/lib:
23: PYTHONPATH:/home/timlinux/dev/cpp/Quantum-GIS/build-master-qtcreator/output/python/:
23: -- Running /usr/bin/python
/home/timlinux/dev/cpp/Quantum-GIS/tests/src/python/test_qgsgeometry.py
23: .
23: ----------------------------------------------------------------------
23: Ran 1 test in 0.000s
23:
23: OK
23:
1/1 Test #23: PyQgsGeometry ....................   Passed    0.10 sec

The following tests passed:
	PyQgsGeometry

4) --------------------------------------- There is no step 4

There is nothing more to it. Your test should run automatically when
you run make check, make test or make Experimental. If you run make
Experimental, your test will appear on the test dashboard here:

http://dash.orfeo-toolbox.org/index.php?project=QGIS

The test will also be built automatically whenever a commit takes
place by our Jenkins robot.

If you contribute a test you provide a verifyable indicator that that
specific functionality is working with each commit. When we have 1000
tests it will be very difficult for people to break stuff in the code
base without us realising it.

Anyway I will hang around on IRC #qgis tomorrow (GMT+2) to lend a hand
to anyone else who might like to start adding tests. It will probably
only take 5-10 mins for most tests you can contrive (unless you need
to test something more complex) and it really doesn't require any deep
technical skills - cut and paste from the QGIS Python cookbook will
probably take you far! I look forward to many pull requests containing
new tests!

Thanks again to Jurgen for resolving the cmake issues so that the
tests can be used with no environment variable gymnastics.

Regards

Tim


-- 
Tim Sutton - QGIS Project Steering Committee Member (Release  Manager)
==============================================
Please do not email me off-list with technical
support questions. Using the lists will gain
more exposure for your issues and the knowledge
surrounding your issue will be shared with all.

Visit http://linfiniti.com to find out about:
 * QGIS programming and support services
 * Mapserver and PostGIS based hosting plans
 * FOSS Consulting Services
Skype: timlinux
Irc: timlinux on #qgis at freenode.net
==============================================