Mock Services

Mock services allow you to develop and test carrier integrations without connecting to real carrier APIs. Staqr uses Microcks for sophisticated API mocking with WSDL/OpenAPI validation.

Overview

Mock services are automatically deployed in development environments via Helm. They provide:

• SOAP mocking: Full WSDL validation for carriers like Optus WSG
• REST mocking: OpenAPI-based mocking for modern carrier APIs
• Request validation: Ensures your code sends valid requests
• Response simulation: Returns realistic mock responses

Accessing Mock Services

Development Environment

Mock services are available at:

Service	URL	Purpose
Microcks UI	https://mocks.go.prvidr.io	Manage mock definitions
Microcks API	http://microcks:8080 (internal)	Runtime mock endpoints

Local Development

When using Docker Compose:

# Start mock services
docker compose -f docker-compose.yml --profile mocks up -d

# Access Microcks
open http://localhost:4750

Managing Mock Definitions

Import WSDL (SOAP APIs)

# Via Microcks API
curl -X POST http://localhost:4750/api/artifact/upload \
  -F "file=@mocks/microcks/import/optus-wsg-9.2.wsdl"

Import OpenAPI (REST APIs)

curl -X POST http://localhost:4750/api/artifact/upload \
  -F "file=@mocks/microcks/import/telstra-api-1.0.yaml"

View Imported Services

curl http://localhost:4750/api/services | jq '.[].name'

Creating Mock Connections

Once mock services are running, create connections that point to them:

Via Platform Admin UI

1. Navigate to Settings > Integrations > Carrier Connections
2. Click Add Connection
3. Configure:
   • Connection ID: mock-optus-wsg
   • Endpoint: http://microcks:8080/soap/WsgServiceOrderService/9.2
   • Is Mock: Yes
   • Authentication: None

Via Helm Values

Mock connections are automatically configured in values-dev.yaml:

staqr:
  connections:
    optus:
      connectionId: mock-optus-wsg
      endpoint: "http://{{ .Release.Name }}-microcks:8080/soap/WsgServiceOrderService/9.2"
      isMock: true
      authentication:
        type: none

Mock Response Customisation

Using Microcks UI

1. Open Microcks UI (https://mocks.go.prvidr.io)
2. Navigate to Services > select your service
3. Click on an operation
4. Add or edit response variants

Response Dispatching

Configure different responses based on request content:

Dispatcher	Use Case
FALLBACK	Always return default response
QUERY_MATCH	Match query parameters
HEADER_MATCH	Match request headers
SCRIPT	Custom JavaScript logic

Example: Error Scenarios

Create response variants for error testing:

Name: "Throttle Error"
Status: 503
Header: X-Test-Scenario: throttle
Body: <SOAP fault envelope>

Trigger in tests:

const result = await adapter.submitOrder(data, {
  headers: { 'X-Test-Scenario': 'throttle' }
})
expect(result.error).toBe('RATE_LIMIT_EXCEEDED')

Viewing Request Logs

Microcks stores all invocations for debugging:

Via UI

1. Navigate to your service
2. Click Invocations tab
3. View request/response pairs

Via API

curl "http://localhost:4750/api/invocations/WsgServiceOrderService/9.2?page=0&size=20" | jq

Mock Services in CI/CD

Mock services run as GitLab CI service containers during integration tests:

integration-tests:
  services:
    - name: quay.io/microcks/microcks:1.9.0
      alias: microcks
      variables:
        SPRING_PROFILES_ACTIVE: uber
        KEYCLOAK_ENABLED: "false"

See API Mocks Developer Guide for CI/CD integration details.

Troubleshooting

Microcks Returns 404

# Check if service is imported
curl http://localhost:4750/api/services | jq '.[].name'

# Re-import WSDL
curl -X POST http://localhost:4750/api/artifact/upload \
  -F "file=@mocks/microcks/import/optus-wsg-9.2.wsdl"

SOAP Request Not Matching

Ensure:

• SOAPAction header matches WSDL operation
• XML namespace matches WSDL targetNamespace
• Request body validates against XSD schema

Mock Response Not Updating

Clear Microcks cache:

docker restart staqr-microcks

Or re-import the WSDL/OpenAPI file.