{"id":20358114,"url":"https://github.com/irods/irods_testing_environment","last_synced_at":"2025-04-12T03:15:16.180Z","repository":{"id":37967206,"uuid":"402877240","full_name":"irods/irods_testing_environment","owner":"irods","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-31T18:55:29.000Z","size":261,"stargazers_count":8,"open_issues_count":64,"forks_count":15,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-12T03:15:13.301Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/irods.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-03T19:24:48.000Z","updated_at":"2025-03-31T18:55:34.000Z","dependencies_parsed_at":"2024-02-07T16:30:29.604Z","dependency_job_id":"85789ac2-4207-48cf-90c2-d0f94eba0a03","html_url":"https://github.com/irods/irods_testing_environment","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_testing_environment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_testing_environment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_testing_environment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irods%2Firods_testing_environment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/irods","download_url":"https://codeload.github.com/irods/irods_testing_environment/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248510001,"owners_count":21116130,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T23:25:26.651Z","updated_at":"2025-04-12T03:15:16.163Z","avatar_url":"https://github.com/irods.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iRODS Testing Environment\n\nThis repository provides a series of [Docker Compose](https://docs.docker.com/compose/) files which are intended for use in a test framework - which may or may not exist at the time of writing - for [iRODS](https://irods.org). \n\nFor each combination of supported OS platform/version and database type/version, there is a Compose project on which to run an iRODS deployment (*for testing*). The following OS platform Docker image tags are currently supported:\n - almalinux:8\n - rockylinux:8\n - rockylinux:9\n - debian:11\n - debian:12\n - ubuntu:20.04\n - ubuntu:22.04\n - ubuntu:24.04\n\nThe following database Docker image tags are currently supported (although not for all platforms):\n - postgres:14\n - postgres:16\n - mariadb:10.6\n - mariadb:10.11\n - mariadb:11.4\n - mysql:8.0\n - mysql:8.4\n\n## Requirements\n\nA recent-ish version of docker, python, and git are required to run this project.\n\nIt is *highly recommended* to use a `virtualenv` python virtual environment. You can set one up which installs the Minimum Requirements (see above) like this:\n```bash\nvirtualenv -p python3 ~/irods_testing_environment\nsource ~/irods_testing_environment/bin/activate\npip install docker-compose GitPython\npip freeze\n```\nCompare the output to `requirements.txt`.\n\n### A note about `docker-compose`\n\n`docker-compose` is being phased out by Docker and you may experience problems installing it via `pip`.\n\nIf this happens to you, try doing the following:\n\nClone the Docker Compose Git repository:\n```bash\ngit clone https://github.com/docker/compose\n```\n\nCheck out the latest tag which was still using the Python implementation:\n```bash\ncd compose\ngit checkout 1.29.2\n```\n\nAt this point, you can make the modifications needed to fix any problems you may encounter.\n\nOnce done, back out and pip install the local directory:\n```bash\ncd -\npip install ./compose\n```\n\n## Run iRODS Tests\n\nThere are 3 main ways to run the iRODS test suite:\n - Core tests: assumes catalog service provider is the only server\n - Topology tests: assumes 1 catalog service provider and 3 catalog service consumers\n - Federation tests: assumes 2 federated catalog service providers\n\nFor the following examples, we will use ubuntu:22.04 for the platform and postgres:14 for the database.\n\nTo run the full iRODS python test suite as defined in [core_tests_list.json](https://github.com/irods/irods/blob/2e82164055d1e6c2a3c64eedc534b45c9449df07/scripts/core_tests_list.json) against locally built iRODS packages, run this:\n```bash\npython run_core_tests.py --project-directory ./projects/ubuntu-22.04/ubuntu-22.04-postgres-14 \\\n                         --irods-package-directory /path/to/irods/package/directory\n```\nThis will run the entire python test suite on a single zone, serially. `--irods-package-directory` takes a path to a directory on the local host which contains packages for the target platform. This can be a full or relative path.\n\nIn order to speed this up, `--concurrent-test-executor-count` can be used to run the tests in parallel:\n```bash\npython run_core_tests.py --project-directory ./projects/ubuntu-22.04/ubuntu-22.04-postgres-14 \\\n                         --irods-package-directory /path/to/irods/package/directory \\\n                         --concurrent-test-executor-count 4\n```\nThe above line will stand up 4 identical zones and divide up the full list of tests in the iRODS python test suite as evenly as possible to run amongst the executors in parallel.\n\nTo run specific tests, use the `--tests` option. If no tests are provided via the `--tests` option (as shown above), the full iRODS python test suite will be run. Note: The python test suite can take 8-10 hours to run.\n```bash\npython run_core_tests.py --project-directory projects/ubuntu-22.04/ubuntu-22.04-postgres-14 \\\n                         --irods-package-directory /path/to/irods/package/directory \\\n                         --tests test_resource_types.Test_Resource_Compound test_rulebase test_iadmin\n```\nThe `--tests` option is compatible with `--concurrent-test-executor-count` as well. This will distribute the provided list of tests as evenly as possible amongst the concurrent executors to be run in parallel.\n\nFor topology tests:\n```bash\npython run_topology_tests.py provider \\\n                         --project-directory ./projects/ubuntu-22.04/ubuntu-22.04-postgres-14 \\\n                         --irods-package-directory /path/to/irods/package/directory\n```\nThe `provider` positional argument means that the test script will be running on the Catalog Service Provider. To run tests from the Catalog Service Consumer, use `consumer` instead.\n\nRunning the federation test suite is very similar. Note: The federation test suite is a separate python `unittest` file, so any `--tests` option used should be a subset of `test_federation`, although any tests can still run in this environment.\n```bash\npython run_federation_tests.py --project-directory ./projects/ubuntu-22.04/ubuntu-22.04-postgres-14 \\\n                               --irods-package-directory /path/to/irods/package/directory \\\n                               --tests test_federation.Test_ICommands.test_iquest__3466\n```\n\nThere is also a script to run the iRODS unit test suite. As with the others, the usual options apply. In order to run the full unit test suite as defined in [unit_tests_list.json](https://github.com/irods/irods/blob/2e82164055d1e6c2a3c64eedc534b45c9449df07/unit_tests/unit_tests_list.json) against locally built iRODS packages, run this:\n```bash\npython run_unit_tests.py --project-directory ./projects/ubuntu-22.04/ubuntu-22.04-postgres-14 \\\n                         --irods-package-directory /path/to/irods/package/directory\n```\nIf using the `--tests` option, please note that the unit tests use the Catch2 framework and the tests should match the names of the compiled executables.\n\nIf all else fails, each of these scripts includes a `--help` option which explains what each of the options do and how they are supposed to be used.\n\n## Run iRODS Plugin Tests\n\nFor purposes of CI, official iRODS Plugins have followed a convention of providing a \"test hook\" which will install the appropriate packages and run the appropriate test suite. If a test hook is provided in the prescribed way, any iRODS plugin test suite can be run in the testing environment.\n\nThe test hooks generally have the following requirements:\n\n - `irods_python_ci_utilities` is installed as a pip package\n - Path to local directory with built plugin packages (passed by `--built_packages_root_directory`)\n   - Inside the root directory, the `os_specific_directory` must exist and contain the appropriate packages\n     - The `os_specific_directory` must be named like this (image tag -\u003e directory name):\n       - ubuntu:20.04  -\u003e  `Ubuntu_20`\n       - ubuntu:22.04  -\u003e  `Ubuntu_22`\n       - rockylinux:9  -\u003e  `Rocky linux_9`\n       - debian:11     -\u003e  `Debian gnu_linux_11`\n - iRODS server is already installed and setup\n\nYour provided built packages should be in an identical directory or symlink following the naming convention above. The directory for your plugin packages might look something like this, where each platform has a directory which contains built packages for the target plugin:\n```bash\n$ ls -l /path/to/plugin/packages\ntotal 8\ndrwxr-xr-x 2 user user 4096 Apr 11 17:17 rocky-9\ndrwxr-xr-x 3 user user 4096 Apr 11 17:15 ubuntu-22.04\n```\n\nThe path for plugin packages used should be `/path/to/plugin/packages`. The test hook will be looking for a directory called by one of the names referenced above. You can create symlinks to the existing directories to satisfy the test hook, like this:\n```bash\n$ ls -l /path/to/plugin/packages\ntotal 8\ndrwxr-xr-x 2 user user 4096 Apr 11 17:17  rocky-9\nlrwxrwxrwx 1 user user    8 May 27 14:54 'Rocky linux_7' -\u003e rocky-9\nlrwxrwxrwx 1 user user   12 May 27 14:54  Ubuntu_22 -\u003e ubuntu-22.04\ndrwxr-xr-x 3 user user 4096 Apr 11 17:15  ubuntu-22.04\n```\n\nIn the future, these requirements will be relaxed so that creating a build-and-test workflow will not be as difficult.\n\n### How to run a test hook\n\nWe will use the curl microservice plugin as an example. The curl microservice plugin package is assumed to have been built for the target platform. The last argument provided to the script is the name of the git repository from which the test hook will be fetched.\n\n```bash\npython run_plugin_tests.py irods_microservice_plugins_curl \\\n                           --project-directory ./projects/ubuntu-22.04/ubuntu-22.04-postgres-14 \\\n                           --irods-package-directory /path/to/irods/packages/directory \\\n                           --plugin-package-directory /path/to/plugin/package/directories\n```\nAgain, `/path/to/plugin/package/directories` should be the path to the directory on the local host which contains directories for the target platform(s) following the naming convention outlined above. *Do not directly target the directory with the packages because the test hook is looking for the platform-specific directory itself.* This is not like `--irods-package-directory`, which is meant to point to a directory with the built packages directly inside.\n\nIf all else fails, this script includes a `--help` option which explains what each of the options do and how they are supposed to be used.\n\n## Stand up a Single Zone\n\nTo stand up the latest released version of iRODS in a Zone running on ubuntu:22.04 using a postgres:14 database to host the catalog, run the following:\n\n```bash\npython stand_it_up.py --project-directory ./projects/ubuntu-22.04/ubuntu-22.04-postgres-14\n```\n`--project-directory` can be a full or relative path to a directory in this repository with a `docker-compose.yml` file.\n\nTry this to make sure iRODS is running:\n```bash\n# expected output: \"/tempZone/home/rods:\"\ndocker exec -u irods ubuntu-2204-postgres-14_irods-catalog-provider_1 ils\n```\nTo stop and remove the containers:\n```bash\ndocker-compose --project-directory ./projects/ubuntu-22.04/ubuntu-22.04-postgres-14 down\n```\nNote: Compose project names default to the name of the directory which contains the `docker-compose.yml` project file. You may wish to specify a project name using `--project-name` in order to give your images and running containers a more recognizable name.\n\nIf all else fails, this script includes a `--help` option which explains what each of the options do and how they are supposed to be used.\n\n## Using static images with released iRODS versions\n\n`--use-static-images` enables building and running a Docker image with iRODS packages installed rather than downloading and installing the packages at runtime. This is useful for testing plugins against released versions of iRODS or for quickly reproducing issues on past versions.\n\nThis operates by using a couple of environment variables:\n\n - `dockerfile` - Selects the Dockerfile to build. Valid values are \"release.Dockerfile\", the default Dockerfile (\"Dockerfile\"), or an empty string (uses the default).\n - `irods_package_version` - Build argument used by the `release.Dockerfile` specifying the package version string for the iRODS package to download and install when building the image. Defaults to the latest released iRODS version on the target platform OS.\n\nThe reader is encouraged to use the provided scripts for standing up iRODS in containers when using this option because they will take care of these environment variables for you when used with the appropriate CLI options. Caution: If `dockerfile` and `irods_package_version` are defined in your environment, unexpected results could occur. Please unset these before running anything.\n\n## Using an ODBC driver\n\nTo use the MySQL database plugin, a MySQL ODBC driver file must be provided for use in the server. The scripts have the `--odbc-driver-path` option to specify an existing ODBC driver on the host machine.\n\nIf no `--odbc-driver-path` is provided, the appropriate ODBC driver for the given database version and OS will be downloaded to a temporary location on the host machine's local filesystem.\n\n## Execute Remotely\n\nAny of the above-mentioned scripts can be run on a remote Docker daemon using the ssh client. There are a few prerequisites:\n\n 1. The remote host must be running a Docker service which accepts remote requests\n 2. The remote host must use private key authentication\n 3. The local client must have `ssh-agent` running with the required keys added (see below for instructions)\n\nTo run the scripts above on a remote host, the `DOCKER_HOST` environment variable must be set to the remote IP address or hostname. The simplest way to do this is to set it before running the script like this:\n```bash\nDOCKER_HOST=\"remote-host-1.example.org\" python stand_it_up.py --project-directory ./projects/ubuntu-22.04/ubuntu-22.04-postgres-14\n```\n\n### Setting up the ssh client\n\nIn order to use the remote execution features of Docker, we need to set up an `ssh-agent` and add our authentication keys to the session.\n\nTo start an `ssh-agent` session, run the following (note: only tested with bash):\n```bash\neval $(ssh-agent -s)\n```\n\nTo add our private keys to the session, run `ssh-add` like this:\n```bash\nssh-add -k \u003cpath to private keys\u003e\n```\n\nSee `ssh-agent` and `ssh-add` man pages for more details.\n\nFor more information about remote execution on Docker, read this: [https://www.docker.com/blog/how-to-deploy-on-remote-docker-hosts-with-docker-compose/](https://www.docker.com/blog/how-to-deploy-on-remote-docker-hosts-with-docker-compose/)\n\n## View results with `xunit-viewer`\n\nAn `xunit-viewer` (https://github.com/lukejpreston/xunit-viewer) Dockerfile was added so that the JUnit XML reports can be viewed a little more easily.\n\nTo view test results, build the Docker image and run the container. Build the image like this:\n```bash\ndocker build -t xunit-viewer -f xunit_viewer.Dockerfile .\n```\n\nRun the viewer like this:\n```bash\ndocker run --rm -d \\\n    -v /path/to/test-results/logs:/results:ro \\\n    -p 3000:3000 \\\n    xunit-viewer -r /results -s\n```\n\nThis does the following:\n 1. Runs the `xunit-viewer1 container with the specified test results as a server on the default port.\n 2. Provides `/results` as a volume mount in the container. `/path/to/test-results` is the location of the test results as specified by the `--output-directory`/`-o` option for the test-running scripts.\n 3. Exposes port 3000 in the container as 3000 on the host. This is the default port for the `xunit-viewer` server.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firods%2Firods_testing_environment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Firods%2Firods_testing_environment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firods%2Firods_testing_environment/lists"}