xq-infra

name: xq-infra description: Guides use of the xq-infra CLI for spinning up local test environments (database, services, gateway). Use when running integration tests, troubleshooting test environment startup, or working with xq-test-infra, xq-infra generate, xq-infra up, or xq-infra down.

xq-infra CLI

CLI for running local test environments: database, backend services, and gateway. Required for integration tests that make real API calls.

Installation

npm install -g @chauhaidang/xq-test-infra@1.0.3

Requires GitHub Packages access (registry-url: https://npm.pkg.github.com/, scope @chauhaidang).

Core Commands

Workflow: Mobile Integration Tests

From mobile/ (same directory as test-env/):

xq-infra generate -f ./test-env
xq-infra up
yarn test:integration
# When done:
xq-infra down

Important: Run xq-infra from the directory that contains test-env/. Do not use a different path.

test-env Structure

• xq.config.yml: Port range, dependency groups (e.g. database)
• xq-fitness-db.service.yml: PostgreSQL (port 5432)
• xq-fitness-read-service.service.yml: Read API (port 8080)
• xq-fitness-write-service.service.yml: Write API (port 3000)
• xq-gateway: Auto-injected by xq-infra; exposes services on port 8080

Gateway URL

Integration tests use GATEWAY_URL=http://localhost:8080 (default). The app resolves:

• Read: ${GATEWAY_URL}/xq-fitness-read-service/api/v1
• Write: ${GATEWAY_URL}/xq-fitness-write-service/api/v1

Port Conflicts

If startup fails or you see "address already in use":

1. Check for other stacks (read-service, write-service, mobile) using the same ports
2. Run xq-infra down in those project directories
3. Avoid running multiple test envs that share ports (5432, 8080)

CI Usage

- run: npm install -g @chauhaidang/xq-test-infra@1.0.3
- run: xq-infra generate -f ./test-env && xq-infra up
- run: yarn test:integration
- if: always()
  run: |
    xq-infra logs
    xq-infra down

Troubleshooting