คู่มือติดตั้ง ReadyAPI Jenkins CI พร้อมทางเลือกที่ง่ายกว่า

สรุป

การรันการทดสอบ ReadyAPI ใน Jenkins สามารถทำได้ผ่านเครื่องมือบรรทัดคำสั่ง testrunner และปลั๊กอิน SmartBear Jenkins แต่ต้องติดตั้ง ReadyAPI บนเอเจนต์บิลด์และมักจะพบปัญหาในการตั้งค่าบ่อยครั้ง การรวม CI/CD ของ Apidog ทำงานผ่าน CLI ที่ติดตั้งด้วย npm ซึ่งไม่จำเป็นต้องใช้ซอฟต์แวร์เอเจนต์และไม่มีการคิดค่าไลเซนส์ต่อการรัน

💡

Apidog คือแพลตฟอร์มพัฒนา API แบบครบวงจรฟรี พร้อมด้วย CLI runner น้ำหนักเบาที่สามารถรวมเข้ากับ Jenkins, GitHub Actions และไปป์ไลน์อื่นๆ ได้โดยไม่ต้องมีใบอนุญาตเพิ่มเติม ทดลองใช้ Apidog ฟรี ไม่ต้องใช้บัตรเครดิต

ปุ่ม

บทนำ

การรวมการทดสอบ API เข้ากับไปป์ไลน์ CI/CD เป็นหนึ่งในสิ่งที่มีคุณค่าที่สุดที่ทีมทดสอบสามารถทำได้ การจับข้อผิดพลาด (regressions) ในทุก pull request ก่อนที่โค้ดจะเข้าสู่ staging หรือ production นั้นคุ้มค่ากับความพยายามในการตั้งค่า

ReadyAPI รองรับการรวมเข้ากับ Jenkins ผ่านกลไกสองอย่าง: เครื่องมือบรรทัดคำสั่ง testrunner และปลั๊กอิน SmartBear Jenkins อย่างเป็นทางการ ทั้งสองอย่างใช้งานได้ แต่ก็มีความซับซ้อนในตัวของมันเอง คู่มือนี้จะครอบคลุมถึงวิธีการตั้งค่า ReadyAPI กับ Jenkins ปัญหาทั่วไปที่คุณอาจพบ และวิธีการที่ Apidog ให้การรวมไปป์ไลน์แบบเดียวกันแต่มีค่าใช้จ่ายด้านโครงสร้างพื้นฐานน้อยกว่า

การตั้งค่า ReadyAPI ใน Jenkins: วิธีการใช้ testrunner

testrunner คือเอ็นจิ้นการประมวลผลบรรทัดคำสั่งของ ReadyAPI เมื่อ Jenkins ต้องการรันการทดสอบ ReadyAPI แบบ Headless มันจะเรียก testrunner พร้อมกับอาร์กิวเมนต์ที่ชี้ไปยังไฟล์โปรเจกต์

ข้อกำหนดเบื้องต้น:

ต้องติดตั้ง ReadyAPI บน Jenkins agent ทุกตัวที่รันการทดสอบ API นี่คือข้อกำหนดในการดำเนินงานที่สำคัญที่สุด หากคุณมี build agent ห้าตัวและการทดสอบ ReadyAPI รันบนตัวใดตัวหนึ่งในนั้น ทั้งห้าตัวจำเป็นต้องติดตั้ง ReadyAPI ซึ่งทำให้เกิด:

ภาระในการบำรุงรักษาการติดตั้งเมื่อ ReadyAPI อัปเดต
คำถามเกี่ยวกับใบอนุญาต: การติดตั้งเอเจนต์แต่ละตัวจำเป็นต้องมีใบอนุญาตเป็นของตัวเองหรือไม่? นโยบายการออกใบอนุญาต CI/CD ของ SmartBear แตกต่างกันไปตามสัญญา โปรดยืนยันกับทีมงานบัญชีของคุณ
ขนาดอิมเมจเอเจนต์ที่ใหญ่ขึ้นและเวลาเริ่มต้นที่นานขึ้นสำหรับเอเจนต์บนคลาวด์

คำสั่ง testrunner พื้นฐาน:

บน Linux/macOS:

/path/to/ReadyAPI/testrunner.sh \
  -r \
  -f /path/to/results \
  -s "TestSuiteName" \
  -c "TestCaseName" \
  /path/to/project.xml

บน Windows:

C:\ReadyAPI\testrunner.bat ^
  -r ^
  -f C:\results ^
  -s "TestSuiteName" ^
  -c "TestCaseName" ^
  C:\projects\project.xml

แฟล็กสำคัญของ testrunner:

