Prerequisites
=============
- * Python 3 (https://www.python.org/)
- * behave test framework >= 1.2.5 (https://github.com/behave/behave)
- * nose (https://nose.readthedocs.org)
- * pytidylib (http://countergram.com/open-source/pytidylib)
- * psycopg2 (http://initd.org/psycopg/)
-
-To get the prerequisites on a a fresh Ubuntu LTS 16.04 run:
-
- [sudo] apt-get install python3-dev python3-pip python3-psycopg2 python3-tidylib phpunit
- pip3 install --user behave nose
-
+See `docs/develop/Setup.md`
Overall structure
=================
This test directory is sturctured as follows:
+```
-+- bdd Functional API tests
| \
| +- steps Step implementations for test descriptions
+- php PHP unit tests
+- scenes Geometry test data
+- testdb Base data for generating API test database
-
+```
PHP Unit Tests
==============
To execute the test suite run
- cd test/php
- phpunit ../
+ cd test/php
+ UNIT_TEST_DSN='pgsql:dbname=nominatim_unit_tests' phpunit ../
It will read phpunit.xml which points to the library, test path, bootstrap
strip and set other parameters.
+It will use (and destroy) a local database 'nominatim_unit_tests'. You can set
+a different connection string with e.g. UNIT_TEST_DSN='pgsql:dbname=foo_unit_tests'.
BDD Functional Tests
====================
cd test/bdd
behave
-The tests can be configured with a set of environment variables:
+The tests can be configured with a set of environment variables (`behave -D key=val`):
- * `BUILD_DIR` - build directory of Nominatim installation to test
+ * `BUILDDIR` - build directory of Nominatim installation to test
* `TEMPLATE_DB` - name of template database used as a skeleton for
the test databases (db tests)
* `TEST_DB` - name of test database (db tests)
- * `ABI_TEST_DB` - name of the database containing the API test data (api tests)
+ * `API_TEST_DB` - name of the database containing the API test data (api tests)
+ * `DB_HOST` - (optional) hostname of database host
+ * `DB_PORT` - (optional) port of database on host
+ * `DB_USER` - (optional) username of database login
+ * `DB_PASS` - (optional) password for database login
+ * `SERVER_MODULE_PATH` - (optional) path on the Postgres server to Nominatim
+ module shared library file
* `TEST_SETTINGS_TEMPLATE` - file to write temporary Nominatim settings to
* `REMOVE_TEMPLATE` - if true, the template database will not be reused during
the next run. Reusing the base templates speeds up tests
### API Tests (`test/bdd/api`)
These tests are meant to test the different API endpoints and their parameters.
-They require a preimported test database, which consists of the import of a
-planet extract. The polygons defining the extract can be found in the test/testdb
-directory. There is also a reduced set of wikipedia data for this extract,
-which you need to import as well.
+They require a to import several datasets into a test database. You need at
+least 2GB RAM and 10GB discspace.
-The official test dataset is derived from the 160725 planet. Newer
-planets are likely to work as well but you may see isolated test
-failures where the data has changed. To recreate the input data
-for the test database run:
- wget http://free.nchc.org.tw/osm.planet/pbf/planet-160725.osm.pbf
- osmconvert planet-160725.osm.pbf -B=test/testdb/testdb.polys -o=testdb.pbf
+1. Fetch the OSM planet extract (200MB). See end of document how it got created.
-Before importing make sure to add the following to your local settings:
+ ```
+ cd Nominatim/data
+ mkdir testdb
+ cd testdb
+ wget https://www.nominatim.org/data/test/nominatim-api-testdata.pbf
+ ```
- @define('CONST_Database_DSN', 'pgsql://@/test_api_nominatim');
+2. Fetch `46*` (South Dakota) Tiger data
+
+ ```
+ cd Nominatim/data/testdb
+ wget https://nominatim.org/data/tiger2018-nominatim-preprocessed.tar.gz
+ tar xvf tiger2018-nominatim-preprocessed.tar.gz --wildcards --no-anchored '46*'
+ rm tiger2018-nominatim-preprocessed.tar.gz
+ ```
+
+3. Adapt build/settings/local.php settings:
+
+ ```
+ @define('CONST_Database_DSN', 'pgsql:dbname=test_api_nominatim');
+ @define('CONST_Use_US_Tiger_Data', true);
+ @define('CONST_Tiger_Data_Path', CONST_ExtraDataPath.'/testdb');
@define('CONST_Wikipedia_Data_Path', CONST_BasePath.'/test/testdb');
+ ```
+
+4. Import
+
+ ```
+ LOGFILE=/tmp/nominatim-testdb.$$.log
+ dropdb --if-exists test_api_nominatim
+ ./utils/setup.php --all --osm-file ../Nominatim/data/testdb/nominatim-api-testdb.pbf 2>&1 | tee $LOGFILE
+ ./utils/specialphrases.php --wiki-import > specialphrases.sql
+ psql -d test_api_nominatim -f specialphrases.sql 2>&1 | tee -a $LOGFILE
+ ./utils/setup.php --import-tiger-data 2>&1 | tee -a $LOGFILE
+ ```
+
+#### Code Coverage
+
+The API tests also support code coverage tests. You need to install
+[PHP_CodeCoverage](https://github.com/sebastianbergmann/php-code-coverage).
+On Debian/Ubuntu run:
+
+ apt-get install php-codecoverage php-xdebug
+
+The run the API tests as follows:
+
+ behave api -DPHPCOV=<coverage output dir>
+
+The output directory must be an absolute path. To generate reports, you can use
+the [phpcov](https://github.com/sebastianbergmann/phpcov) tool:
+
+ phpcov merge --html=<report output dir> <coverage output dir>
### Indexing Tests (`test/bdd/db`)
These tests check that data is imported correctly into the place table. They
use the same template database as the Indexing tests, so the same remarks apply.
+
+
+
+How the test database extract was generated
+-------------------------------------------
+The official test dataset was derived from the 180924 planet (note: such
+file no longer exists at https://planet.openstreetmap.org/planet/2018/).
+Newer planets are likely to work as well but you may see isolated test
+failures where the data has changed. To recreate the input data
+for the test database run:
+
+ wget https://ftp5.gwdg.de/pub/misc/openstreetmap/planet.openstreetmap.org/pbf/planet-180924.osm.pbf
+ osmconvert planet-180924.osm.pbf -B=test/testdb/testdb.polys -o=testdb.pbf
projects / nominatim.git / blobdiff