test/README.md

   1 This directory contains functional and unit tests for the Nominatim API.
   2
   3 Prerequisites
   4 =============
   5
   6 See `docs/develop/Setup.md`
   7
   8 Overall structure
   9 =================
  10
  11 There are two kind of tests in this test suite. There are functional tests
  12 which test the API interface using a BDD test framework and there are unit
  13 tests for specific PHP functions.
  14
  15 This test directory is sturctured as follows:
  16
  17 ```
  18  -+-   bdd         Functional API tests
  19   | \
  20   | +-  steps      Step implementations for test descriptions
  21   | +-  osm2pgsql  Tests for data import via osm2pgsql
  22   | +-  db         Tests for internal data processing on import and update
  23   | +-  api        Tests for API endpoints (search, reverse, etc.)
  24   |
  25   +-   php         PHP unit tests
  26   +-   scenes      Geometry test data
  27   +-   testdb      Base data for generating API test database
  28 ```
  29
  30 PHP Unit Tests
  31 ==============
  32
  33 Unit tests can be found in the php/ directory and tests selected php functions.
  34 Very low coverage.
  35
  36 To execute the test suite run
  37
  38     cd test/php
  39     UNIT_TEST_DSN='pgsql:dbname=nominatim_unit_tests' phpunit ../
  40
  41 It will read phpunit.xml which points to the library, test path, bootstrap
  42 strip and set other parameters.
  43
  44 It will use (and destroy) a local database 'nominatim_unit_tests'. You can set
  45 a different connection string with e.g. UNIT_TEST_DSN='pgsql:dbname=foo_unit_tests'.
  46
  47 BDD Functional Tests
  48 ====================
  49
  50 Functional tests are written as BDD instructions. For more information on
  51 the philosophy of BDD testing, see http://pythonhosted.org/behave/philosophy.html
  52
  53 Usage
  54 -----
  55
  56 To run the functional tests, do
  57
  58     cd test/bdd
  59     behave
  60
  61 The tests can be configured with a set of environment variables (`behave -D key=val`):
  62
  63  * `BUILDDIR` - build directory of Nominatim installation to test
  64  * `TEMPLATE_DB` - name of template database used as a skeleton for
  65                    the test databases (db tests)
  66  * `TEST_DB` - name of test database (db tests)
  67  * `API_TEST_DB` - name of the database containing the API test data (api tests)
  68  * `DB_HOST` - (optional) hostname of database host
  69  * `DB_PORT` - (optional) port of database on host
  70  * `DB_USER` - (optional) username of database login
  71  * `DB_PASS` - (optional) password for database login
  72  * `SERVER_MODULE_PATH` - (optional) path on the Postgres server to Nominatim
  73                           module shared library file
  74  * `TEST_SETTINGS_TEMPLATE` - file to write temporary Nominatim settings to
  75  * `REMOVE_TEMPLATE` - if true, the template database will not be reused during
  76                        the next run. Reusing the base templates speeds up tests
  77                        considerably but might lead to outdated errors for some
  78                        changes in the database layout.
  79  * `KEEP_TEST_DB` - if true, the test database will not be dropped after a test
  80                     is finished. Should only be used if one single scenario is
  81                     run, otherwise the result is undefined.
  82
  83 Logging can be defined through command line parameters of behave itself. Check
  84 out `behave --help` for details. Also keep an eye out for the 'work-in-progress'
  85 feature of behave which comes in handy when writing new tests.
  86
  87 Writing Tests
  88 -------------
  89
  90 The following explanation assume that the reader is familiar with the BDD
  91 notations of features, scenarios and steps.
  92
  93 All possible steps can be found in the `steps` directory and should ideally
  94 be documented.
  95
  96 ### API Tests (`test/bdd/api`)
  97
  98 These tests are meant to test the different API endpoints and their parameters.
  99 They require a to import several datasets into a test database. You need at
 100 least 2GB RAM and 10GB discspace.
 101
 102
 103 1. Fetch the OSM planet extract (200MB). See end of document how it got created.
 104
 105     ```
 106     cd Nominatim/data
 107     mkdir testdb
 108     cd testdb
 109     wget https://www.nominatim.org/data/test/nominatim-api-testdata.pbf
 110     ```
 111
 112 2. Fetch `46*` (South Dakota) Tiger data
 113
 114     ```
 115     cd Nominatim/data/testdb
 116     wget https://nominatim.org/data/tiger2018-nominatim-preprocessed.tar.gz
 117     tar xvf tiger2018-nominatim-preprocessed.tar.gz --wildcards --no-anchored '46*'
 118     rm tiger2018-nominatim-preprocessed.tar.gz
 119     ```
 120
 121 3. Adapt build/settings/local.php settings:
 122
 123         ```
 124     @define('CONST_Database_DSN', 'pgsql:dbname=test_api_nominatim');
 125     @define('CONST_Use_US_Tiger_Data', true);
 126     @define('CONST_Tiger_Data_Path', CONST_ExtraDataPath.'/testdb');
 127     @define('CONST_Wikipedia_Data_Path', CONST_BasePath.'/test/testdb');
 128     ```
 129
 130 4. Import
 131
 132     ```
 133         LOGFILE=/tmp/nominatim-testdb.$$.log
 134     dropdb --if-exists test_api_nominatim
 135     ./utils/setup.php --all --osm-file ../Nominatim/data/testdb/nominatim-api-testdb.pbf 2>&1 | tee $LOGFILE
 136     ./utils/specialphrases.php --wiki-import > specialphrases.sql
 137     psql -d test_api_nominatim -f specialphrases.sql 2>&1 | tee -a $LOGFILE
 138     ./utils/setup.php --import-tiger-data 2>&1 | tee -a $LOGFILE
 139     ```
 140
 141 #### Code Coverage
 142
 143 The API tests also support code coverage tests. You need to install
 144 [PHP_CodeCoverage](https://github.com/sebastianbergmann/php-code-coverage).
 145 On Debian/Ubuntu run:
 146
 147     apt-get install php-codecoverage php-xdebug
 148
 149 The run the API tests as follows:
 150
 151     behave api -DPHPCOV=<coverage output dir>
 152
 153 The output directory must be an absolute path. To generate reports, you can use
 154 the [phpcov](https://github.com/sebastianbergmann/phpcov) tool:
 155
 156     phpcov merge --html=<report output dir> <coverage output dir>
 157
 158 ### Indexing Tests (`test/bdd/db`)
 159
 160 These tests check the import and update of the Nominatim database. They do not
 161 test the correctness of osm2pgsql. Each test will write some data into the `place`
 162 table (and optionally `the planet_osm_*` tables if required) and then run
 163 Nominatim's processing functions on that.
 164
 165 These tests need to create their own test databases. By default they will be
 166 called `test_template_nominatim` and `test_nominatim`. Names can be changed with
 167 the environment variables `TEMPLATE_DB` and `TEST_DB`. The user running the tests
 168 needs superuser rights for postgres.
 169
 170 ### Import Tests (`test/bdd/osm2pgsql`)
 171
 172 These tests check that data is imported correctly into the place table. They
 173 use the same template database as the Indexing tests, so the same remarks apply.
 174
 175
 176
 177 How the test database extract was generated
 178 -------------------------------------------
 179 The official test dataset was derived from the 180924 planet (note: such
 180 file no longer exists at https://planet.openstreetmap.org/planet/2018/).
 181 Newer planets are likely to work as well but you may see isolated test
 182 failures where the data has changed. To recreate the input data
 183 for the test database run:
 184
 185     wget https://ftp5.gwdg.de/pub/misc/openstreetmap/planet.openstreetmap.org/pbf/planet-180924.osm.pbf
 186     osmconvert planet-180924.osm.pbf -B=test/testdb/testdb.polys -o=testdb.pbf