QAPI Integration for Java Microservices

Seer lets you integrate your Java Microservices with the API Test Suite on QAPI and helps you find out which API tests are impacted based on the code changes

Pre-requisites You'll Need 📋

Before you unlock this continuous testing magic, ensure you have:

• A GitHub Repository: Where your Java API code and OpenAPI specifications reside.

• Permissions: You'll need admin access to your GitHub repository to set up secrets and workflows.

---

🔐 Step 1: Generate a GitHub Personal Access Token (PAT)

To allow SeeR (via the QAPI integration) to securely connect to your repository and monitor changes, you'll need to create a GitHub Personal Access Token (PAT). This token acts as a secure key for SeeR to interact with your GitHub repository.

1. Go to GitHub Settings: Navigate to your GitHub profile settings: Settings > Developer Settings > Personal Access Tokens > Tokens (classic).

2. Generate New Token: Click on "Generate new token (classic)".

3. Name Your Token: Give your token a descriptive name, like SeeR-QAPI-Java-integration.

4. Set Expiration: (Optional but recommended for security) Choose an expiration date. For continuous integration, "No expiration" is often used, but consider your organization's security policies.

5. Select Required Scopes: This is crucial! Ensure you select the following permissions:

   • repo ✔️ (Full control of private repositories)

   • workflow ✔️ (Read/write GitHub Actions workflows)

   • admin:repo_hook ✔️ (Control webhooks)

   • read:org ✔️ (Read organization-level metadata)

6. Generate and Copy: Click "Generate token". Immediately copy the token that appears! GitHub will not show it to you again, so keep it in a secure place.

Remember: Treat this token like a password! Keep it safe and never expose it publicly.

---

🚀 Step 2: Configure GitHub Workflow for Java Code Impact Monitoring

This step involves creating a GitHub Actions workflow file (code-impact.yml) in your repository. This file defines when and how SeeR's QAPI integration for Java-based impact analysis is triggered.

The example workflow below is configured to run automatically whenever a Pull Request (PR) is created, updated, or reopened, and that PR is proposing changes into your designated integration branch (e.g., develop, main, master, etc.). This ensures that every proposed change undergoes impact analysis before it's merged, catching potential issues early in the development cycle!

1. Navigate to your Repository: Go to your GitHub repository where your Java API code is stored.

2. Create Workflow Directory: If it doesn't exist, create a directory structure: .github/workflows/.

3. Create Workflow File: Inside the workflows directory, create a new file named code-impact.yml.

4. Paste Workflow Content: Copy and paste the following content into your code-impact.yml file.

name: Send Code Changes on Push

on:
  push:
    branches:
      - master
    paths:
      - 'QyrusEcommerceJavaBackend/**'
  pull_request:
    branches:
      - master
    paths:
      - 'QyrusEcommerceJavaBackend/**'

