OpenXAPI Integration Tests

This repository contains integration tests for OpenXAPI-generated SDKs to ensure they work correctly with each release.

Purpose

This repository serves as a comprehensive test suite for all SDKs generated by OpenXAPI. It validates that the generated code functions correctly against real exchange APIs, ensuring reliability and compatibility across different exchanges, languages, and protocols.

Repository Structure

The repository follows a strict hierarchical structure:

src/
└── {exchange}/
    └── {language}/
        └── {protocol}/
            └── {module}/

Where:

• {exchange}: The cryptocurrency exchange (e.g., binance, okx, bybit)
• {language}: The programming language (e.g., go, python, javascript)
• {protocol}: The protocol type (ws for WebSocket, rest for REST API)
• {module}: The specific trading module (e.g., spot, umfutures, cmfutures)

Current Structure:

src/
└── binance/                    # Binance exchange tests
    └── go/                    # Go language tests
        ├── ws/                # WebSocket API tests
        │   ├── spot/          # Spot WebSocket API + User Data Streams
        │   ├── umfutures/     # USD-M Futures WebSocket API + User Data Streams
        │   ├── cmfutures/     # Coin-M Futures WebSocket API + User Data Streams
        │   ├── pmargin/       # Portfolio Margin WebSocket API + User Data Streams
        │   ├── spot-streams/  # Spot Market Data Streams (public data)
        │   ├── umfutures-streams/ # USD-M Futures Market Data Streams (public data)
        │   ├── cmfutures-streams/ # Coin-M Futures Market Data Streams (public data)
        │   └── options-streams/   # Options Market Data Streams (public data)
        └── rest/              # REST API tests
            └── spot/          # Spot trading REST API tests (87.2% coverage)

Development Guidelines

Important Rules

1. Module Isolation: Each integration test folder is completely independent. When working on tests:

   • Only modify files within your dedicated module folder
   • Do not change files in other modules or exchanges
   • Each folder represents a specific {exchange}/{language}/{protocol}/{module} combination

2. SDK Location: The SDKs being tested are located outside this repository:

   • WebSocket APIs + User Data Streams: ../binance-go/ws/{module} (e.g., ../binance-go/ws/spot)
   • Market Data Streams: ../binance-go/ws/{module}-streams (e.g., ../binance-go/ws/spot-streams)
   • REST APIs: ../binance-go/rest/{module} (e.g., ../binance-go/rest/spot)
   • Never modify SDK source files - only create integration tests

3. Adding New Integration Tests:

   • Follow the exact directory structure: src/{exchange}/{language}/{protocol}/{module}/
   • Create all necessary test files within your module folder
   • Include a README.md specific to your module
   • Add appropriate .gitignore and env.example files

Running Integration Tests

Prerequisites

1. Navigate to the specific module directory
2. Set up environment variables:

   cd src/binance/go/ws/spot
   cp env.example env.local
   # Edit env.local with your API credentials
   source env.local

Running Tests

By default, tests are run against the testnet server where available.

Binance WebSocket API + User Data Streams Tests (Go)

# Spot WebSocket API + User Data Streams (41 endpoints, 100% coverage)
cd src/binance/go/ws/spot
go test -v -run TestFullIntegrationSuite ./...

# USD-M Futures WebSocket API + User Data Streams (19 endpoints, 100% coverage)
cd src/binance/go/ws/umfutures
go test -v -run TestFullIntegrationSuite ./...

# Coin-M Futures WebSocket API + User Data Streams (10 endpoints, 100% coverage)
cd src/binance/go/ws/cmfutures
go test -v -run TestFullIntegrationSuite ./...

# Portfolio Margin WebSocket API + User Data Streams (11 event types, limited coverage)
cd src/binance/go/ws/pmargin
go test -v -run TestFullIntegrationSuite ./...

Binance Market Data Streams Tests (Go)

# Spot Market Data Streams (10 stream types, 100% coverage)
cd src/binance/go/ws/spot-streams
go test -v -run TestFullIntegrationSuite ./...

# USD-M Futures Market Data Streams (13 stream types, 100% coverage)
cd src/binance/go/ws/umfutures-streams
go test -v -run TestFullIntegrationSuite ./...

# Coin-M Futures Market Data Streams (13 stream types, 100% coverage)
cd src/binance/go/ws/cmfutures-streams
go test -v -run TestFullIntegrationSuite ./...

# Options Market Data Streams (9 stream types, 100% coverage)
cd src/binance/go/ws/options-streams
go test -v -run TestFullIntegrationSuite ./...

Binance REST API Tests (Go)

# Spot REST API (410+ endpoints, 87.2% coverage)
cd src/binance/go/rest/spot
go test -v -run TestFullIntegrationSuite ./...

Makefile Shortcuts (Binance Go WebSocket)

Use the root Makefile to run every Binance Go WebSocket suite at once:

# Default: test modules against the locally checked-out ../binance-go workspace
make test-binance-ws-go

# Test against the remote main branch of github.com/openxapi/binance-go/{ws,rest}
make test-binance-ws-go BINANCE_WS_GO_SOURCE=main