-r: สร้างรายงาน XML ที่เข้ากันได้กับ JUnit
-f <directory>: ไดเรกทอรีสำหรับผลลัพธ์
-s <name>: รันชุดทดสอบที่ระบุ (ละเว้นเพื่อรันทั้งหมด)
-c <name>: รันกรณีทดสอบที่ระบุ (ละเว้นเพื่อรันทั้งหมด)
-e <environment>: ระบุสภาพแวดล้อมที่จะใช้
-P <name>=<value>: เขียนทับคุณสมบัติโปรเจกต์

ขั้นตอนใน Jenkins pipeline:

ใน Jenkinsfile:

stage('API Tests') {
  steps {
    sh '''
      /opt/readyapi/testrunner.sh \
        -r \
        -f ${WORKSPACE}/test-results \
        -e ${ENVIRONMENT} \
        ${WORKSPACE}/project.xml
    '''
    junit 'test-results/*.xml'
  }
}

ขั้นตอน junit จะเผยแพร่ผลลัพธ์ไปยัง Jenkins เพื่อให้ข้อผิดพลาดปรากฏในรายงานการบิลด์

การใช้ปลั๊กอิน SmartBear Jenkins

SmartBear มีปลั๊กอิน Jenkins สำหรับ ReadyAPI ซึ่งมีให้ใช้งานจากไดเรกทอรีปลั๊กอินของ Jenkins ปลั๊กอินนี้มี build step ใน Jenkins UI แทนที่จะต้องให้คุณเขียนคำสั่ง shell ด้วยตนเอง

วิธีการติดตั้ง:

ไปที่ Jenkins > Manage Jenkins > Plugin Manager
ค้นหา “SmartBear ReadyAPI Functional Testing”
ติดตั้งและรีสตาร์ท Jenkins

หลังจากติดตั้ง คุณจะต้องกำหนดค่าพาธการติดตั้ง ReadyAPI ในการตั้งค่าส่วนกลางของ Jenkins จากนั้นเพิ่มขั้นตอนการทดสอบ ReadyAPI ไปยังงานบิลด์ของคุณโดยเลือกจากเมนูแบบเลื่อนลงของ build steps

ปลั๊กอินจะจัดการการสร้างอาร์กิวเมนต์ให้คุณและรวมผลลัพธ์เข้ากับการรายงานการทดสอบของ Jenkins สำหรับทีมที่ชอบการกำหนดค่าผ่าน GUI มากกว่าสคริปต์ Groovy pipeline ปลั๊กอินนี้จะช่วยลดเวลาในการตั้งค่า

ข้อจำกัดของปลั๊กอิน: ปลั๊กอินนี้ผูกติดกับ Jenkins เวอร์ชันและ ReadyAPI เวอร์ชันเฉพาะ การอัปเดตปลั๊กอินจะช้ากว่าการเปิดตัว ReadyAPI และ Jenkins ทีมที่ใช้ ReadyAPI เวอร์ชันล่าสุดอาจพบปัญหาความเข้ากันได้ที่ต้องรอการอัปเดตปลั๊กอิน

ปัญหาทั่วไปของ Jenkins + ReadyAPI

Testrunner ค้างเมื่อเริ่มต้น. ReadyAPI เป็นแอปพลิเคชัน Java/Swing เมื่อถูกเรียกใช้งานแบบ Headless ใน CI บางครั้งมันจะพยายามเริ่มต้นส่วนประกอบ GUI ตั้งค่าตัวแปรสภาพแวดล้อม DISPLAY หรือใช้พารามิเตอร์ JVM -Djava.awt.headless=true หากคุณพบปัญหานี้

การตรวจสอบใบอนุญาตล้มเหลว. ReadyAPI ตรวจสอบใบอนุญาตเมื่อเริ่มต้น หาก CI agent ไม่สามารถเข้าถึงเซิร์ฟเวอร์ใบอนุญาตของ SmartBear ได้ (ซึ่งพบบ่อยในเครือข่ายองค์กรที่มีการจำกัดการเข้าถึง) การทดสอบจะล้มเหลวพร้อมข้อผิดพลาดเกี่ยวกับใบอนุญาตแทนที่จะเป็นข้อผิดพลาดในการทดสอบ คุณต้องกำหนดค่าการตั้งค่าเซิร์ฟเวอร์ใบอนุญาตแบบ floating หรือการออกใบอนุญาตแบบออฟไลน์

ข้อผิดพลาดหน่วยความจำไม่พอ. การตั้งค่า JVM heap เริ่มต้นใน testrunner นั้นค่อนข้างอนุรักษ์นิยม ชุดทดสอบขนาดใหญ่หรือโปรเจกต์ที่มีไฟล์ข้อมูลจำนวนมากอาจต้องปรับการตั้งค่า -Xmx แก้ไขไฟล์ testrunner.sh หรือ testrunner.bat เพื่อเพิ่ม heap:

