TESTING.md

Testing & CI

🗂️ Index

• Testing
  • Setup test environment
  • Run unit tests
  • Run unit coverage
  • Run API basic integration test
  • Run Selenium integration test
  • Run full integration suite
• CI
  • GitLab unit test matrix
  • GitHub Actions

---

🔬 Testing

Setup test environment

1. Install dependencies:

npm install

2. Create .env from sample:

cp .env.sample .env

3. Set valid credentials in .env:

DBC_USERNAME=your_dbc_username
DBC_PASSWORD=your_dbc_password

4. Ensure browser + driver are available (firefox + geckodriver by default).

Run unit tests

npm run test:unit

Run unit coverage

npm run test:coverage

Run API basic integration test

npm run test:integration:api

This test validates:

• server/user check (get_user)
• balance (get_balance)
• upload text captcha (type=0) using images/normal.jpg
• decode response contains text
• report call returns boolean

Test file:

• tests/integration/api.basic.integration.test.js

Run Selenium integration test

npm run test:integration:selenium

The test file is:

• tests/integration/selenium.integration.test.js

Run full integration suite

npm run test:integration

---

CI

GitLab unit test matrix

GitLab CI is configured in:

• .gitlab-ci.yml

The pipeline runs unit tests on Node.js versions:

• 20
• 22
• 24

Each matrix job runs:

npm install
npm run test:coverage

Coverage is visible in the GitLab job output and the coverage/ folder is uploaded as a job artifact.

GitLab also runs the basic API integration test on Node.js 24.

For credentials, the integration job tries these options in order:

1. local .env file in the workspace
2. DBC_ENV_FILE GitLab variable (File type recommended)
3. DBC_ENV GitLab variable with full .env contents

This avoids declaring multiple separate username/password variables in GitLab.

Run with gitlab-ci-local

For local gitlab-ci-local runs, the easiest option is a local-only variables file:

1. Copy .gitlab-ci-local-variables.example.yml to .gitlab-ci-local-variables.yml
2. Fill your real credentials there
3. Run:

gitlab-ci-local --file ./.gitlab-ci.yml

gitlab-ci-local loads .gitlab-ci-local-variables.yml automatically, and the pipeline will pass DBC_ENV into the integration job without requiring committed .env credentials.

GitHub Actions

GitHub Actions is configured in:

• .github/workflows/unit-tests.yml
• .github/workflows/unit-tests-node22.yml
• .github/workflows/unit-tests-node24.yml
• .github/workflows/coverage.yml
• .github/workflows/api-integration.yml

Unit Tests workflow

• Runs as separate workflows for Node.js 20, 22 and 24
• Each executes:

npm install
npm run test:unit

• Uses only native GitHub Actions
• Exposes native workflow badges per Node.js version

Coverage workflow

• Runs on Node.js 22
• Executes:

npm install
npm run test:coverage

• Uses only native GitHub Actions
• Uploads the coverage/ folder as an artifact
• Exposes a separate native coverage badge

API Integration workflow

• Runs the basic API integration test on Node.js 24
• Executes:

npm install
npm run test:integration:api

• Uses GitHub secrets:

  • DBC_USERNAME
  • DBC_PASSWORD

• Optional runtime env in workflow:

  • MOZ_HEADLESS=1

• No committed .env file is required in GitHub Actions

• If either secret is missing, the workflow skips the integration test without failing the pipeline

• Exposes a native GitHub Actions workflow badge

---

Tests results

Workflow	Node	Status
Unit Tests	20
Unit Tests	22
Unit Tests	24
API Integration	24
Selenium Integration	24
API npm Integration	24
Coverage	22