diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..642bfee9 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +* text=auto + +*.dockerfile text eol=lf +*.sh text eol=lf diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77617a00..0b6a59cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ There are three levels of tests in this project: ### Python Unit Tests Python unit tests are located in `tests/python/` and run with pytest. ```sh -bash scripts/unittests.sh +bash scripts/python-tests.sh ``` ### JavaScript Unit Tests @@ -32,7 +32,7 @@ npm run test:js ``` Or on Windows: ``` -scripts\jstests.bat +scripts\javascript-tests.bat ``` To run in watch mode during development: ```sh @@ -54,50 +54,89 @@ All tests run automatically in GitHub Actions. They are triggered through the `. Results can be found at the `PR > checks > Upload robot logs`. The check will have a failed status if any tests has failed. -### Running Tests Locally -Perhaps you want to run the tests locally on your PC before pushing and waiting for the results from the GitHub actions. But this requires to install the required components in your native PC. In most cases this will not work as expected bacause of the differemt versions used. E.g. screenshots taken during the tests may differ, so that the tests will fail. +## Running Tests Locally - in a Docker Container +Run the tests locally on your PC before pushing and waiting for the results from the GitHub actions is always a good idea. But this requires to install the required components in your native PC. In some cases this will not work as expected bacause of the differemt versions used. E.g. screenshots taken during the tests may differ, so that the tests might fail. -Using a Docker container to run the tests in avoids both, messing up your local system with installing the required parts for the tests and getting failed tests due to your setup. +Using a Docker container to run the tests in avoids both, messing up your local system with installing the required parts for the tests and getting failed tests due to your setup. You just need to create the respective docker *images* by running the scripts as described below. -> Note: To use this methond there is no need to understand how Docker is working in detail. +> Note: To use this method there is no need to understand how Docker is working in detail. -To run all the tests in the Docker container in the same way as in the GitHub action: +### Python Unit Tests - in Docker Container +To run the python based tests in a docker container, execute: ```bash -bash scripts/run-in-test-container.sh bash scripts/robot-tests.sh +# Linux +bash scripts/docker/run-in-python-container.sh bash scripts/python-tests.sh +# Windows +C:> scripts\docker\run-in-python-container.bat bash scripts/python-tests.sh ``` + +### JavaScript Unit Tests - in Docker Container +To run the javascript based tests in a docker container, execute: +```bash +# Linux +bash scripts/docker/run-in-js-container.sh bash scripts/javascript-tests.sh +# Windows +C:> scripts\docker\run-in-js-container.bat bash scripts/javascript-tests.sh +``` + +### Robot Framework End-to-End Tests - in Docker Container +To run all the robot framework end-to-end tests in the Docker container in the same way as in the GitHub action: +```bash +# Linux +bash scripts/docker/run-in-robot-container.sh bash scripts/robot-tests.sh +# Windows +C:> scripts\docker\run-in-robot-container.bat bash scripts/robot-tests.sh +``` + To run a individual tests out of a suite: ```bash -bash scripts/run-in-test-container.sh robot -t "*version*" tests/robot/testsuites/00_cli.robot +# Linux +bash scripts/docker/run-in-robot-container.sh robot -t "*version*" tests/robot/testsuites/00_cli.robot +# Windows +C:> scripts\docker\run-in-robot-container.bat robot -t "*version*" tests/robot/testsuites/00_cli.robot ``` To run a single test suite in such a container: ```bash -bash scripts/run-in-test-container.sh robot tests/robot/testsuites/02_overview.robot +# Linux +bash scripts/docker/run-in-robot-container.sh robot tests/robot/testsuites/02_overview.robot +# Windows +C:> scripts\docker\run-in-robot-container.bat robot tests/robot/testsuites/02_overview.robot ``` > Note: It is not required to run any `pip install .` as this will be done by the script within the Docker container. #### How does it Work -Using the script requires that you are in the top-level directory of your working copy of the git repository. When using the script, the following happens: +Using the scripts require that you are in the top-level directory of your working copy of the git repository. When using the script, the following happens: - It is launching a new Docker container based on the image created (see below) - The current working directory is getting mounted to `/robotframework-dashboard` within the container -- In the container the working copy is installed by `pip install .` +- Depending on the script / image you use: + - The python based container contains all the setup required to run the python utit tests. + - The javascript based container contains all the setup of node.js and npm. The dependenies are getting installed automatically by `npm ci`. + - The robot based container contains the setup to run robot framework tests. Your current version of the dashboard from the working directory is installed by `pip install .` - The arguments you provide are executed as a bash command within the container - Due to the mounted working directory all the generated results can be accessed directly -- Once the command is completed, the running container is stopped and throw away +- Once the command is completed, the running container is stopped and thrown away #### Prerequisuites and Setup Running the tests in a Docker container requires a working docker installation. To check if your system has Docker installed check for the version: ```bash +# Linux $ docker -v Docker version 29.3.0, build 5927d80 +# Windows +C:> docker -v +Docker version 29.3.1, build c2be9cc ``` -If you have no Docker installer yet, follow the instructions to [Install Docker Engine](https://docs.docker.com/engine/install/) depending on your OS. One way is to use the *convenient script*: +If you have no Docker installer yet, follow the instructions to [Install Docker Engine](https://docs.docker.com/engine/install/) depending on your Linux OS. One way is to use the *convenient script*: ```bash $ curl -fsSL https://get.docker.com -o get-docker.sh $ sudo sh get-docker.sh ``` +If you are running on Windows, follow the instructions in [Install Docker Desktop on Windows](https://docs.docker.com/desktop/setup/install/windows-install/) + Once Docker is available verify if you are allowed to run docker commands. ```bash +# Linux $ docker ps permission denied while trying to connect to the docker API at unix:///var/run/docker.sock ``` @@ -107,21 +146,52 @@ $ sudo usermod -aG docker $USER ``` Don't forget to relogin to make the new group membership effective for your user. -#### Creating the the Docker Image -Once Docker is working you need to generate an *image*. The image can be easily created by: +#### Creating the Docker Images +Once Docker is working you need to generate an *image* for each type of tests (python, javascript, robot framework). +> Note: If you are not familar with docker, imagine an *image* as an ISO image of a Linux live-CD. It is an immutable preconfigured setup of an OS which can be used to run it without installing. + +The respective image can be easily created by one of the following: ```bash -$ bash scripts/create-test-image.sh +# Linux +$ bash scripts/docker/create-test-image.sh python +$ bash scripts/docker/create-test-image.sh js +$ bash scripts/docker/create-test-image.sh robot +# Windows +C:> scripts\docker\create-test-image.bat python +C:> scripts\docker\create-test-image.bat js +C:> scripts\docker\create-test-image.bat robot ``` -> Note: If you are not familar with docker, imagine an *image* as an ISO image of a Linux live-CD. It is an immutable preconfigured setup of an OS which can be used to run it without installing. The image is created in the following steps: +##### Image for Python Tests +For the python based one: +- It is based on the public image `ubuntu:latest`, as of writing 24.04 LTS. +- Installs the latest `python3` and `pip` from the distribution +- Installs all the project requirements to perform the tests from `requirements-dev.txt` +- Creates and go into the working directory `/robotframework-dashboard` + +##### Image for Javascript Tests +For the javascript based one: +- It is based on the public image `ubuntu:latest`, as of writing 24.04 LTS. +- Installs `curl` and the latest `node.js v24` from the distribution +- Creates and go into the working directory `/robotframework-dashboard` + +##### Image for Robot Framework Tests +For the robot framework based one: - It is based on the public image `mcr.microsoft.com/playwright:v1.56.0-jammy`, a *framework for Web Testing and Automation*. - which is based on `ubuntu:jammy` (ubuntu 22.04) - Installs the latest `python3-pip` from the distribution - Installs all the project requirements to perform the tests from `requirements-test.txt` - Initializes the `robotframework-browser` library - Creates a working directory `/robotframework-dashboard` -The image created is being used whenever a new docker container is launched by the `scripts/run-in-test-container.sh`. The image is static. To address changes in the `requirements-test.txt` you can recreate (and replace) the image by running the `create-test-image.sh` once again. + +The image created is being used whenever a new docker container is launched by the `scripts/docker/run-in-test-container.sh`. The image is static. To address changes in the `requirements-test.txt` you can recreate (and replace) the image by running the `create-test-image.sh` or `create-test-image.bat` once again. You can also force a complete requild of the image by: +```bash +# Linux +$ bash scripts/docker/create-test-image.sh python --no-cache +# Windows +C:> scripts\docker\create-test-image.bat python --no-cache +``` ## 📖 Docs diff --git a/scripts/create-test-image.sh b/scripts/create-test-image.sh deleted file mode 100644 index 5bbf6696..00000000 --- a/scripts/create-test-image.sh +++ /dev/null @@ -1,39 +0,0 @@ -#!/usr/bin/env bash -# -# Creates a docker image to used to run tests locally, without -# installing all the required tool into your system - -die() { echo "FATAL: $*"; exit 1; } - -docker -v || die "docker seems not being installed" - -docker build --tag test-dashboard -f - . < /dev/null || + die "Docker seems not being installed" +[ -n "$(docker images -q "$IMAGE" 2> /dev/null)" ] || + die "Docker image $IMAGE not found, please run 'scripts/docker/create-test-image.sh $1'" +[ -f robotframework_dashboard/robotdashboard.py ] || + die "you need to start this script from the toplevel directory of the robotframework-dashboard repository" + +USER_MAPPING="--user $(id -u):$(id -g)" +[ "$(uname -o)" = Msys ] && USER_MAPPING="" + +docker run -it --rm --ipc=host -v"/$(pwd)":/robotframework-dashboard $USER_MAPPING $IMAGE "${@}" diff --git a/scripts/docker/run-in-js-container.bat b/scripts/docker/run-in-js-container.bat new file mode 100644 index 00000000..4d451f8f --- /dev/null +++ b/scripts/docker/run-in-js-container.bat @@ -0,0 +1 @@ +@scripts\docker\run-in-container.bat js bash -c "npm ci; %*" diff --git a/scripts/docker/run-in-js-container.sh b/scripts/docker/run-in-js-container.sh new file mode 100644 index 00000000..e9230395 --- /dev/null +++ b/scripts/docker/run-in-js-container.sh @@ -0,0 +1,5 @@ +#!/usr/bin/env bash + +echo "Installing node.js dependencies and running '$*'" + +bash scripts/docker/run-in-container.sh js bash -c "npm ci; ${*}" diff --git a/scripts/docker/run-in-python-container.bat b/scripts/docker/run-in-python-container.bat new file mode 100644 index 00000000..9eb958c2 --- /dev/null +++ b/scripts/docker/run-in-python-container.bat @@ -0,0 +1 @@ +@scripts\docker\run-in-container.bat python %* diff --git a/scripts/docker/run-in-python-container.sh b/scripts/docker/run-in-python-container.sh new file mode 100644 index 00000000..641ffcba --- /dev/null +++ b/scripts/docker/run-in-python-container.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +bash scripts/docker/run-in-container.sh python "${@}" diff --git a/scripts/docker/run-in-robot-container.bat b/scripts/docker/run-in-robot-container.bat new file mode 100644 index 00000000..9f5f2fe5 --- /dev/null +++ b/scripts/docker/run-in-robot-container.bat @@ -0,0 +1,3 @@ +@ECHO OFF +ECHO Deploying current workingdirectory into the container and running "%*" +scripts\docker\run-in-container.bat robot /bin/bash -c "pip install .; export PATH=$PATH:~/.local/bin; %*" diff --git a/scripts/docker/run-in-robot-container.sh b/scripts/docker/run-in-robot-container.sh new file mode 100644 index 00000000..02044685 --- /dev/null +++ b/scripts/docker/run-in-robot-container.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash + +echo "Deploying current workingdirectory into the container and running" +echo " $*" +echo "" +bash scripts/docker/run-in-container.sh robot /bin/bash -c "pip install .; export PATH=\$PATH:~/.local/bin; ${*}" diff --git a/scripts/docker/test-dashboard-js.dockerfile b/scripts/docker/test-dashboard-js.dockerfile new file mode 100644 index 00000000..bedc0e05 --- /dev/null +++ b/scripts/docker/test-dashboard-js.dockerfile @@ -0,0 +1,24 @@ +# Base of the image is the latest ubuntu like 24.04 LTS +FROM ubuntu:latest + +RUN << FOE + # Install prereqs + apt-get update + + apt install -y curl +FOE + +RUN << FOE + # Download and install nvm: + curl -fsSL https://deb.nodesource.com/setup_24.x | bash - + apt install -y nodejs + + # Verify the Node.js version: + node -v # Should print "v24.14.1". + + # Verify npm version: + npm -v # Should print "11.11.0". +FOE + +# create a workspace directory, where we mount the repo into +WORKDIR /robotframework-dashboard diff --git a/scripts/docker/test-dashboard-python.dockerfile b/scripts/docker/test-dashboard-python.dockerfile new file mode 100644 index 00000000..7482fecf --- /dev/null +++ b/scripts/docker/test-dashboard-python.dockerfile @@ -0,0 +1,19 @@ +# Base of the image is the latest ubuntu like 24.04 LTS +FROM ubuntu:latest + +RUN << FOE + # install python + apt-get update + + apt-get install -y python3.12 python3 python-is-python3 python3-pip +FOE + +# we need the test requirements file withing the image to install them +COPY requirements-dev.txt /tmp/requirements-dev.txt +RUN << FOE + # Install requirements + pip3 install -r /tmp/requirements-dev.txt --break-system-packages +FOE + +# create a workspace directory, where we mount the repo into +WORKDIR /robotframework-dashboard diff --git a/scripts/docker/test-dashboard-robot.dockerfile b/scripts/docker/test-dashboard-robot.dockerfile new file mode 100644 index 00000000..6bee539a --- /dev/null +++ b/scripts/docker/test-dashboard-robot.dockerfile @@ -0,0 +1,20 @@ +# Base of the image is the playwright image for ubuntu 22.04 +FROM mcr.microsoft.com/playwright:v1.56.0-jammy + +# we need the test requirements to be withing the image to install them +COPY requirements-test.txt /tmp/requirements-test.txt +RUN << EOF + # Ensure pip is installed + apt-get update + apt-get install -y python3-pip + + # Install Robot Framework and Python dependencies + python3 -m pip install --upgrade pip + pip3 install -r /tmp/requirements-test.txt + + # Initialize Browser library + rfbrowser init +EOF + +# create a workspace directory, where we mount the repo into +WORKDIR /robotframework-dashboard diff --git a/scripts/run-in-test-container.sh b/scripts/run-in-test-container.sh deleted file mode 100644 index ece9c934..00000000 --- a/scripts/run-in-test-container.sh +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env bash - -IMAGE=test-dashboard - -die() { echo "FATAL: $*"; exit 1; } - -docker -v 2> /dev/null || - die "docker seems not being installed" -[ -n "$(docker images -q "$IMAGE" 2> /dev/null)" ] || - die "image $IMAGE not found, please run scripts/create-test-image.sh" -[ -d .git ] || - die "you need to start this script from the toplevel directory of the robotframework-dashboard repository" - -my_uid=$(id -u) -my_gid=$(id -g) - -if [ $# = 0 ]; then - echo "No arguments given, starting container with interactive terminal" - echo "Hint: don't forget to install the dashboard from the git repository in the container:" - echo " pip install . && export PATH=\$PATH:~/.local/bin" - echo "" - docker run -it --rm --ipc=host -v.:/robotframework-dashboard --user ${my_uid}:${my_gid} test-dashboard -else - echo "Deploying current workingdirectory into the container and running" - echo " $*" - echo "" - docker run -it --rm --ipc=host -v.:/robotframework-dashboard --user ${my_uid}:${my_gid} test-dashboard \ - /bin/bash -c \ - "pip install .; export PATH=\$PATH:~/.local/bin; ${*}" -fi diff --git a/tests/robot/resources/keywords/general-keywords.resource b/tests/robot/resources/keywords/general-keywords.resource index a67ce5d4..64e76c60 100644 --- a/tests/robot/resources/keywords/general-keywords.resource +++ b/tests/robot/resources/keywords/general-keywords.resource @@ -44,7 +44,7 @@ Generate Dashboard Log ${output} Remove Database And Dashboard - ${files} List Files In Directory path=${CURDIR}/../../.. + ${files} List Files In Directory path=${CURDIR}/../../../.. FOR ${file} IN @{files} IF ('.db' in $file or '.html' in $file) and not ('robotresults_' in $file or 'robotdashboard_' in $file) Remove File path=${file}