Skip to content
Algorand Developer Portal

Health Check Utility

← Back to Testing

Description

Section titled “Description”

This example demonstrates how to use checkServerHealth() to verify mock server availability before running tests. The function checks if a server is reachable by performing a health check request. This example works whether or not mock servers are running - it just reports the status of each server.

Prerequisites

Section titled “Prerequisites”
  • No LocalNet required
  • Mock server optional (reports status either way)

Run This Example

Section titled “Run This Example”

From the repository root:

Terminal window
cd examples
npm run example testing/03-health-check.ts

Code

Section titled “Code”

View source on GitHub

03-health-check.ts
/**
 * Example: Health Check Utility
 *
 * This example demonstrates how to use checkServerHealth() to verify
 * mock server availability before running tests. The function checks
 * if a server is reachable by performing a health check request.
 *
 * This example works whether or not mock servers are running - it just
 * reports the status of each server.
 *
 * Prerequisites:
 * - No LocalNet required
 * - Mock server optional (reports status either way)
 */


import {
  checkServerHealth,
  EXTERNAL_URL_ENV_VARS,
  MOCK_PORTS,
} from '@algorandfoundation/algokit-utils/testing';
import { printHeader, printInfo, printStep, printSuccess } from '../shared/utils.js';


/**
 * Get the URL for a mock server, checking environment variable first,
 * then falling back to localhost with default port.
 */
function getServerUrl(clientType: 'algod' | 'indexer' | 'kmd'): string {
  const envVar = EXTERNAL_URL_ENV_VARS[clientType];
  const envValue = process.env[envVar];
  if (envValue) {
    return envValue;
  }
  return `http://localhost:${MOCK_PORTS[clientType].host}`;
}


async function main() {
  printHeader('Health Check Utility Example');


  // Step 1: Explain checkServerHealth function
  printStep(1, 'checkServerHealth() - Check if a server is reachable');
  printInfo(
    'Function signature: checkServerHealth(url: string, timeout?: number): Promise<boolean>',
  );
  printInfo('  - url: The base URL of the server to check');
  printInfo('  - timeout: Maximum time to wait (default: 5000ms)');
  printInfo('  - Returns: true if server responds, false otherwise');
  printInfo('');
  printInfo('The function sends a request to /health endpoint and considers');
  printInfo('any HTTP response (including 500) as the server being reachable.');


  // Step 2: Check algod mock server with default timeout
  printStep(2, 'Check algod mock server (default 5000ms timeout)');
  const algodUrl = getServerUrl('algod');
  printInfo(`URL: ${algodUrl}`);
  printInfo(`  (from ${EXTERNAL_URL_ENV_VARS.algod} or localhost:${MOCK_PORTS.algod.host})`);
  const algodHealthy = await checkServerHealth(algodUrl);
  printInfo(`Status: ${algodHealthy ? '✓ Server is reachable' : '✗ Server is not reachable'}`);


  // Step 3: Check indexer mock server with custom timeout
  printStep(3, 'Check indexer mock server (custom 2000ms timeout)');
  const indexerUrl = getServerUrl('indexer');
  printInfo(`URL: ${indexerUrl}`);
  printInfo(`  (from ${EXTERNAL_URL_ENV_VARS.indexer} or localhost:${MOCK_PORTS.indexer.host})`);
  const indexerHealthy = await checkServerHealth(indexerUrl, 2000);
  printInfo(`Status: ${indexerHealthy ? '✓ Server is reachable' : '✗ Server is not reachable'}`);


  // Step 4: Check kmd mock server with custom timeout
  printStep(4, 'Check kmd mock server (custom 2000ms timeout)');
  const kmdUrl = getServerUrl('kmd');
  printInfo(`URL: ${kmdUrl}`);
  printInfo(`  (from ${EXTERNAL_URL_ENV_VARS.kmd} or localhost:${MOCK_PORTS.kmd.host})`);
  const kmdHealthy = await checkServerHealth(kmdUrl, 2000);
  printInfo(`Status: ${kmdHealthy ? '✓ Server is reachable' : '✗ Server is not reachable'}`);


  // Step 5: Summary of health check results
  printStep(5, 'Health Check Summary');
  printInfo('Server Status:');
  printInfo(`  - algod   (${algodUrl}): ${algodHealthy ? 'REACHABLE' : 'NOT REACHABLE'}`);
  printInfo(`  - indexer (${indexerUrl}): ${indexerHealthy ? 'REACHABLE' : 'NOT REACHABLE'}`);
  printInfo(`  - kmd     (${kmdUrl}): ${kmdHealthy ? 'REACHABLE' : 'NOT REACHABLE'}`);
  printInfo('');


  // Provide helpful guidance based on results
  const anyServerUp = algodHealthy || indexerHealthy || kmdHealthy;
  const allServersUp = algodHealthy && indexerHealthy && kmdHealthy;


  if (allServersUp) {
    printInfo('All mock servers are running and ready for testing!');
  } else if (anyServerUp) {
    printInfo('Some mock servers are running. Start the others if needed for your tests.');
  } else {
    printInfo('No mock servers are currently running.');
    printInfo('To start mock servers for local development:');
    printInfo('  1. Use algokit-polytest CLI to start servers');
    printInfo('  2. Or set environment variables to external server URLs:');
    printInfo(`     export ${EXTERNAL_URL_ENV_VARS.algod}=http://your-server:8000`);
    printInfo(`     export ${EXTERNAL_URL_ENV_VARS.indexer}=http://your-server:8002`);
    printInfo(`     export ${EXTERNAL_URL_ENV_VARS.kmd}=http://your-server:8001`);
  }


  printSuccess('Health check example completed!');
}


main().catch(console.error);

Other examples in Testing

Section titled “Other examples in Testing”