-Xms128m -Xmx1024m

ปัญหาพาธของไฟล์โปรเจกต์. โปรเจกต์ ReadyAPI อ้างอิงไฟล์ภายนอก (แหล่งข้อมูล, สคีมา, สคริปต์) โดยใช้พาธ เมื่อรันใน CI พาธแบบ relative จะใช้งานได้ก็ต่อเมื่อไดเรกทอรีทำงานถูกตั้งค่าอย่างถูกต้อง พาธแบบ absolute ในไฟล์โปรเจกต์จะทำให้เกิดปัญหาเมื่อโปรเจกต์ย้ายระหว่างเครื่อง ใช้ project properties สำหรับพาธและตั้งค่าผ่านแฟล็ก -P เมื่อรัน

การทดสอบผ่านบนเครื่องแต่ล้มเหลวใน CI. มักเกิดจากความแตกต่างของสภาพแวดล้อม: ข้อมูลในไฟล์ภายนอกที่แตกต่างกัน, ค่าตัวแปรสภาพแวดล้อมที่แตกต่างกัน, หรือพาธที่ถูกฮาร์ดโค้ด ใช้คุณสมบัติ Environment ของ ReadyAPI พร้อมกับการเลือกสภาพแวดล้อมที่ชัดเจนในอาร์กิวเมนต์ -e ของ testrunner

การรวม Apidog กับ Jenkins: วิธีการที่ง่ายกว่า

CLI runner ของ Apidog ติดตั้งผ่าน npm และไม่จำเป็นต้องมีแอปพลิเคชันบนเดสก์ท็อปบน build agent

การติดตั้งบน Jenkins agent:

npm install -g apidog-cli

หรือในขั้นตอนไปป์ไลน์:

npm ci
# apidog-cli is in devDependencies

การรันการทดสอบใน Jenkinsfile:

stage('API Tests') {
  steps {
    sh '''
      apidog run \
        --collection ${WORKSPACE}/apidog-collection.json \
        --environment staging \
        --reporter junit \
        --reporter-junit-export ${WORKSPACE}/results/report.xml
    '''
    junit 'results/report.xml'
  }
}

ความแตกต่างที่สำคัญจาก ReadyAPI:

ไม่มีแอปพลิเคชันบนเดสก์ท็อปบนเอเจนต์ Apidog CLI เป็นแพ็กเกจ Node.js น้ำหนักเบา ติดตั้งได้ในไม่กี่วินาที ไม่ใช่หลายนาที ไม่มีปัญหาการเริ่มต้น GUI ไม่มีข้อกำหนดในการเชื่อมต่อเซิร์ฟเวอร์ใบอนุญาต

ไม่ต้องกังวลเรื่องใบอนุญาตต่อการรัน Apidog ไม่คิดค่าใช้จ่ายต่อการประมวลผล CI รันการทดสอบได้มากเท่าที่ไปป์ไลน์ของคุณต้องการในแต่ละวัน

การกำหนดค่าสภาพแวดล้อมผ่านตัวแปรสภาพแวดล้อมหรือแฟล็ก ส่งข้อมูลรับรองและ base URL เป็นตัวแปรสภาพแวดล้อมโดยตรงจาก Jenkins credentials store:

withCredentials([string(credentialsId: 'api-key', variable: 'API_KEY')]) {
  sh 'apidog run collection.json -e production --env-var "apiKey=${API_KEY}"'
}

การเปรียบเทียบกับ GitHub Actions:

สำหรับทีมที่ใช้ GitHub Actions ด้วย วิธีการของ Apidog ก็ใช้งานได้ง่ายเช่นกัน:

- name: Run API tests
  run: |
    npm install -g apidog-cli
    apidog run collection.json --environment staging
  env:
    API_BASE_URL: ${{ vars.STAGING_URL }}
    API_KEY: ${{ secrets.API_KEY }}

ส่วน ReadyAPI ที่เทียบเท่ากันนั้นต้องการ self-hosted runner ที่ติดตั้ง ReadyAPI หรือการสร้าง Docker image ที่ซับซับซ้อน ทั้งสองวิธีนี้ไม่ตรงไปตรงมาเท่า

การย้าย CI/CD จาก ReadyAPI ไปยัง Apidog

หากคุณกำลังย้ายชุดทดสอบและต้องการอัปเดตการกำหนดค่า CI/CD พร้อมกัน:

