Run JOSF in a GitLab pipeline

When it comes to automating tests for your software, JOSF provides a robust platform for building and managing test cases. However, to ensure that your tests are properly version-controlled and integrated into your CI/CD pipeline, it’s essential to manage your JOSF project within a source control platform like GitLab.

In this blog post, we’ll walk you through the steps to create a JOSF project and set it up with GitLab for efficient collaboration and continuous integration.

Step 1: Create an Empty GitLab Repository

Before you can integrate JOSF with GitLab, you’ll need to set up an empty repository where your test project will be stored. (If you already have a repository setup in Gitlab you can skip to step 2.)

Log In to GitLab:
- Access your GitLab account and navigate to your dashboard.
Create a New Repository:
- Click on the “New Project” button.
- Select “Create Blank Project” and provide a name for your repository, such as MyFirstJOSFprojectOnGitlab.
- Choose whether the repository should be public or private based on your needs.
- Leave the repository empty by unchecking the “Initialize repository with a README" option.
- Click “Create Project” to finalize the setup.
Obtain GitLab Repository Credentials:
- Once your repository is created, you’ll need the repository URL and credentials (username and personal access token or gitlab password) to allow JOSF to push the project files.

Step 2: Set Up JOSF to Work with GitLab

Now that your GitLab repository is ready, the next step is to configure JOSF to connect to this repository.

Open JOSF:
- Start JOSF on your local machine.
Configure GitLab Integration in JOSF:
- In your JOSF workspace, press “Add project > Import GIT project”.
- Enter the repository URL that you obtained from GitLab.
- Provide your GitLab username and the personal access token or your gitlab password.
- JOSF will use these credentials to push the project files to your GitLab repository.
- Press validate and choose a suitable project name.
- When prompted, provide your JOSF licence key.

Create the Test Project:
- After entering finishing the setup, JOSF will automatically create a new test project.
- Setup tests as you would do in a normal JOSF project.
Run Initial Tests Locally:
- Before integrating with GitLab, run your tests locally to ensure that everything works as expected. This step helps catch any issues early and ensures your test scripts are functional before committing to a repository.
- After finishing and being confident everything works, press sync now under the version control menu. This will push all created files by JOSF to your Gitlab repository.
Configure browser to be compatible with the pipeline:
- Before running the pipeline, the test browser needs some specific configuration to run properly.
- Open your JOSF preferences, and open the tab browsers.
- Click on the pencil next to headless chrome and add the following block to the arguments field:
  [ "--headless",
  "--remote-allow-origins=*",
  "--disable-extensions",
  "--disable-dev-shm-usage",
  "--no-sandbox" ]

Step 3: Setting Up CI/CD in GitLab

Integrating your JOSF project with GitLab’s CI/CD pipeline allows for automated testing whenever changes are pushed to the repository.

Create a .gitlab-ci.yml File:
- In your repository/project root, create a file named .gitlab-ci.yml. This file will define the scripts for your CI/CD pipeline. (The root of your project is found under “Project location“ in the JOSF preferences).
- Add the code contents of the snippet at the bottom of this blog to your .gitlab-ci.yml file.
Create an acces token for the Gitlab CI.
To get your results back into your local JOSF environment, the pipeline needs access to the repository for pushing the results. This has to be done with an personal acces token.
- Open the preferences under your profile picture in Gitlab.
- Navigate to Access tokens and press Add new token.
- Give the token a suitable name and select read and write repository.
- Copy the generated access token and navigate back to your repository.
- Navigate to Settings > CI/CD > Variables. And press Add Variable.
- Fill in the following fields: Visibility: Masked, Key: ACCESS_TOKEN & Value: Your copied accestoken.
- When these steps are followed your pipeline is ready to kick off.
Push .gitlab-ci.yml to GitLab:
- Press “Sync now” under the version control menu of JOSF to push the file to Gitlab.
Monitor the Pipeline:
- After pushing the .gitlab-ci.yml file, GitLab will automatically trigger the pipeline.
- You can monitor the pipeline’s progress under the Build > Jobs section of your GitLab project. Ensure that the test job runs successfully and investigate any failures to fix issues early.

Conclusion

By setting up your JOSF project within GitLab, you gain robust version control and the ability to integrate automated testing into your CI/CD pipeline. This setup not only streamlines your testing workflow but also ensures that your tests are consistently executed across different environments, catching potential issues before they reach production.

If you have any questions or need further assistance with JOSF and GitLab integration, feel free to contact us directly via JOSF@valori.nl Happy testing!

.gitlab-ci.yml

stages:
  - testphase

variables:
  JOSF_ZIP: "josf.zip"
  JOSF_DOWNLOAD_URL: "https://www.josf.nl/wp-content/releases/beta/JOSF-server-gitlab.zip"
  PLAYBOOK_NAME: "Testplaybook"
  GIT_USER_NAME: "Gitlab DevOps agent"
  GIT_USER_EMAIL: "JOSF-gitlab@valori.nl"
  GIT_BRANCH: "main"

default:
  image: ubuntu:latest

deploy_josf:
  stage: testphase
  script:
    # Accept failures to continue script
    - set +e

    # Download, unzip and install important virtual machine parts
    - apt-get update -qq && apt-get install -y wget unzip chromium openjdk-21-jre git -qq > /dev/null
    - wget -q -O "$JOSF_ZIP" "$JOSF_DOWNLOAD_URL"
    - unzip -q "$JOSF_ZIP"
    - wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add -
    - echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google-chrome.list
    - apt-get update -qq && apt-get install -y google-chrome-stable -qq > /dev/null


    # Start JOSF
    - cd "JOSF/api"
    - classes_dir="$CI_PROJECT_DIR/JOSF/action-packs"
    - classpath="josf-core.jar:$classes_dir/custom:$classes_dir/api:$classes_dir/selenese:$classes_dir/database"
    - java -cp "$classpath" io.vertx.core.Launcher -conf config.json > /dev/null &

    - echo "Waiting for JOSF to be online..."
    - |
      for i in {1..120}; do
        if wget -q --spider http://localhost:8090/api/version; then
          echo "JOSF is online!"
          break
        fi
        echo -n "."
        sleep 1
      done

    - cd ..

    # Execute Playbook
    - java -jar "cli/josf-cli.jar" -r playbook "'$PLAYBOOK_NAME'" browser "'Headless Chrome'" retryCount "'0'" projectPath "'$CI_PROJECT_DIR'" || true

    # Commit playbook results
    - git remote set-url origin "https://oauth2:${ACCESS_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
    - git config user.name "$GIT_USER_NAME"
    - git config user.email "$GIT_USER_EMAIL"
    - git add $CI_PROJECT_DIR/play-books/*
    - git commit -m "Commit pipeline playbook results [skip ci]"
    - git pull origin $branch
    - git push origin HEAD:$branch

  # Search for generated JUnit file & Logfiles and push these as artifacts
    - JUNIT_FILE=$(find . -name "*junit-report.xml")
    - echo "Found JUnit report $JUNIT_FILE"
    - mv "$JUNIT_FILE" "$CI_PROJECT_DIR/junit-report.xml"
    - mv "$CI_PROJECT_DIR/JOSF/api/logs/josf.log" "$CI_PROJECT_DIR/josf.log"

  artifacts:
    reports:
      junit: "**/*junit-report.xml"
    paths:
      - "$CI_PROJECT_DIR/josf.log"
  # Allow failure makes it possible to continue the pipeline even when testcases fail.
  # this is important to push all artifacts. The timeout will stop the pipeline after 75 minutes.
  allow_failure: true
  timeout: 75m