jobs:
  send_code_changes:
    runs-on: ubuntu-latest

    env:
      MONITORED_PATH: QyrusEcommerceJavaBackend

    steps:
      # 1) Checkout with full history
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GH_TOKEN }}

      # 2) Compute commit range
      - name: Compute commit range & list
        id: range
        shell: bash
        run: |
          set -euo pipefail

          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
            FROM_SHA="${{ github.event.pull_request.base.sha }}"
            TO_SHA="${{ github.event.pull_request.head.sha }}"
          else
            FROM_SHA="${{ github.event.before }}"
            TO_SHA="${{ github.sha }}"
          fi

          echo "FROM_SHA=$FROM_SHA" >> $GITHUB_ENV
          echo "TO_SHA=$TO_SHA" >> $GITHUB_ENV

          COMMITS=$(git rev-list --reverse "${FROM_SHA}..${TO_SHA}")
          COMMITS_JSON=$(printf "%s\n" "$COMMITS" | jq -R -s -c 'split("\n")[:-1]')
          echo "commits=$COMMITS_JSON" >> $GITHUB_ENV

      # 3) Get code diff
      - name: Get code changes (diff)
        id: diff
        shell: bash
        run: |
          set -euo pipefail
          git diff "${FROM_SHA}..${TO_SHA}" -- "${MONITORED_PATH}" > changes.txt || true
          ENCODED_CHANGES=$(jq -Rs . < changes.txt)
          echo "encoded_changes=$ENCODED_CHANGES" >> $GITHUB_ENV

      
      # 4) Send diff and metadata to Impact Analyzer
      - name: Send changes to Analyze API
        shell: bash
        env:
          REPO_NAME: ${{ github.repository }}
          BRANCH_NAME: master
          COMMIT_IDS: ${{ env.commits }}
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
          ENCODED_CHANGES: ${{ env.encoded_changes }}
          USERNAME: ${{ secrets.USERNAME }}
          PASSWORD: ${{ secrets.PASSWORD }}
          WORKSPACE_NAME: ${{ secrets.WORKSPACE_NAME }}
          SUITE_NAME: ${{ secrets.SUITE_NAME }}
          ENVIRONMENT_NAME: ${{ secrets.ENVIRONMENT_NAME }}
          GATEWAY_URL: ${{ secrets.GATEWAY_URL }}
          GATEWAY_TOKEN: ${{ secrets.GATEWAY_TOKEN }}
        run: |
          set -euo pipefail
          BASE="${GATEWAY_URL%/}"
          ANALYZE_URL="${BASE}/seer-api-java-impact-analyzer-producer/v1/analyze-test-impact"

          PAYLOAD=$(jq -n \
            --arg repo "$REPO_NAME" \
            --arg branch "$BRANCH_NAME" \
            --arg commits "$COMMIT_IDS" \
            --arg changes "$ENCODED_CHANGES" \
            --arg username "$USERNAME" \
            --arg password "$PASSWORD" \
            --arg workspace_name "$WORKSPACE_NAME" \
            --arg suite_name "$SUITE_NAME" \
            --arg environment_name "$ENVIRONMENT_NAME" \
            '{
              repository: $repo,
              branch: $branch,
              commit_ids: $commits,
              changes: $changes,
              username: $username,
              password: $password,
              workspace_name: $workspace_name,
              suite_name: $suite_name,
              environment_name: $environment_name
            }')

          echo "Posting to $ANALYZE_URL"
          HTTP_CODE=$(curl -sS -o response.json -w "%{http_code}" \
            -X POST "$ANALYZE_URL" \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer ${GATEWAY_TOKEN}" \
            -H "GithubToken: $GH_TOKEN" \
            -d "$PAYLOAD")

          echo "Response Code: $HTTP_CODE"
          if [[ "$HTTP_CODE" -lt 200 || "$HTTP_CODE" -ge 300 ]]; then
            echo "❌ Error Response:"
            cat response.json
            exit 1
          fi

          echo "✅ Successfully sent changes"

---

Understanding the Workflow: A Step-by-Step Explanation for Java Projects

This workflow is meticulously designed to provide automated impact analysis on your Pull Requests for Java projects. Here's a clear breakdown of each critical section:

---

• name: Send Code Changes on Push:

  • This is the human-readable name of your workflow. It will appear in the GitHub Actions tab and indicates the workflow’s purpose: sending code changes when a push event happens.

---

• on: push:

  • This block defines when the workflow should run.

  • branches: - develop: This ensures the workflow triggers only when code is pushed to the develop branch. Replace develop with the branch you want to monitor, e.g., main, release, or staging.

  • paths: - 'QyrusEcommerceJavaBackend/**': This narrows the trigger to only run if changes occur within the specified folder (QyrusEcommerceJavaBackend). Update the path if your Java backend code resides elsewhere.

  • In summary: The workflow starts only when code changes are pushed to the develop branch and affect files under QyrusEcommerceJavaBackend/.

---

• jobs: send_code_changes:

  • Defines a single job named send_code_changes.

  • runs-on: ubuntu-latest: Runs on the latest GitHub-hosted Ubuntu runner.

---

• steps: The actions performed sequentially inside the job.

1. name: Checkout code

   • uses: actions/checkout@v3: Checks out the repository so the runner has access to the codebase.

   • with: fetch-depth: 0: Fetches the entire Git history instead of just the latest commit. This is important for calculating diffs between commits.

   • token: ${{ secrets.GH_TOKEN }}: Uses a GitHub token stored in repository secrets to authenticate checkout operations.

2. name: Extract Commit Details

   • Runs a shell script that:

     • Gets the total number of commits in the repository (TOTAL_COMMITS).

     • Gets the number of new commits in this push (NEW_COMMITS_COUNT).

     • Determines the appropriate commit range (COMMIT_RANGE).

     • Retrieves all commit hashes included in the push (COMMITS).

     • Converts commit IDs into JSON (COMMITS_JSON) for safe transport.

     • Stores them in an environment variable (commits) for later steps.

   ✅ Purpose: Captures commit IDs from the current push in a machine-readable format.

3. name: Get Code Changes

   • Uses git diff to generate a cumulative diff of all changes introduced in the current push.

   • Saves this diff to a file changes.txt.

   • Encodes the file contents into JSON format using jq -Rs . (to safely handle special characters).

   • Exports it as an environment variable (encoded_changes).

   ✅ Purpose: Collects all code changes as a clean, encoded JSON string.

4. name: Send changes to API

   • Prepares and sends the collected commit details + code changes to an external API for impact analysis.

   • Environment variables used:

     • API_URL: Target API endpoint (https://testui-qyrusbot.quinnox.info/...).

     • REPO_NAME: Repository name (provided by GitHub context).

     • BRANCH_NAME: Hardcoded as main (⚠️ you may want to align this with the develop branch defined earlier).

     • COMMIT_IDS: Commit IDs from earlier step.

     • ENCODED_CHANGES: Encoded diff of changes.

     • GH_TOKEN: GitHub token for authorization.

   • Constructs a JSON payload with jq -n containing:

     {
       "repository": "repo-name",
       "branch": "branch-name",
       "commit_ids": [ ... ],
       "changes": "..."
     }

   • Sends the payload via curl -X POST with the Authorization header.

   ✅ Purpose: Transmits all relevant commit + code change data to your analysis service for further processing.

---

🔑 Step 3: Set GitHub Secrets for QAPI Workflow Authentication

To ensure secure communication and avoid hardcoding sensitive information, you'll store all your tokens and QAPI configuration parameters as GitHub Secrets. The names of these secrets should match exactly what is expected by the QAPI service and referenced in the workflow's inputs defaults.

1. In your GitHub repository, navigate to: Settings > Secrets > Actions.

2. Click “New repository secret” for each of the following:

Secret Name	Example Value	Description
USERNAME	[email protected]	Your username for logging into QAPI.
PASSWORD	your-password-here	Your password for logging into QAPI.
GH_TOKEN	YOUR_GENERATED_PAT_FROM_STEP_1	The GitHub Personal Access Token you generated in Step 1. This token allows the qyrus-impact-analyzer-py action to create a GitHub Issue to report its findings.
WORKSPACE_NAME	MyTeamWorkspace	Your workspace name in QAPI.
SUITE_NAME	RegressionSuite	The name of the test suite in QAPI where your APIs are present.
ENVIRONMENT_NAME	Global Default	The environment name in QAPI for test execution. Use Global Default if you are unsure or if it's your default environment.
GATEWAY_URL	https://gateway-xx.qyrus.com	Collect the gateway URL from the Qyrus support team.
GATEWAY_TOKEN	Bearer XXXXX...	Collect the gateway token from the Qyrus support team.

---

✅ Done! SeeR (via QAPI) is Now Linked to GitHub!

Once these steps are complete:

• Automated tests will triggerbased on your workflow configuration (e.g., with every commit if you set on: push).

• You’ll see the reports and results directly as new GitHub Issues and in the GitHub Actions tab, providing immediate feedback on your code changes!

---

⚠️ Note

As of now, we support a repo with a maximum of 50 APIs.