Skip to content

Latest commit

 

History

History
328 lines (223 loc) · 11 KB

README.md

File metadata and controls

328 lines (223 loc) · 11 KB

Testing Lizmap

Installation

A docker configuration is provided to launch Lizmap into a container.

This Docker Compose project is using :

With Windows

  1. Install Docker
  2. Install Git
  3. Launch Git Bash as administrator (right-click, run as administrator), then in the new window...
# Create a directory for Git repositories
mkdir GIT
# Git clone Lizmap Web Client in this directory
cd GIT && git clone https://github.com/3liz/lizmap-web-client.git --config core.autocrlf=input
# Go to tests repository
cd lizmap-web-client/tests/
# Download Lizmap plugin for QGIS Server
# https://packages.3liz.org/pub/lizmap-qgis-plugin/master/lizmap-qgis-plugin.master.zip
# and unzip the content in `qgis-server-plugins/` directory
# Launch Lizmap Web Client with docker compose
docker compose --env-file .env.windows up
# You can now go to http://localhost:8130 and test

# Later, you can get the latest changes in Lizmap Web Client with:
git pull

With Linux

You must install Docker on your machine first. Then you should execute the run-docker script.

To launch containers for the first time, with your current user:

./lizmap-ctl clean
./run-docker build

Then:

./run-docker
./lizmap-ctl install
./qgis-projects/tests/load_sql.sh # to populate PostgreSQL database with testing data

Then, in your browser, go to http://localhost:8130/. (see below to change the port)

Optionally, you can set lizmap.local into your /etc/hosts, as well as othersite.local for some tests:

127.0.0.1 lizmap.local
127.0.0.1 othersite.local

Then, in your browser, go to http://lizmap.local:8130/. (see below to change the port)

To stop containers:

./run-docker stop

You may have to close connections to the postgresql database if you are using PgAdmin for example, before stopping containers.

Available commands

You can execute some commands into the PHP container or other containers, by using this command:

./lizmap-ctl <command>

Available commands :

  • clean: delete all files generated by the build process.
  • reset: to reinitialize the application (with lizmap data stored into Postgresql)
  • reset-sqlite: to reinitialize the application (with lizmap data stored into sqlite)
  • composer-update and composer-install: to update PHP packages
  • clean-tmp: to delete temp files
  • install: to launch the Jelix installer
  • script: to launch lizmap command line like wmts
  • docker-exec : exec command into the php container
  • shell and shell-root : to enter into the php container
  • ldap-reset to reset the ldap content, and ldap-users to store some users for tests
  • psql to enter into the interactive command line of postgresql (psql)
  • redis-cli to enter into the interactive command line of Redis (redis-cli)
  • phpstan to launch PHP code quality tool phpstan

Accessing to Postgresql

If you want to use pgAdmin or any other postgresql client, access credentials from your computer are:

  • host: localhost
  • port: 8132 (see below to change the port)
  • database: lizmap
  • user: lizmap
  • password: lizmap1234!

However, you must not indicate these credentials in your QGIS projects for tests, because host and port are different when accessing from your computer, and when accessing from one of the containers, like QGIS or lizmap.

A postgresql service named lizmapdb is configured in containers. So you must use it as access parameter in your QGIS projects, with the database name lizmap.

In order to set the service from QGIS Desktop, you must create the file ~/.pg_service.conf and put these parameters in it:

[lizmapdb]
host=localhost
port=8132
user=lizmap
password=lizmap1234!

Admin User Account Setup

Default admin credentials are admin/admin, to modify it, set these variables in your environment, default values are provided in run-docker :

  • LIZMAP_ADMIN_LOGIN: Login of the admin user
  • LIZMAP_ADMIN_EMAIL: Email address of the admin user, it will be used by the password reset process.
  • LIZMAP_ADMIN_DEFAULT_PASSWORD_SOURCE: The password source to user for the admin user, it can either be:
    • __reset: It will initiate a password reset process. An email will be sent to LIZMAP_ADMIN_EMAIL with a link to choose a new password.
    • __random: Will set a random password that will be report into the command line (see docker logs to access it).
    • /path/to/pass/file: The path to a file containing your password. The file must be used as a volume for docker to access it.

Setting port numbers for services

You can modify port to access to the web server, the postgresql server or QGIS Server, by creating some environment variable, LZMWEBPORT, LZMPGPORT or LZMQGSRVPORT.

Example:

export LZMPGPORT=8150
export LZMWEBPORT=8151
export LZMQGSRVPORT=8152

./run-docker up -d

# you can then open browser at http://localhost:8151/

Changing PHP, postgresql and QGIS versions

You can change the version of some softwares to use, by setting some environment variables:

  • PHP_VERSION to set the PHP version
  • LZMQGSRVVERSION to set the QGIS version
  • LZMPOSTGISVERSION to set the PostgreSQL/PostGIS version (the format is X-Y where X is the major version of postgresql, and Y the major version of PostGIS)

