Docker

You can setup a local instance of LimeSurvey with Docker Compose:

docker compose up -d

Now you can access LimeSurvey at port 8001.

Other LimeSurvey versions

By default, citric is tested against the latest 6-apache tag of LimeSurvey. If you want to use a different tag, you can specify it using the LS_IMAGE_TAG environment variable.

export LS_IMAGE_TAG=6.0.7+230515-apache
docker compose up -d

Integration tests

Docker Compose allows you to run integration tests against a local instance of LimeSurvey. First you’ll need to setup the environment variables:

export BACKEND=postgres
export LS_URL=http://localhost:8001/index.php/admin/remotecontrol
export LS_USER=iamadmin
export LS_PASSWORD=secret
export LS_VERSION=6-apache

Then you can run the tests with Nox:

nox -rs integration

Tip

You can use the --force-python option to run the tests on a different Python version from the default one (3.11).

Run integraton tests on a specific LimeSurvey version

export LS_IMAGE_TAG='6.0.7+230515-apache'

docker-compose -d

nox -rs integration

Run integraton tests against an unreleased LimeSurvey version

export DOCKER_BUILDKIT=0
export LS_VERSION=f148781ec57fd1a02e5faa26a7465d78c9ab5dfe
export LS_CHECKSUM=64aec410738b55c51045ac15373e2bc376e67cd6e20938d759c4596837ef6154

docker compose \
    -f docker-compose.yml \
    -f docker-compose.ref.yml up \
    -d

nox -rs integration

Where LS_VERSION is the commit SHA at the point of interest and LS_CHECKSUM is the SHA256 checksum of the .tar.gz archive of the project at that commit.

Tip

You can obtain the checksum by running:

wget https://github.com/LimeSurvey/LimeSurvey/archive/${LS_VERSION}.tar.gz
sha256sum ${LS_VERSION}.tar.gz

To test against such a version in CI, add the following to the job matrix:

- python-version: "3.11"
  os: "ubuntu-latest"
  session: "integration"
  limesurvey_version: "f148781ec57fd1a02e5faa26a7465d78c9ab5dfe"
  database: postgres
  experimental: true