3 This chapter describes the tests in the `/test` directory, how they are
4 structured and how to extend them. For a quick introduction on how to run
5 the tests, see the [Development setup chapter](Development-Environment.md).
9 There are two kind of tests in this test suite. There are functional tests
10 which test the API interface using a BDD test framework and there are unit
11 tests for the Python code.
13 This test directory is structured as follows:
16 -+- bdd Functional API tests
18 | +- steps Step implementations for test descriptions
19 | +- osm2pgsql Tests for data import via osm2pgsql
20 | +- db Tests for internal data processing on import and update
21 | +- api Tests for API endpoints (search, reverse, etc.)
23 +- python Python unit tests
24 +- testdb Base data for generating API test database
25 +- testdata Additional test data used by unit tests
28 ## Python Unit Tests (`test/python`)
30 Unit tests for Python code can be found in the `python/` directory. The goal is
31 to have complete coverage of the Python library in `nominatim`.
33 To execute the tests run
41 The name of the pytest binary depends on your installation.
43 ## BDD Functional Tests (`test/bdd`)
45 Functional tests are written as BDD instructions. For more information on
46 the philosophy of BDD testing, read the Wikipedia article on
47 [Behaviour-driven development](https://en.wikipedia.org/wiki/Behavior-driven_development).
51 To run the functional tests, do
55 The BDD tests create databases for the tests. You can set name of the databases
56 through configuration variables in your `pytest.ini`:
58 * `nominatim_test_db` defines the name of the temporary database created for
59 a single test (default: `test_nominatim`)
60 * `nominatim_api_test_db` defines the name of the database containing
61 the API test data, see also below (default: `test_api_nominatim`)
62 * `nominatim_template_db` defines the name of the template database used
63 for creating the temporary test databases. It contains some static setup
64 which usually doesn't change between imports of OSM data
65 (default: `test_template_nominatim`)
67 To change other connection parameters for the PostgreSQL database, use
68 the [libpq enivronment variables](https://www.postgresql.org/docs/current/libpq-envars.html).
69 Never set a password through these variables. Use a
70 [password file](https://www.postgresql.org/docs/current/libpq-pgpass.html) instead.
72 The API test database and the template database are only created once and then
73 left untouched. This is usually what you want because it speeds up subsequent
74 runs of BDD tests. If you do change code that has an influence on the content
75 of these databases, you can run pytest with the `--nominatim-purge` parameter
76 and the databases will be dropped and recreated from scratch.
78 When running the BDD tests with make (using `make tests` or `make bdd`), then
79 the databases will always be purged.
81 The temporary test database is usually dropped directly after the test, so
82 it does not take up unnecessary space. If you want to keep the database around,
83 for example while debugging a specific BDD test, use the parameter
84 `--nominatim-keep-db`.
87 ### API Tests (`test/bdd/api`)
89 These tests are meant to test the different API endpoints and their parameters.
90 They require to import several datasets into a test database. This is normally
91 done automatically during setup of the test. The API test database is then
92 kept around and reused in subsequent runs of behave. Use `--nominatim-purge`
93 to force a reimport of the database.
95 The official test dataset is saved in the file `test/testdb/apidb-test-data.pbf`
96 and compromises the following data:
98 * Geofabrik extract of Liechtenstein
99 * extract of Autauga country, Alabama, US (for tests against Tiger data)
100 * additional data from `test/testdb/additional_api_test.data.osm`
102 API tests should only be testing the functionality of the website frontend code.
103 Most tests should be formulated as BDD DB creation tests (see below) instead.
105 ### DB Creation Tests (`test/bdd/db`)
107 These tests check the import and update of the Nominatim database. They do not
108 test the correctness of osm2pgsql. Each test will write some data into the `place`
109 table (and optionally the `planet_osm_*` tables if required) and then run
110 Nominatim's processing functions on that.
112 These tests use the template database and create temporary test databases for
115 ### Import Tests (`test/bdd/osm2pgsql`)
117 These tests check that data is imported correctly into the place table.
119 These tests also use the template database and create temporary test databases