ReadyAPI: A Beginner’s Guide to Functional and API Testing

Integrating ReadyAPI into CI/CD Pipelines (Jenkins, GitHub Actions)

Reliable API tests in CI/CD ensure regressions are caught early. This guide shows two practical ways to run ReadyAPI tests automatically: using Jenkins (with the official plugin or TestEngine/testrunner) and using GitHub Actions (TestEngine or command-line testrunner). It includes prerequisites, recommended project setup, examples, license notes, reporting, and troubleshooting.

Prerequisites

• ReadyAPI project saved (composite project recommended for source control).
• ReadyAPI installation (or TestEngine) on the CI runner/agent, or access to a TestEngine service.
• Active ReadyAPI Test license available on the machine or via TestEngine.
• Source repo (Git) with the ReadyAPI project or pipeline configuration.
• Basic knowledge of Jenkinsfile or GitHub Actions workflows.

Project setup recommendations

• Use a composite project (includes external resources) to keep everything versioned.
• Parameterize environments using ReadyAPI Environments or custom properties for base URLs, credentials, timeouts.
• Tag test suites/test cases for selective runs (useful for quick smoke vs full runs).
• Externalize sensitive values and use CI secrets (do not hard-code passwords).
• Generate JUnit-compatible reports via testrunner for CI test reporting.

Option A — Jenkins

Two common approaches

1. Jenkins ReadyAPI Functional Testing plugin (official)
2. Command-line testrunner/TestEngine invoked from a pipeline

Using the ReadyAPI Jenkins plugin

• Install plugin: “ReadyAPI Functional Testing” (ID: soapui-pro-functional-testing).
• Configure a node/agent that has ReadyAPI installed and licensed for the same user Jenkins runs as.
• In the job, add the ReadyAPI build step and set:
  • Path to testrunner (testrunner.sh/testrunner.bat)
  • Path to ReadyAPI project (.xml or .zip)
  • Test Suite / Test Case (optional) or use tags
  • Environment name
  • Project password (if encrypted)
  • License auth method and any SLM fields if applicable
• Plugin publishes:
  • Printable PDF ReadyAPI Test Results
  • JUnit XML and HTML reports (seen in Jenkins Test Results)
• Pipeline (Declarative) example using plugin step (conceptual):

  Code
  Copy CodeCopied
  pipeline { agent any   stages {
  
   
  stage('ReadyAPI Tests') {   steps {     // Plugin configured via UI or use shell step to call testrunner     sh '"/opt/ReadyAPI/bin/testrunner.sh" -r -a -j -f"reports" -E"staging" /path/to/project.xml'   } } 
  }   post {
  always {   junit 'reports/*.xml'   archiveArtifacts artifacts: 'reports/**', allowEmptyArchive: true } 
  } } 
  
  (If using the plugin UI, configure fields there instead of shell.)

Using testrunner or TestEngine from Jenkins

• Prefer TestEngine for headless, scalable execution (runs ReadyAPI tests via REST) or use testrunner for direct execution.
• Steps:
  • Ensure testrunner or TestEngine is available on the agent.
  • Add a shell/batch step to call testrunner with flags for JUnit output, environment, and report folder:
    • Example:

      Code
      Copy CodeCopied
      /opt/ReadyAPI/bin/testrunner.sh -E “staging” -r -f reports -j -J -PmyProp=value /workspace/project.xml 

      Flags: -r (generate reports), -f (report folder), -j (create JUnit), -J (full console output), -P pass properties.

  • Publish JUnit results in Jenkins (Post-build action or junit step in pipeline).
  • Archive HTML/PDF reports as artifacts.

License considerations on Jenkins

• Run Jenkins agent under the same OS user that activated the ReadyAPI license or configure SLM credentials. The plugin and testrunner require an active license accessible to the running user.

Option B — GitHub Actions

Two approaches

1. Use TestEngine (recommended for headless/scalable runs, Docker deployment)
2. Use testrunner CLI on self-hosted runner or a runner with ReadyAPI installed

Using TestEngine with GitHub Actions

• Deploy TestEngine (container or service) with access to your ReadyAPI project artifacts.
• Workflow steps:
  • Checkout repo
  • Upload ReadyAPI project package to TestEngine or reference a repository-hosted artifact
  • Call TestEngine REST API to trigger a run (POST with project and parameters)
  • Download results or have TestEngine push results to storage/webhook
  • Upload artifacts and annotate PRs if desired
• Benefits: no license management on GitHub Actions runners; TestEngine handles execution and licensing.

Using testrunner on GitHub Actions

• Use a self-hosted runner with ReadyAPI installed and licensed, or pre-install ReadyAPI in a custom runner image (not supported on GitHub-hosted runners due to licensing).
• Example workflow snippet (conceptual):

  Code
  Copy CodeCopied
  name: ReadyAPI CI on: [push, pull_request] jobs:   run-readyapi:
  
   
  runs-on: self-hosted steps: - uses: actions/checkout@v4 - name: Run ReadyAPI tests   run: '/opt/ReadyAPI/bin/testrunner.sh -E "ci" -r -f reports -j -J ./project.xml' - name: Upload reports   uses: actions/upload-artifact@v4   with:     name: readyapi-reports     path: reports/ 
  
  
  

• Publish JUnit results with third-party actions or parse results to GitHub checks.

Reporting & Results

• Always produce JUnit XML for CI visibility (jenkins junit step, GitHub third-party actions).
• Archive full ReadyAPI HTML/PDF reports for debugging.
• Use tags to run subsets (smoke, regression) and map them to pipeline jobs or matrix builds.

Best practices

• Keep test runs fast in PRs (smoke subset); run full suite on main branch or nightly builds.
• Fail builds on test failures by returning non-zero exit from testrunner (default).
• Use environment-specific variables via CI secrets to avoid committing credentials.
• Retain artifacts for failed builds to aid debugging.
• Use test tags and property-driven configuration to reuse projects across environments.

Troubleshooting (quick)

• License not found: ensure Jenkins/GitHub self-hosted runner runs under the same user that activated the license or use TestEngine licensing.
• Missing resources: use composite projects so external files are included in source control.
• Large reports: compress or store externally (artifact storage or object store).
• CI permission issues: ensure runner has execute permissions for testrunner and read access to project files.

Example checklist before enabling CI integration

• Project converted to composite and committed
• Environments and properties parameterized
• Runner/agent has ReadyAPI or TestEngine available
• Licensing for ReadyAPI resolved (local user or TestEngine)
• Pipeline configured to run testrunner or call TestEngine
• JUnit reporting and artifact upload configured
• Secrets configured for credentials and not stored in repo

If you want, I can:

• Provide a ready-to-copy Jenkinsfile for your specific project layout, or
• Create a complete GitHub Actions workflow that calls TestEngine or testrunner using your repo paths and environment names.