ส่งออกคำจำกัดความ API ของคุณจาก ReadyAPI และนำเข้าสู่ Apidog
ติดตั้ง Apidog CLI บน Jenkins agents ของคุณ
เพิ่มขั้นตอนการทดสอบ Apidog ไปยังไปป์ไลน์ของคุณควบคู่ไปกับขั้นตอน ReadyAPI ที่มีอยู่
รันทั้งสองอย่างพร้อมกัน เปรียบเทียบอัตราความล้มเหลวและการครอบคลุมการทดสอบ
ลบขั้นตอน ReadyAPI ออกเมื่อคุณมั่นใจในการครอบคลุมของ Apidog แล้ว
ลบ ReadyAPI ออกจาก build agents ในระหว่างการรีเฟรชอิมเมจเอเจนต์ครั้งถัดไป

คำถามที่พบบ่อย

testrunner ของ ReadyAPI ต้องมีใบอนุญาต CI แยกต่างหากหรือไม่?นโยบายการออกใบอนุญาตของ SmartBear สำหรับการใช้งาน CI/CD แตกต่างกันไปตามสัญญา ข้อตกลงบางฉบับรวมสิทธิ์ในการดำเนินการ CI/CD ไว้ในใบอนุญาตมาตรฐาน บางฉบับต้องการข้อตกลงแยกต่างหาก ตรวจสอบสัญญาของคุณหรือติดต่อผู้จัดการบัญชี SmartBear ของคุณก่อนที่จะสันนิษฐานว่าการรัน CI ได้รับการคุ้มครอง

การทดสอบ ReadyAPI สามารถรันใน Docker containers ได้หรือไม่?ได้ แต่ต้องใช้ความพยายาม คุณสามารถสร้างอิมเมจ Docker ที่ติดตั้ง ReadyAPI และใช้เป็นคอนเทนเนอร์ Jenkins agent ได้ อิมเมจมีขนาดใหญ่ (ReadyAPI เป็นแอปพลิเคชันบนเดสก์ท็อป) และต้องมีการกำหนดค่าแบบ headless มันใช้งานได้แต่เพิ่มความซับซ้อนเมื่อเทียบกับเครื่องมือที่สร้างขึ้นสำหรับสภาพแวดล้อม CI แบบคอนเทนเนอร์

Apidog รองรับการรันการทดสอบแบบขนานใน Jenkins หรือไม่?ใช่ คุณสามารถรัน Apidog CLI หลายอินสแตนซ์ใน Jenkins stages แบบขนาน ซึ่งแต่ละอินสแตนซ์จะรันคอลเลกชันหรือสภาพแวดล้อมที่แตกต่างกัน การดำเนินการแบบขนานถูกควบคุมผ่าน Jenkinsfile ของคุณ ไม่ใช่ Apidog CLI

Apidog สร้างรายงานการทดสอบในรูปแบบใดสำหรับ Jenkins?Apidog CLI สามารถสร้างรายงาน JUnit XML ซึ่ง Jenkins สามารถแยกวิเคราะห์และแสดงผลได้โดยตรงในส่วนผลลัพธ์การทดสอบ รูปแบบนี้เหมือนกับที่ testrunner ของ ReadyAPI สร้างขึ้น

สคริปต์ทดสอบ Apidog รันในกระบวนการเดียวกับ CLI runner หรือไม่?ใช่ สคริปต์ทดสอบ JavaScript จะถูกประมวลผลภายในกระบวนการ Node.js ของ Apidog CLI ไม่มีสภาพแวดล้อมการประมวลผลสคริปต์แยกต่างหากให้กำหนดค่า

มีปลั๊กอิน Apidog Jenkins อย่างเป็นทางการหรือไม่?Apidog CLI ทำงานเป็นขั้นตอน shell ใน Jenkins ซึ่งไม่จำเป็นต้องใช้ปลั๊กอินเฉพาะ วิธีนี้บำรุงรักษาง่ายกว่าการรวมระบบที่ใช้ปลั๊กอิน ซึ่งต้องมีการอัปเดตเมื่อ Jenkins หรือ Apidog ออกเวอร์ชันใหม่

การรวม ReadyAPI กับ Jenkins ใช้งานได้ แต่ต้องมีการจัดการโครงสร้างพื้นฐานจำนวนมาก สำหรับทีมที่ต้องการทำให้การตั้งค่า CI/CD ง่ายขึ้น ในขณะที่ยังคงครอบคลุมการทดสอบ API อย่างครบถ้วน วิธีการ CLI ของ Apidog ช่วยขจัดปัญหาที่พบบ่อยที่สุด ได้แก่ ข้อกำหนดซอฟต์แวร์เอเจนต์ การพึ่งพาเซิร์ฟเวอร์ใบอนุญาต และการกำหนดค่าสภาพแวดล้อมที่ซับซ้อน