mirror of
https://github.com/osm-search/Nominatim.git
synced 2026-02-15 02:47:59 +00:00
restructure developer's manual
Add a section on setting up the development environment which now also includes the former chapter on recreating the documentation. Move the README from test/ into the manual as the new Testing chapter.
This commit is contained in:
Sarah Hoffmann
170
docs/develop/Development-Environment.md
Normal file
170
docs/develop/Development-Environment.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Setting up Nominatim for Development
|
||||
|
||||
This chapter gives an overview how to set up Nominatim for developement
|
||||
and how to run tests.
|
||||
|
||||
!!!Important
|
||||
This guide assumes that you develop under the latest version of Ubuntu. You
|
||||
can of course also use your favourite distribution. You just might have to
|
||||
adapt the commands below slightly, in particular the commands for installing
|
||||
additional software.
|
||||
|
||||
## Installing Nominatim
|
||||
|
||||
The first step is to install Nominatim itself. Please follow the installation
|
||||
instructions in the [Admin section](../admin/Installation.md). You don't need
|
||||
to set up a webserver for development, the webserver that is included with PHP
|
||||
is sufficient.
|
||||
|
||||
If you want to run Nominatim in a VM via Vagrant, use the default `ubuntu` setup.
|
||||
Vagrant's libvirt provider runs out-of-the-box under Ubuntu. You also need to
|
||||
install an NFS daemon to enable directory sharing between host and guest. The
|
||||
following packages should get you started:
|
||||
|
||||
sudo apt install vagrant vagrant-libvirt libvirt-daemon nfs-kernel-server
|
||||
|
||||
## Prerequisites for testing and documentation
|
||||
|
||||
The Nominatim tests suite consists of behavioural tests (using behave) and
|
||||
unit tests (using PHPUnit). It has the following additional requirements:
|
||||
|
||||
* [behave test framework](https://github.com/behave/behave) >= 1.2.5
|
||||
* [nose](https://nose.readthedocs.org)
|
||||
* [pytidylib](http://countergram.com/open-source/pytidylib)
|
||||
* [phpunit](https://phpunit.de) >= 7.3
|
||||
* [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)
|
||||
|
||||
The documentation is built with mkdocs:
|
||||
|
||||
* [mkdocs](https://www.mkdocs.org/) >= 1.1.2
|
||||
|
||||
### Installing prerequisites on Ubuntu/Debian
|
||||
|
||||
Some of the Python packages require the newest version which is not yet
|
||||
available with the current distributions. Therefore it is recommended to
|
||||
install pip to get the newest versions.
|
||||
|
||||
To install all necessary packages run:
|
||||
|
||||
```sh
|
||||
sudo apt install php-cgi phpunit php-codesniffer \
|
||||
python3-pip python3-setuptools python3-dev
|
||||
|
||||
pip3 install --user behave nose mkdocs
|
||||
```
|
||||
|
||||
The `mkdocs` executable will be located in `.local/bin`. You may have to add
|
||||
this directory to your path, for example by running:
|
||||
|
||||
```
|
||||
echo 'export PATH=~/.local/bin:$PATH' > ~/.profile
|
||||
```
|
||||
|
||||
If your distribution does not have PHPUnit 7.3+, you can install it (as well
|
||||
as CodeSniffer) via composer:
|
||||
|
||||
```
|
||||
sudo apt-get install composer
|
||||
composer global require "squizlabs/php_codesniffer=*"
|
||||
composer global require "phpunit/phpunit=8.*"
|
||||
```
|
||||
|
||||
The binaries are found in `.config/composer/vendor/bin`. You need to add this
|
||||
to your PATH as well:
|
||||
|
||||
```
|
||||
echo 'export PATH=~/.config/composer/vendor/bin:$PATH' > ~/.profile
|
||||
```
|
||||
|
||||
|
||||
## Executing Tests
|
||||
|
||||
All tests are located in the `\test` directory.
|
||||
|
||||
### Preparing the test database
|
||||
|
||||
Some of the behavioural test expect a test database to be present. You need at
|
||||
least 2GB RAM and 10GB disk space to create the database.
|
||||
|
||||
First create a separate directory for the test DB and Fetch the test planet
|
||||
data and the Tiger data for South Dakota:
|
||||
|
||||
```
|
||||
mkdir testdb
|
||||
cd testdb
|
||||
wget https://www.nominatim.org/data/test/nominatim-api-testdata.pbf
|
||||
wget -O - https://nominatim.org/data/tiger2018-nominatim-preprocessed.tar.gz | tar xz --wildcards --no-anchored '46*'
|
||||
```
|
||||
|
||||
Configure and build Nominatim in the usual way:
|
||||
|
||||
```
|
||||
cmake $USERNAME/Nominatim
|
||||
make
|
||||
```
|
||||
|
||||
Copy the test settings:
|
||||
|
||||
```
|
||||
cp $USERNAME/Nominatim/test/testdb/local.php settings/
|
||||
```
|
||||
|
||||
Inspect the file to check that all settings are correct for your local setup.
|
||||
|
||||
Now you can import the test database:
|
||||
|
||||
```
|
||||
dropdb --if-exists test_api_nominatim
|
||||
./utils/setup.php --all --osm-file nominatim-api-testdb.pbf 2>&1 | tee import.log
|
||||
./utils/specialphrases.php --wiki-import | psql -d test_api_nominatim 2>&1 | tee -a import.log
|
||||
./utils/setup.php --import-tiger-data 2>&1 | tee -a import.log
|
||||
```
|
||||
|
||||
### Running the tests
|
||||
|
||||
To run all tests just go to the test directory and run make:
|
||||
|
||||
```sh
|
||||
cd test
|
||||
make
|
||||
```
|
||||
|
||||
To skip tests that require the test database, run `make no-test-db` instead.
|
||||
|
||||
For more information about the structure of the tests and how to change and
|
||||
extend the test suite, see the [Testing chapter](Testing.md).
|
||||
|
||||
## Documentation Pages
|
||||
|
||||
The [Nominatim documentation](https://nominatim.org/release-docs/develop/) is
|
||||
built using the [MkDocs](https://www.mkdocs.org/) static site generation
|
||||
framework. The master branch is automatically deployed every night on
|
||||
[https://nominatim.org/release-docs/develop/](https://nominatim.org/release-docs/develop/)
|
||||
|
||||
To build the documentation, go to the build directory and run
|
||||
|
||||
```
|
||||
make doc
|
||||
INFO - Cleaning site directory
|
||||
INFO - Building documentation to directory: /home/vagrant/build/site-html
|
||||
```
|
||||
|
||||
This runs `mkdocs build` plus extra transformation of some files and adds
|
||||
symlinks (see `CMakeLists.txt` for the exact steps).
|
||||
|
||||
Now you can start webserver for local testing
|
||||
|
||||
```
|
||||
build> mkdocs serve
|
||||
[server:296] Serving on http://127.0.0.1:8000
|
||||
[handlers:62] Start watching changes
|
||||
```
|
||||
|
||||
If you develop inside a Vagrant virtual machine, use a port that is forwarded
|
||||
to your host:
|
||||
|
||||
```
|
||||
build> mkdocs serve --dev-addr 0.0.0.0:8088
|
||||
[server:296] Serving on http://0.0.0.0:8088
|
||||
[handlers:62] Start watching changes
|
||||
```
|
||||
@@ -1,39 +0,0 @@
|
||||
# Documentation Pages
|
||||
|
||||
The [Nominatim documentation](https://nominatim.org/release-docs/develop/) is built using the [MkDocs](https://www.mkdocs.org/) static site generation framework. The master branch is automatically deployed every night on under [https://nominatim.org/release-docs/develop/](https://nominatim.org/release-docs/develop/)
|
||||
|
||||
To preview local changes, first install MkDocs
|
||||
|
||||
```
|
||||
pip3 install --user mkdocs
|
||||
```
|
||||
|
||||
If `mkdocs` can't be found after the installation, the $PATH might have not
|
||||
been set correctly yet. Try opening a new terminal session.
|
||||
|
||||
|
||||
Then go to the build directory and run
|
||||
|
||||
```
|
||||
make doc
|
||||
INFO - Cleaning site directory
|
||||
INFO - Building documentation to directory: /home/vagrant/build/site-html
|
||||
```
|
||||
|
||||
This runs `mkdocs build` plus extra transformation of some files and adds
|
||||
symlinks (see `CMakeLists.txt` for the exact steps).
|
||||
|
||||
Now you can start webserver for local testing
|
||||
|
||||
```
|
||||
build> mkdocs serve
|
||||
[server:296] Serving on http://127.0.0.1:8000
|
||||
[handlers:62] Start watching changes
|
||||
```
|
||||
|
||||
If you develop inside a Vagrant virtual machine:
|
||||
|
||||
* add port forwarding to your Vagrantfile,
|
||||
e.g. `config.vm.network "forwarded_port", guest: 8000, host: 8000`
|
||||
* use `mkdocs serve --dev-addr 0.0.0.0:8000` because the default localhost
|
||||
IP does not get forwarded.
|
||||
@@ -1,52 +0,0 @@
|
||||
# Setup Test Environment
|
||||
|
||||
To test changes and contribute to Nominatim you should be able to run
|
||||
the test suite(s). For many usecases it's enough to create a Vagrant
|
||||
virtual machine (see `VAGRANT.md`), import one small country into the
|
||||
database.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Nominatim supports a range of PHP versions and PHPUnit versions also
|
||||
move fast. We try to test against the newest stable PHP release and
|
||||
PHPUnit version even though we expect many Nominatim users will install
|
||||
older version on their production servers.
|
||||
|
||||
* 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/)
|
||||
|
||||
#### Ubuntu 20
|
||||
|
||||
sudo apt-get install -y phpunit php-codesniffer php-cgi
|
||||
pip3 install --user behave nose
|
||||
|
||||
#### Ubuntu 18
|
||||
|
||||
pip3 install --user behave nose
|
||||
|
||||
sudo apt-get install -y composer php-cgi php-cli php-mbstring php-xml zip unzip
|
||||
|
||||
composer global require "squizlabs/php_codesniffer=*"
|
||||
sudo ln -s ~/.config/composer/vendor/bin/phpcs /usr/bin/
|
||||
|
||||
composer global require "phpunit/phpunit=8.*"
|
||||
sudo ln -s ~/.config/composer/vendor/bin/phpunit /usr/bin/
|
||||
|
||||
|
||||
#### CentOS 7 or 8
|
||||
|
||||
sudo dnf install -y php-dom php-mbstring
|
||||
pip3 install --user behave nose
|
||||
|
||||
composer global require "squizlabs/php_codesniffer=*"
|
||||
sudo ln -s ~/.config/composer/vendor/bin/phpcs /usr/bin/
|
||||
|
||||
composer global require "phpunit/phpunit=^7"
|
||||
sudo ln -s ~/.config/composer/vendor/bin/phpunit /usr/bin/
|
||||
|
||||
## Run tests, code linter, code coverage
|
||||
|
||||
See `README.md` in `test` subdirectory.
|
||||
142
docs/develop/Testing.md
Normal file
142
docs/develop/Testing.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Nominatim Test Suite
|
||||
|
||||
This chapter describes the tests in the `/test` directory, how they are
|
||||
structured and how to extend them. For a quick introduction on how to run
|
||||
the tests, see the [Development setup chapter](Development-Environment.md).
|
||||
|
||||
## Overall structure
|
||||
|
||||
There are two kind of tests in this test suite. There are functional tests
|
||||
which test the API interface using a BDD test framework and there are unit
|
||||
tests for specific PHP functions.
|
||||
|
||||
This test directory is sturctured as follows:
|
||||
|
||||
```
|
||||
-+- bdd Functional API tests
|
||||
| \
|
||||
| +- steps Step implementations for test descriptions
|
||||
| +- osm2pgsql Tests for data import via osm2pgsql
|
||||
| +- db Tests for internal data processing on import and update
|
||||
| +- api Tests for API endpoints (search, reverse, etc.)
|
||||
|
|
||||
+- php PHP unit tests
|
||||
+- scenes Geometry test data
|
||||
+- testdb Base data for generating API test database
|
||||
```
|
||||
|
||||
## PHP Unit Tests (`test/php`)
|
||||
|
||||
Unit tests can be found in the php/ directory and tests selected php functions.
|
||||
Very low coverage.
|
||||
|
||||
To execute the test suite run
|
||||
|
||||
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 (`test/bdd`)
|
||||
|
||||
Functional tests are written as BDD instructions. For more information on
|
||||
the philosophy of BDD testing, see the
|
||||
[Behave manual](http://pythonhosted.org/behave/philosophy.html).
|
||||
|
||||
The following explanation assume that the reader is familiar with the BDD
|
||||
notations of features, scenarios and steps.
|
||||
|
||||
All possible steps can be found in the `steps` directory and should ideally
|
||||
be documented.
|
||||
|
||||
### General Usage
|
||||
|
||||
To run the functional tests, do
|
||||
|
||||
cd test/bdd
|
||||
behave
|
||||
|
||||
The tests can be configured with a set of environment variables (`behave -D key=val`):
|
||||
|
||||
* `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)
|
||||
* `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
|
||||
considerably but might lead to outdated errors for some
|
||||
changes in the database layout.
|
||||
* `KEEP_TEST_DB` - if true, the test database will not be dropped after a test
|
||||
is finished. Should only be used if one single scenario is
|
||||
run, otherwise the result is undefined.
|
||||
|
||||
Logging can be defined through command line parameters of behave itself. Check
|
||||
out `behave --help` for details. Also have a look at the 'work-in-progress'
|
||||
feature of behave which comes in handy when writing new tests.
|
||||
|
||||
### API Tests (`test/bdd/api`)
|
||||
|
||||
These tests are meant to test the different API endpoints and their parameters.
|
||||
They require a to import several datasets into a test database.
|
||||
See the [Development Setup chapter](Development-Environment.md#preparing-the-test-database)
|
||||
for instructions on how to set up this database.
|
||||
|
||||
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.
|
||||
|
||||
The official test dataset can always be downloaded from
|
||||
[nominatim.org](https://www.nominatim.org/data/test/nominatim-api-testdata.pbf)
|
||||
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
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
Then 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>
|
||||
|
||||
### DB Creation Tests (`test/bdd/db`)
|
||||
|
||||
These tests check the import and update of the Nominatim database. They do not
|
||||
test the correctness of osm2pgsql. Each test will write some data into the `place`
|
||||
table (and optionally `the planet_osm_*` tables if required) and then run
|
||||
Nominatim's processing functions on that.
|
||||
|
||||
These tests need to create their own test databases. By default they will be
|
||||
called `test_template_nominatim` and `test_nominatim`. Names can be changed with
|
||||
the environment variables `TEMPLATE_DB` and `TEST_DB`. The user running the tests
|
||||
needs superuser rights for postgres.
|
||||
|
||||
### Import Tests (`test/bdd/osm2pgsql`)
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user