tests/README.md

   1 This directory contains functional tests for the Nominatim API,
   2 for the import/update from osm files and for indexing.
   3
   4 The tests use the lettuce framework (http://lettuce.it/) and
   5 nose (https://nose.readthedocs.org). API tests are meant to be run
   6 against a Nominatim installation with a complete planet-wide
   7 setup based on a fairly recent planet. If you only have an
   8 excerpt, some of the API tests may fail. Database tests can be
   9 run without having a database installed.
  10
  11 Prerequisites
  12 =============
  13
  14  * lettuce framework (http://lettuce.it/)
  15  * nose (https://nose.readthedocs.org)
  16  * pytidylib (http://countergram.com/open-source/pytidylib)
  17  * haversine (https://github.com/mapado/haversine)
  18  * shapely (https://github.com/Toblerity/Shapely)
  19
  20 Usage
  21 =====
  22
  23  * get prerequisites
  24
  25      # on a fresh Ubuntu LTS 14.04 you'll also need these system-wide packages
  26      [sudo] apt-get install python-dev python-pip python-Levenshtein tidy
  27
  28      [sudo] pip install lettuce nose pytidylib haversine psycopg2 shapely
  29
  30  * run the tests
  31
  32      NOMINATIM_SERVER=http://your.nominatim.instance/ lettuce features
  33
  34 The tests can be configured with a set of environment variables:
  35
  36  * `NOMINATIM_SERVER` - URL of the nominatim instance (API tests)
  37  * `NOMINATIM_DIR` - source directory of Nominatim (import tests)
  38  * `TEMPLATE_DB` - name of template database used as a skeleton for
  39                    the test databases (db tests)
  40  * `TEST_DB` - name of test database (db tests)
  41  * `NOMINATIM_SETTINGS` - file to write temporary Nominatim settings to (db tests)
  42  * `NOMINATIM_REUSE_TEMPLATE` - if defined, the template database will not be
  43                                 deleted after the test runs and reused during
  44                                 the next run. This speeds up tests considerably
  45                                 but might lead to outdated errors for some
  46                                 changes in the database layout.
  47  * `NOMINATIM_KEEP_SCENARIO_DB` - if defined, the test database will not be
  48                                   dropped after a test is finished. Should
  49                                   only be used if one single scenario is run,
  50                                   otherwise the result is undefined.
  51  * `LOGLEVEL` - set to 'debug' to get more verbose output (only works properly
  52                 when output to a logfile is configured)
  53  * `LOGFILE` - sends debug output to the given file
  54
  55 Writing Tests
  56 =============
  57
  58 The following explanation assume that the reader is familiar with the lettuce
  59 notations of features, scenarios and steps.
  60
  61 All possible steps can be found in the `steps` directory and should ideally
  62 be documented.
  63
  64
  65 API Tests (`features/api`)
  66 --------------------------
  67
  68 These tests are meant to test the different API calls and their parameters.
  69
  70 There are two kind of steps defined for these tests:
  71 request setup steps (see `steps/api_setup.py`)
  72 and steps for checking results (see `steps/api_result.py`).
  73
  74 Each scenario follows this simple sequence of steps:
  75
  76   1. One or more steps to define parameters and HTTP headers of the request.
  77      These are cumulative, so you can use multiple steps.
  78   2. A single step to call the API. This sends a HTTP request to the configured
  79      server and collects the answer. The cached parameters will be deleted,
  80      to ensure that the setup works properly with scenario outlines.
  81   3. As many result checks as necessary. The result remains cached, so that
  82      multiple tests can be added here.
  83
  84 Indexing Tests (`features/db`)
  85 ---------------------------------------------------
  86
  87 These tests check the import and update of the Nominatim database. They do not
  88 test the correctness of osm2pgsql. Each test will write some data into the `place`
  89 table (and optionally `the planet_osm_*` tables if required) and then run
  90 Nominatim's processing functions on that.
  91
  92 These tests need to create their own test databases. By default they will be
  93 called `test_template_nominatim` and `test_nominatim`. Names can be changed with
  94 the environment variables `TEMPLATE_DB` and `TEST_DB`. The user running the tests
  95 needs superuser rights for postgres.
  96
  97
  98 Import Tests (`features/osm2pgsql`)
  99 -----------------------------------
 100
 101 These tests check that data is imported correctly into the place table. They
 102 use the same template database as the Indexing tests, so the same remarks apply.