From 674c627a7c853c6bf0119fcc5ee93bc78c9d9f34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Chlup?= Date: Fri, 7 Jul 2023 15:33:51 +0200 Subject: [PATCH] test: Update README --- test/README.md | 104 +++++++++++++++++++------------------------------ 1 file changed, 41 insertions(+), 63 deletions(-) diff --git a/test/README.md b/test/README.md index 20efda3eb..486019ef4 100644 --- a/test/README.md +++ b/test/README.md @@ -1,23 +1,46 @@ -# tomcat_mod_cluster -Tomcat9 image with mod_cluster enabled. -Start Apache Httpd with mod cluster enabled. +# Running tests + +There are several tests within the repository. Some common tests are within the root directory, more specialized tests +live within their own subdirectories. All tests can be run by a single shell script `testsuite.sh`. The script itself +is a bit parametrized so that you can influence the duration of testing. Upon invocation, the script outputs values of +its parameters. You can change the value by passing the environment variable of the same name with a desired value. + +You can also run the individual testsuites by yourself, just execute the corresponsing script. + +You might find useful `includes` directory, especially `common.sh` script that contains shared functions for the tests +(mainly for controlling container images, see the section below). + +You should be able to check tests results based on the `$?` as usual so that you can use it in your scripts and automations. + +## Test images -Make sure you have checkout and build mod_cluster in sub directory at the same level you checkout mod_proxy_cluster. +If you use the main `testsuite.sh` script, you don't have to worry about this too much. Just make sure that you have checked +out and built [mod_cluster](https://github.com/modcluster/mod_cluster) in sub directory at the same level you checked out this +repository. -There are two variables worth setting: `APACHE_BASE` which is by default set to `/usr/local/apache` and which should -correspond to the path where apache is present, then `IMG` which is set by default to -`quay.io/${USER}/tomcat_mod_cluster`. +Also, if you use `podman` instead of `docker`, make sure you have `podman-docker` package installed (tests are using `docker`). -If your setup differs, set those variables to appropriate values simply by running `export APACHE_BASE=/your/path`. +If you don't want to use quay.io, just set `IMG` and `HTTPD_IMG` variables to docker, local repository or some other service. -## Building and pushing the image +### httpd_mod_cluster -You can build the image by running +There are two types of images we use in tests. The first one is the httpd image with mod_proxy_cluster. Its Dockerfile can +be found in `httpd` subdirectory and you can create it (as tests do) with the `httpd_create` function. All functions with +the prefix `httpd_` are using this image. + +### tomcat_mod_cluster + +The second image is a Tomcat image with mod_cluster enabled. Its Dockerfile is in the test root directory and tests use +`tomcat_create` function. As for httpd, all functions orking with tomcat image are prefixed `tomcat_`. + +#### Building and pushing the image + +You can build the images manually or using included Makefiles. For tomcat, you can built the image by running ``` make docker-build ``` -and then push it by +and then push it to quay.io by ``` make docker-push @@ -25,13 +48,12 @@ make docker-push Do not forget to log into quay.io before you run those commands. You can log in using `docker login quay.io`. -If you use `podman` instead of `docker`, you can use `podman-docker` package if it is available for you platform. -## Running the image +#### Running the image ``` -docker run --network=host -e tomcat_port=[port1] -e cluster_port=[port3] [image] +docker run --network=host -e tomcat_port=[port] -e cluster_port=[port] [image] Or -docker run --network=host -e tomcat_ajp_port=[port1] -e cluster_port=[port3] [image] +docker run --network=host -e tomcat_ajp_port=[port] -e cluster_port=[port] [image] # You can also add the variable -e tomcat_shutdown_port=true if u want to have a shutdown port ``` @@ -40,17 +62,10 @@ To load webapps into the container: docker cp webapp.war :/usr/local/tomcat/webapps/ ``` -# mod_cluster_tests -Tests can be run by invoking `make tests` or manually by running `sh tests.sh` but in that case -make sure you have exported the IMG variable as described above. - -The docker image should be build and you might push it before, make sure you have exported the IMG variable. -``` -export IMG=quay.io/${USER}/tomcat_mod_cluster -``` -# Testing websocket +## Testing websocket Using com.ning.http.client.ws.WebSocketTextListener -To be able to run the test please use https://github.com/jfclere/httpd_websocket just build it: +To be able to run `maintests.sh` successfully, please check out https://github.com/jfclere/httpd_websocket +and build it: ``` git clone https://github.com/jfclere/httpd_websocket cd https://github.com/jfclere/httpd_websocket @@ -66,44 +81,7 @@ run the groovy stuff java -jar target/test-1.0.jar ``` -*NOTE: You'll probably need an older JAVA version – version 11 should be ok. You can change it via JAVA env variable.* - -# Running tests -You need an Apache httpd with the mod_cluster.so installed and running. You can run it in docker -- checkout the `httpd/` -subdirectory or simply run `make setup-httpd`. You should have following piece in httpd.conf/mod_proxy_cluster.conf: - -``` -LoadModule cluster_slotmem_module modules/mod_cluster_slotmem.so -LoadModule manager_module modules/mod_manager.so -LoadModule proxy_cluster_module modules/mod_proxy_cluster.so - -ServerName localhost -Listen 6666 -ManagerBalancerName mycluster -EnableWsTunnel -WSUpgradeHeader "websocket" - - - Require ip 127.0.0.1 - - - KeepAliveTimeout 300 - MaxKeepAliveRequests 0 - - EnableMCPMReceive - - Require ip 127.0.0.1 - - -``` - -Make sure you disable `mod_proxy` module. - -You can run tests running `sh tests.sh`. There are a few variables by which you can influence the duration/number of -repetitions (those are printed out with their respective values right after executions starts). - -If tests fail or you interupt them, make sure that docker tomcat container that were created are removed first -(you need to run `docker container stop ` and `docker container rm `). +*NOTE: You might need an older JAVA version – version 11 should be ok. You can change it via JAVA env variable.* # Testing with miniserver There is also a python script that can be run to check mod_proxy_cluster. You can find it within `includes` directory