🧪How to Create Integration Tests Using GitHub Actions and Stellar's Docker Image

The Importance of Testing in Programming

Testing helps detect errors before they reach production, improves software reliability, and provides confidence when making changes or adding new features. Among the various types of tests, integration tests are crucial for ensuring that an application’s modules work correctly together. In this article, we’ll explore the benefits of integration testing and how to set it up locally and in a GitHub Actions pipeline using the stellar/quickstart Docker image.

Benefits of Integration Testing

Integration tests verify the interaction between multiple components of a system, such as databases, external APIs, and other services. The main benefits include:

- Error detection in module communication: Helps identify compatibility issues and logical errors.

- Risk reduction Ensures that code changes do not break existing functionality.

- Easier debugging Provides additional context when testing real-world scenarios.

Setting Up Integration Tests with stellar/quickstart Image and Docker

Using the stellar/quickstart image allows you to set up a local environment to interact with the Horizon API and simulate Stellar operations. This eliminates the dependency on the production network, improving test speed and reliability. Below is a step-by-step guide.

Step 1: Create a docker-compose.yml file

This file defines the services needed to run the Stellar image. Add a Stellar service configured for a local network:

version: '3.8'
services:
  stellar:
    image: stellar/quickstart
    container_name: stellar
    command: --local
    ports:
      - "8000:8000"

- image: Specifies the stellar/quickstart Docker image.

- command: --local: Configures the local network to run the tests.

- ports: Maps local port 8000 to the container for accessing the Horizon API.

Step 2: Run the Image Locally

With Docker Desktop installed, start the container by running:

docker-compose up -d

This starts the service detached, and the Horizon API will be available at http://localhost:8000.

Step 3: Interact with Stellar locally

Next, we'll create a file named accountSetup.js to test basic operations:

import { Horizon, Keypair, Server } from 'stellar-sdk';

const server = new Server('http://localhost:8000', { allowHttp: true });

export async function createFundedAccount() {
    try {
        console.log('Creating Account 1...');

        const keypair1 = Keypair.random();

        await server.friendbot(keypair1.publicKey()).call();

        console.log('Funding Account 1...');

        process.env.VITE_MOCKED_ACCOUNT_1_PUBLIC_KEY = keypair1.publicKey();
        process.env.VITE_MOCKED_ACCOUNT_1_PRIVATE_KEY = keypair1.secret();

        console.log(`Account 1: PUBKEY: ${process.env.VITE_MOCKED_ACCOUNT_1_PUBLIC_KEY} SECRET: ${process.env.VITE_MOCKED_ACCOUNT_1_PRIVATE_KEY}`,);
        console.log('Account succesfully created and funded with 10000.0000000 XLM');

    } catch (error) {
        console.error('Error funding accounts with Friendbot:', error);
    }
}

export async function getBalance(publicKey: string): Promise<string | undefined> {
    let accountBalance;
    try {
        const { balances } = await server.loadAccount(publicKey);

        accountBalance = balances.find((balance: Horizon.BalanceLine) => balance.asset_type === 'native')?.balance;
    } catch (error) {
        console.error('Account balance not found:', error);
    }
    return accountBalance;
}

These functions:

1. createFundedAccount: Creates a random account and funds it with 10,000 lumens using Friendbot.

2. getBalance: Retrieves the balance of an account using the Horizon API.

Step 4: Write the Tests

You can use a framework like Jest to write the tests:

/**
 * @jest-environment node
*/

import { expect } from '@jest/globals';
import { createFundedAccount, getBalance } from '../stellar/accountSetup';

it('Should get account funded', async () => {
    await createFundedAccount();
    const balance = await getBalance(process.env.VITE_MOCKED_ACCOUNT_1_PUBLIC_KEY);

    expect(balance).toBe('10000.0000000');
});

Run the tests locally with:

npm test

Step 5: Setting Up the Pipeline with GitHub Actions

The next step is automating the tests in GitHub Actions. This ensures that code changes are continuously validated.

Create a workflow file at .github/workflows/ci.yml:

name: CI Pipeline

on:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      stellar:
        image: stellar/quickstart
        options: --local
        ports:
          - 8000:8000

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

This pipeline:

1. Configures a Docker service for Stellar.

2. Installs Node.js dependencies.

3. Runs the tests.

Conclusion

Performing integration tests using stellar/quickstart in Docker provides a controlled and reliable environment for validating functionality. Setting up a GitHub Actions pipeline improves efficiency by detecting errors before they reach production. These steps ensure that developers can focus on innovation while maintaining high code quality standards.

Resources:

- docker-compose.yml file

- accountSetup.ts file

- home.test.ts file

- main.yml file