# Test against the latest (or specific) tag pushed to github.com/openxapi/binance-go
make test-binance-ws-go BINANCE_WS_GO_SOURCE=tag             # empty BINANCE_WS_GO_TAG => latest tag
make test-binance-ws-go BINANCE_WS_GO_SOURCE=tag BINANCE_WS_GO_TAG=v0.4.1

BINANCE_WS_GO_SOURCE accepts three values:

• local (default): keep using the local ../binance-go checkout via replace directives.
• main: fetch pseudo-versions for the remote main branch before testing.
• tag: resolve a commit from the remote https://github.com/openxapi/binance-go tags (leave BINANCE_WS_GO_TAG empty to auto-pick the highest vX.Y.Z, or set it to a specific tag/commit hash).

Remote modes create a temporary go.mod (and go.sum) by stripping the local replace directives, call scripts/resolve_binance_tag.py (which shells out to git ls-remote) when a tag is requested, execute go get github.com/openxapi/binance-go/{ws,rest}@<ref> with -modfile, then run the tests with the same temp module file so your working tree stays untouched.

Test Categories

WebSocket API + User Data Streams Tests

Tests for request/response style WebSocket APIs and user-specific data streams:

• Public Endpoints: Market data, exchange info, ticker prices (no auth required)
• Trading Endpoints: Order placement, cancellation, modification (TRADE auth)
• Account Endpoints: Balance queries, position info, trading status (USER_DATA auth)
• Session Management: Authentication, connection lifecycle
• User Data Streams: Account updates, order updates, position changes (authenticated)
• Authentication Methods: HMAC, RSA, Ed25519 signature support

Market Data Streams Tests

Tests for real-time public market data streaming WebSocket APIs:

• Market Data Streams: Trade, ticker, depth, kline streams (no auth required)
• Combined Streams: Multi-stream subscriptions and event handling
• Connection Management: Server selection, reconnection, error handling
• Subscription Management: Dynamic subscribe/unsubscribe operations
• Event Processing: Real-time event handling and data validation

REST API Tests

Tests for traditional HTTP REST APIs:

• Public APIs: Market data, exchange information
• Trading APIs: Order management, trade execution
• Account APIs: Balance queries, transaction history
• Wallet APIs: Deposits, withdrawals, transfers
• Advanced Features: Margin trading, staking, mining, loans

Test Coverage Summary

Binance Go Integration Tests

• Total Modules: 9 (8 WebSocket + 1 REST)
• WebSocket API + User Data Streams Modules: 4 (spot, umfutures, cmfutures, pmargin)
• Market Data Streams Modules: 4 (spot-streams, umfutures-streams, cmfutures-streams, options-streams)
• REST API Modules: 1 (spot)
• Overall Coverage: Comprehensive across all major Binance trading products

Key Features Tested

• Authentication: All three methods (HMAC, RSA, Ed25519) where supported
• Error Handling: Comprehensive error scenarios and recovery testing
• Rate Limiting: Proper handling of exchange rate limits
• Real-time Data: Live market data validation and event processing
• Cross-platform: Tests run on testnet and mainnet environments
• Performance: Load testing and concurrent operations
• Event Handlers: Updated to use HandleXxxEvent naming pattern (replaced OnXxxEvent)

Environment Requirements

Test Environment Support

• Testnet: Primary testing environment (safe for most tests)
• Mainnet: Required for Options and Portfolio Margin (no testnet available)
• Authentication: API keys and secrets required for private endpoints
• Network: Stable internet connection required for real-time tests

Setup Requirements

Each module includes:

• env.example - Template for environment variables
• README.md - Module-specific documentation and usage instructions
• API_COVERAGE.md - Detailed test coverage tracking
• Comprehensive test suites with error handling and logging

Recent Updates

🔄 SDK Naming Pattern Changes (Latest)

All WebSocket integration tests have been updated to use the new SDK naming pattern:

• Event Handlers: OnXxxEvent → HandleXxxEvent
• Affected Modules: All WebSocket streams modules (spot-streams, umfutures-streams, cmfutures-streams, options-streams)
• WebSocket API Modules: Updated to use HandleXxxEventEvent pattern with proper model types
• Status: ✅ All modules now compile and run successfully with updated patterns

Event Handler Examples

// OLD pattern (no longer used)
client.OnAggregateTradeEvent(func(event *models.AggregateTradeEvent) error {
    return nil
})

// NEW pattern (current)
client.HandleAggregateTradeEvent(func(event *models.AggregateTradeEvent) error {
    return nil
})

Notes

• Integration tests interact with real exchange endpoints
• Use testnet environments when available to avoid affecting real trading
• Some tests may require specific account permissions or balances
• Rate limits apply - tests include appropriate delays
• Tests include comprehensive logging for debugging and monitoring

Contributing

When adding new integration tests:

1. Follow the existing directory structure: src/{exchange}/{language}/{protocol}/{module}/
2. Include appropriate environment variable handling and security
3. Add comprehensive error checking and timeout management
4. Create detailed API coverage documentation
5. Include both positive and negative test scenarios
6. Update this README with new module information
7. Ensure tests are idempotent and can be run repeatedly