Run JOSF in a GitHub 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 GitHub.

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

Step 1: Create an Empty GitHub Repository

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

Log In to GitHub:
- Access your GitHub account and navigate to the home page.
Create a New Repository:
- Click on the “New” button in the left drawer.
- Pprovide a name for your repository, such as MyFirstJOSFprojectOnGitHub.
- 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 Repository” to finalize the setup.
Obtain GitHub Repository Credentials:
- Once your repository is created, you’ll need the repository URL and credentials (username and personal access token or GitHub password) to allow JOSF to push the project files.

Step 2: Set Up JOSF to Work with GitHub

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

Open JOSF:
- Start JOSF on your local machine.
Configure GitHub Integration in JOSF:
- In your JOSF workspace, press “Add project > Import GIT project”.
- Enter the repository URL that you obtained from GitHub.
- Provide your GitHub username and the personal access token or your GitHub password.
- JOSF will use these credentials to push the project files to your GitHub 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 GitHub, 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 GitHub 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 GitHub

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

Create a .GitHub-ci.yml File:
- In your repository, create the folders: .github/workflows and create a file named ci.yml placed in the directory. This file will define the configuration for your CI/CD pipeline.
- Add the code that’s displayed at the bottom of this blogpost to your CI file.
Push .GitHub-ci.yml to GitHub:
- Press “Sync now” under the version control menu in JOSF to push the file to GitHub.
Monitor the Pipeline:
- After pushing the .github/workflows/ci.yml file, GitHub will automatically trigger the pipeline.
- You can monitor the pipeline’s progress in your GitHub repository under the Actions > All workflows section of your GitHub project. Ensure that the test job runs successfully and investigate any failures to fix issues early.

Conclusion

By setting up your JOSF project within GitHub, 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 GitHub integration, feel free to contact us directly via JOSF@valori.nl Happy testing!

CI.yml file:

name: Deploy JOSF

on:
  push:
    branches:
      - main
      - master
  workflow_dispatch:

env:
  JOSF_ZIP: "josf.zip"
  JOSF_DOWNLOAD_URL: "https://www.josf.nl/wp-content/releases/JOSF-server.zip"
  PLAYBOOK_NAME: "Testcase"
  GIT_USER_NAME: "GitHub DevOps agent"
  GIT_USER_EMAIL: "JOSF-github@valori.nl"

jobs:
  deploy_josf:
    runs-on: ubuntu-latest
    timeout-minutes: 75

    permissions:
      contents: write  

    steps:
      # Checkout the repository
      - name: Checkout code
        uses: actions/checkout@v2

      # Install necessary dependencies
      - name: Install Dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y wget unzip

      # Set up Java and dependencies
      - name: Set up Java21
        uses: actions/setup-java@v3
        with:
          distribution: temurin
          java-version: 21
      
      # Set up Chrome and dependencies
      - name: Set up Chrome
        uses: browser-actions/setup-chrome@v1
        with:
          chrome-version: 128
          install-chromedriver: true
    
      - name: Download and Unzip JOSF
        run: |
          wget -q -O "$GITHUB_WORKSPACE/josf.zip" "$JOSF_DOWNLOAD_URL"
          unzip -q "$GITHUB_WORKSPACE/josf.zip"
        shell: bash
        
      # Start JOSF
      - name: Start JOSF
        run: |
          classes_dir="${GITHUB_WORKSPACE}/JOSF/action-packs"
          classpath="${GITHUB_WORKSPACE}/JOSF/api/josf-core.jar:$classes_dir/custom:$classes_dir/api:$classes_dir/selenese:$classes_dir/database"
          java -cp "$classpath" io.vertx.core.Launcher -conf "{\"http.port\": 8090,\"http.connection.timeout\": 60000,\"http.socket.timeout\": 60000,\"showObjectTimeout\": 7,\"pageLoadTimeout\": 10,\"setScriptTimeout\": 15,\"actionPackPath\": \"${GITHUB_WORKSPACE}/JOSF/action-packs\",\"webappPath\": \"${GITHUB_WORKSPACE}/JOSF/api/josf-app\"}" &
          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

      - name: Execute playbook
        run: java -jar "${GITHUB_WORKSPACE}/JOSF/cli/josf-cli.jar" -r playbook "'$PLAYBOOK_NAME'" browser "'Headless Chrome'" retryCount "'0'" projectPath "'.'"
        continue-on-error: true

      # Commit playbook results
      - name: Commit Playbook Results
        run: |
          ls -R
          git remote set-url origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
          git config user.name "$GIT_USER_NAME"
          git config user.email "$GIT_USER_EMAIL"
          git add "${GITHUB_WORKSPACE}/play-books/"* || true
          git commit -m "Commit pipeline playbook results [skip ci]" || echo "Nothing to commit"
          git pull origin ${{ env.GIT_BRANCH }} || true
          git push origin HEAD:${{ env.GIT_BRANCH }} || true
        env:
          GIT_BRANCH: ${{ github.ref_name }}

      # Search for generated JUnit file and push these as artifacts
      - name: Find and Move JUnit Report
        run: |
          JUNIT_FILE=$(find . -name "*junit-report.xml" -print -quit)
          if [[ -n "$JUNIT_FILE" ]]; then
            echo "Found JUnit report $JUNIT_FILE"
            mv "$JUNIT_FILE" "${GITHUB_WORKSPACE}/junit-report.xml"
          else
            echo "JUnit report not found!"
          fi

      # Upload artifacts
      - name: Upload JUnit Report
        uses: actions/upload-artifact@v3
        with:
          name: junit-report
          path: ${{ github.workspace }}/junit-report.xml
          if-no-files-found: ignore

      - name: Upload JOSF log
        uses: actions/upload-artifact@v3
        with:
          name: josf-log
          path: ${{ github.workspace }}/JOSF/api/josf.log
          if-no-files-found: ignore