🚀

ThirdParty Emulator

Integration testing without the limits

Open Source

Test third-party integrations in a controlled environment

Define custom API routes, request/response formats, and timing behaviors to simulate external services. Keep your integration tests reliable, fast, and independent of third-party API availability.

Get Started View on GitLab
routes.yml 
routes:
  - path: /api/users
    rules:
      - method: get
        response:
          status: 200
          body: '[{"name": "John"}]'

Powerful Capabilities

Everything you need for reliable integration testing

🎯

Precise Route Matching

Match requests exactly by HTTP methods, headers, query parameters, and request bodies with full control.

⏱️

Simulate Delays

Add configurable wait times to test slow responses and network timeouts exactly as they happen.

📝

Custom Responses

Return any status code, headers, and response bodies to thoroughly test all scenarios.

🔧

Simple Configuration

Define routes and behaviors in clean YAML files for easy maintenance and team collaboration.

⚡

Fast & Isolated

Lightweight Go server runs locally or in CI/CD without external dependencies or delays.

🔄

Full HTTP Support

Support for GET, POST, PUT, PATCH with complete request validation and response control.

Why Use ThirdParty Emulator?

🚫 Avoid API Quota Exhaustion

Run integration tests without counting against your third-party API rate limits. Test as often as you need.

📊 Stable Test Environments

Tests never fail due to third-party service outages or maintenance windows.

💨 Faster Test Execution

No network latency - run tests locally with instant responses or controlled delays.

🎭 Test Edge Cases

Simulate error responses, timeouts, and uncommon scenarios that are hard to reproduce with real APIs.

🔒 CI/CD Integration

Embed in your automated testing pipeline for consistent, repeatable integration tests.

👥 Team Collaboration

Share YAML configurations across teams for consistent testing scenarios.

Simple Configuration, Powerful Results

Define your routes in clean YAML. The emulator handles request matching, timing, and response formatting automatically.

  • ✅ Intuitive syntax
  • ✅ Version control friendly
  • ✅ Share across teams
View Full Documentation → 
routes:
  - path: /v1/test
    rules:
      - method: get
        args:
          - name: author
            value: stephen-king
        response:
          status: 200
          body: '[{"title": "cujo"}]'
  
  - path: /v1/post
    rules:
      - method: post
        body: '{"username": "test"}'
        wait: 2s
        response:
          status: 200
          body: '{"success": true}'

Documentation

Complete guide to configuring your emulator

Configuration File (config/config.yml)

The configuration file controls the server settings.

---
server:
  port: 8080
Field Type Description Required
server.port integer The port number where the emulator server will listen No (default: 8000)

Routes File (routes/routes.yml)

The routes file defines all API endpoints and their behaviors. Each route can have multiple rules to match different requests.

File Structure

---
routes:
  - path: /api/users
    rules:
      - method: get
        # ... rule configuration
      - method: post
        # ... rule configuration

Route Fields

Field Type Description Required
path string The URL path for this route (e.g., /api/users) Yes
rules array List of rules that define how to match requests and what to respond with Yes

Rule Fields

Each rule defines matching criteria and the response to return when the criteria match.

Field Type Description Required
method string HTTP method to match: get, post, put, patch Yes
headers array List of header name/value pairs that must match exactly No
args array Query parameters (for GET requests) - name/value pairs that must match exactly No
body string JSON string that must be contained in the request body (for POST/PUT/PATCH). The rule checks if all keys in this JSON exist in the request body with matching values. No
wait string Delay before responding. Format: 5s, 2m, 1h (seconds, minutes, hours) No
response object Response configuration (status code, headers, body) Yes

Response Fields

Field Type Description Required
status integer HTTP status code (e.g., 200, 404, 500) Yes
headers array List of header name/value pairs to include in the response No
body string Response body content (typically JSON as a string) No

Complete Example

---
routes:
  - path: /v1/books
    rules:
      # GET request with query parameters
      - method: get
        headers:
          - name: content-type
            value: application/json
        args:
          - name: author
            value: stephen-king
          - name: year
            value: 1987
        response:
          status: 200
          headers:
            - name: content-type
              value: application/json
          body: '[{"title": "The Shining", "year": 1977}]'
      
      # POST request with body matching
      - method: post
        headers:
          - name: content-type
            value: application/json
        body: '{"title": "New Book", "author": "John Doe"}'
        wait: 2s
        response:
          status: 201
          headers:
            - name: content-type
              value: application/json
          body: '{"id": "123", "message": "Created"}'
      
      # PUT request example
      - method: put
        body: '{"id": "123", "status": "updated"}'
        response:
          status: 200
          body: '{"success": true}'

  - path: /v1/health
    rules:
      - method: get
        response:
          status: 200
          body: '{"status": "ok"}'

Important Notes

  • Rule Matching: Rules are checked in order. The first matching rule is used.
  • Body Matching: For POST/PUT/PATCH, the body field defines a JSON object. The rule matches if all keys in the rule's body exist in the request body with the same values. Extra keys in the request body are allowed.
  • No Match: If no rule matches the request, the emulator returns a 404 Not Found response.
  • Header Names: Header names are case-insensitive during matching, but case is preserved in responses.
  • Wait Format: The wait field supports seconds (s), minutes (m), and hours (h). Examples: 5s, 2m, 1h.

Get Started in Minutes

Simple installation, immediate results

1

Install

go get gitlab.com/iferminm/thirdparty.git
2

Configure Routes

Create routes/routes.yml in your project root:

routes:
  - path: /api/example
    rules:
      - method: get
        response:
          status: 200
          body: '{"message": "Hello World"}'
3

Run

go run src/service/main.go

The server starts on localhost:8080 (configure in config/config.yml)