You must set these (optional) environment variables, before building the stack.

export PHP_VERSION=8.2
export LZMQGSRVVERSION=3.24
export LZMPOSTGISVERSION=14-3
./run-docker build

Running different docker stack for each branch

By default, name of containers are different for each branch, so you can build and run a docker stack for each branch of the repository. Name of containers are made with the name of the current branch. You set a different name by creating an environment variable LZMBRANCH before running run-docker or lizmap-ctl.

Example:

export LZMBRANCH=another-name

./run-docker build
./run-docker up -d
./lizmap-ctl reset
# etc...

Port to access to the postgresql server and the nginx server are the same on each branch, by default. So if you want to run different stack at the same time, you will have some error. You must then change the port. See above.

Automatic PHP tests

The units directory contains some unit tests.

To launch PHP tests:

  • Launch the lizmap application as indicated above.
  • launch ./lizmap-ctl unit-tests

Automatic JavaScript tests

The js-units directory contains some unit tests.

In the root directory :

  • Run npm install to install Mocha
  • npm run js:test to run the JavaScript unit tests

Testing data

You must execute tests/qgis-projects/tests/load_sql.sh to populate PostgreSQL database with testing data.

Automatic End-to-End tests

First add testing data as explained above.

The end2end directory contains some end-to-end tests made for Cypress and Playwright.

In the root directory, npm install to install Cypress and Playwright.

Cypress

You can then :

  • execute npm run cy:open to open Cypress window.
  • select the target browser then click one of the integration tests or 'Run n integration specs' to run all.

or

  • execute npm run cy:test to automatically open Cypress window and run tests in Electron browser.

You can also use GNU Parallel to parallelize Cypress tests execution on 8 cores for example:

find cypress/integration/ -name '*.js' | parallel -j8 --group npx cypress run --spec {}

Output colors can be kept with --tty parameter, but it won't work with --group which is useful to not mix outputs from different tests.

Playwright

You have to install the browsers with npx playwright install (only the first time or after an update) You can then :

  • npx playwright test --ui --project=chromium to open a UI as in Cypress which ease testing
  • npx playwright test to execute all tests with all browsers
  • npx playwright test --grep @readonly --workers 4 to run tests with 4 workers for tests which are read-only
  • npx playwright test --project=chromium to execute all tests with the Chromium browser
  • npx playwright test --project=chromium --grep-invert "test_a|test_b" to execute all tests but "test_a" and "test_b" with the Chromium browser
  • npx playwright test mytest.spec.js --project=chromium to execute one test with the Chromium browser
  • npx playwright test mytest.spec.js --project=chromium --debug to execute one test with the Chromium browser in debug mode
  • other command line : https://playwright.dev/docs/intro#command-line

You can also install the handy Playwright extension on VSCode.

Writing tests

A tests doing only a read-only on Lizmap must be tagged as @readonly, otherwise, it must be tagged @write.

Artifacts

When GitHub Action is failing, all screenshots and downloaded files are uploaded in an ZIP. It's available in the CI Summary page of the CI job, with a zip called cypress-screenshots.zip.

Mouse coordinates

In Firefox, you can enable and use the measuring tool.

You need to be sure to use the same viewport size as Cypress : 1280 * 800 DPR 1 or Playwright : 900 * 650 DPR 1. We suggest you to save those configurations in Settings => Emulated Devices as Cypress or Playwright.

In Cypress, to click on the map, it's recommended to use the cy.mapClick(x,y) function using coordinates

Manual tests

First add testing data as explained above.

Put your projects into tests/qgis-projects/tests/ (replace tests by the name of your choice), and then you can declare tests projects into the admin page of Lizmap, or in its var/config/lizmapConfig.ini.php.

To test CORS, you can load http://othersite.local:8130, click on the buttons, and check the JS console for errors.

ESLint

Eslint can be run if you're located in assets/.

# Run eslint without fixing issues
npm run pretest

# Run eslint and fix issues
npm run pretest:fix

Using LDAP

Into lizmap/var/config/localconfig.ini.php:

  1. set ldapdao.access=2 into the modules section
  2. set driver=ldapdao into the coordplugin_auth section
  3. launch lizmap-ctl install

Be sure there are users into the ldap: execute lizmap-ctl ldap-users. It should show a list of users (Jane and John). If there are not present, launch lizmap-ctl ldap-reset.

You should then be able to connect yourself into lizmap with login jane (password: passjane) or login john (password: passjohn).

Using Redis for cache

Into lizmap/var/config/lizmapConfig.ini.php, set cacheStorageType=redis into the services section.

Into lizmap/var/config/profiles.ini.php, uncomment parameters into the jcache:qgisprojects section.

You can inspect the content of Redis with lizmap-ctl redis-cli.