Skip to content
Algorand Developer Portal

Pre-built Global Setups

← Back to Testing

Description

Section titled “Description”

This example demonstrates the pre-built global setup functions available for common client types and how to use them in Vitest configuration. It shows:

  • algodGlobalSetup, indexerGlobalSetup, and kmdGlobalSetup imports
  • How these are pre-configured setup functions ready to use
  • Example vitest.config.ts configurations for each setup
  • Example tests/globalSetup.ts files that re-export the setup
  • The difference between pre-built setups and createGlobalSetup() NOTE: This example documents usage patterns without invoking setups (no running server needed). The setup functions are designed for use in vitest.config.ts, not direct invocation.

Prerequisites

Section titled “Prerequisites”
  • No LocalNet required

Run This Example

Section titled “Run This Example”

From the repository root:

Terminal window
cd examples
npm run example testing/06-prebuilt-global-setups.ts

Code

Section titled “Code”

View source on GitHub

06-prebuilt-global-setups.ts
/**
 * Example: Pre-built Global Setups
 *
 * This example demonstrates the pre-built global setup functions available for
 * common client types and how to use them in Vitest configuration. It shows:
 * - algodGlobalSetup, indexerGlobalSetup, and kmdGlobalSetup imports
 * - How these are pre-configured setup functions ready to use
 * - Example vitest.config.ts configurations for each setup
 * - Example tests/globalSetup.ts files that re-export the setup
 * - The difference between pre-built setups and createGlobalSetup()
 *
 * NOTE: This example documents usage patterns without invoking setups
 * (no running server needed). The setup functions are designed for use in
 * vitest.config.ts, not direct invocation.
 *
 * Prerequisites:
 * - No LocalNet required
 */


import {
  algodGlobalSetup,
  createGlobalSetup,
  indexerGlobalSetup,
  kmdGlobalSetup,
} from '@algorandfoundation/algokit-utils/testing';
import { printHeader, printInfo, printStep, printSuccess } from '../shared/utils.js';


function main() {
  printHeader('Pre-built Global Setups Example');


  // Step 1: Import pre-built global setups
  printStep(1, 'Importing Pre-built Global Setups');
  printInfo('The testing package exports three pre-built global setup functions:');
  printInfo('');
  printInfo('  import {');
  printInfo('    algodGlobalSetup,');
  printInfo('    indexerGlobalSetup,');
  printInfo('    kmdGlobalSetup,');
  printInfo('  } from "@algorandfoundation/algokit-utils/testing"');
  printInfo('');
  printInfo('These are pre-configured setup functions ready to use in Vitest.');
  printInfo('');
  printInfo('Verifying imports are functions:');
  printInfo(`  algodGlobalSetup:   ${typeof algodGlobalSetup}`);
  printInfo(`  indexerGlobalSetup: ${typeof indexerGlobalSetup}`);
  printInfo(`  kmdGlobalSetup:     ${typeof kmdGlobalSetup}`);


  // Step 2: Explain algodGlobalSetup
  printStep(2, 'algodGlobalSetup - Mock Algod Server');
  printInfo('algodGlobalSetup connects to the mock algod server.');
  printInfo('');
  printInfo('What it does:');
  printInfo('  - Reads MOCK_ALGOD_URL from environment (default: http://localhost:8000)');
  printInfo('  - Verifies the mock algod server is reachable');
  printInfo('  - Returns a teardown function for cleanup');
  printInfo('');
  printInfo('The mock algod server provides:');
  printInfo('  - Transaction submission and status endpoints');
  printInfo('  - Account information queries');
  printInfo('  - Application state queries');
  printInfo('  - Block information');


  // Step 3: Explain indexerGlobalSetup
  printStep(3, 'indexerGlobalSetup - Mock Indexer Server');
  printInfo('indexerGlobalSetup connects to the mock indexer server.');
  printInfo('');
  printInfo('What it does:');
  printInfo('  - Reads MOCK_INDEXER_URL from environment (default: http://localhost:8002)');
  printInfo('  - Verifies the mock indexer server is reachable');
  printInfo('  - Returns a teardown function for cleanup');
  printInfo('');
  printInfo('The mock indexer server provides:');
  printInfo('  - Historical transaction search');
  printInfo('  - Account transaction history');
  printInfo('  - Asset and application lookups');
  printInfo('  - Block search capabilities');


  // Step 4: Explain kmdGlobalSetup
  printStep(4, 'kmdGlobalSetup - Mock KMD Server');
  printInfo('kmdGlobalSetup connects to the mock kmd server.');
  printInfo('');
  printInfo('What it does:');
  printInfo('  - Reads MOCK_KMD_URL from environment (default: http://localhost:8001)');
  printInfo('  - Verifies the mock kmd server is reachable');
  printInfo('  - Returns a teardown function for cleanup');
  printInfo('');
  printInfo('The mock kmd server provides:');
  printInfo('  - Wallet management (create, list, delete)');
  printInfo('  - Key management within wallets');
  printInfo('  - Transaction signing');
  printInfo('  - Key import/export');


  // Step 5: Show example vitest.config.ts for algod
  printStep(5, 'Example vitest.config.ts for Algod');
  printInfo('For testing with the algod mock server:');
  printInfo('');
  printInfo('  // vitest.config.ts');
  printInfo('  import { defineConfig } from "vitest/config"');
  printInfo('');
  printInfo('  export default defineConfig({');
  printInfo('    test: {');
  printInfo('      globalSetup: "./tests/globalSetup.ts",');
  printInfo('    },');
  printInfo('  })');
  printInfo('');
  printInfo('  // tests/globalSetup.ts');
  printInfo('  import { algodGlobalSetup } from "@algorandfoundation/algokit-utils/testing"');
  printInfo('  export default algodGlobalSetup');


  // Step 6: Show example vitest.config.ts for indexer
  printStep(6, 'Example vitest.config.ts for Indexer');
  printInfo('For testing with the indexer mock server:');
  printInfo('');
  printInfo('  // vitest.config.ts');
  printInfo('  import { defineConfig } from "vitest/config"');
  printInfo('');
  printInfo('  export default defineConfig({');
  printInfo('    test: {');
  printInfo('      globalSetup: "./tests/globalSetup.ts",');
  printInfo('    },');
  printInfo('  })');
  printInfo('');
  printInfo('  // tests/globalSetup.ts');
  printInfo('  import { indexerGlobalSetup } from "@algorandfoundation/algokit-utils/testing"');
  printInfo('  export default indexerGlobalSetup');


  // Step 7: Show example vitest.config.ts for kmd
  printStep(7, 'Example vitest.config.ts for KMD');
  printInfo('For testing with the kmd mock server:');
  printInfo('');
  printInfo('  // vitest.config.ts');
  printInfo('  import { defineConfig } from "vitest/config"');
  printInfo('');
  printInfo('  export default defineConfig({');
  printInfo('    test: {');
  printInfo('      globalSetup: "./tests/globalSetup.ts",');
  printInfo('    },');
  printInfo('  })');
  printInfo('');
  printInfo('  // tests/globalSetup.ts');
  printInfo('  import { kmdGlobalSetup } from "@algorandfoundation/algokit-utils/testing"');
  printInfo('  export default kmdGlobalSetup');


  // Step 8: Show example globalSetup.ts re-export pattern
  printStep(8, 'Re-export Pattern in globalSetup.ts');
  printInfo('The recommended pattern is to create a globalSetup.ts file that re-exports:');
  printInfo('');
  printInfo('  // tests/globalSetup.ts - Simple re-export');
  printInfo('  import { algodGlobalSetup } from "@algorandfoundation/algokit-utils/testing"');
  printInfo('  export default algodGlobalSetup');
  printInfo('');
  printInfo('This pattern allows you to:');
  printInfo('  - Keep vitest.config.ts clean and focused');
  printInfo('  - Easily switch between different mock servers');
  printInfo('  - Add custom setup logic if needed later');
  printInfo('');
  printInfo('For multiple servers, combine setups:');
  printInfo('');
  printInfo('  // tests/globalSetup.ts - Combined setup');
  printInfo(
    '  import { algodGlobalSetup, indexerGlobalSetup } from "@algorandfoundation/algokit-utils/testing"',
  );
  printInfo('');
  printInfo('  export default async function setup() {');
  printInfo('    const teardownAlgod = await algodGlobalSetup()');
  printInfo('    const teardownIndexer = await indexerGlobalSetup()');
  printInfo('    return async () => {');
  printInfo('      await teardownAlgod()');
  printInfo('      await teardownIndexer()');
  printInfo('    }');
  printInfo('  }');


  // Step 9: Difference between pre-built setups and createGlobalSetup()
  printStep(9, 'Pre-built Setups vs createGlobalSetup()');
  printInfo('Understanding when to use each approach:');
  printInfo('');
  printInfo('PRE-BUILT SETUPS (algodGlobalSetup, indexerGlobalSetup, kmdGlobalSetup):');
  printInfo('  - Ready to use with no configuration');
  printInfo('  - Simply import and re-export');
  printInfo('  - Best for most common use cases');
  printInfo('  - Equivalent to createGlobalSetup("algod"), etc.');
  printInfo('');
  printInfo('createGlobalSetup(clientType):');
  printInfo('  - Factory function for creating custom setups');
  printInfo('  - Useful when you need programmatic control');
  printInfo('  - Can be used to create setups dynamically');
  printInfo('  - Example: createGlobalSetup(process.env.CLIENT_TYPE as ClientType)');
  printInfo('');
  printInfo('Equivalence:');
  printInfo('  algodGlobalSetup   === createGlobalSetup("algod")');
  printInfo('  indexerGlobalSetup === createGlobalSetup("indexer")');
  printInfo('  kmdGlobalSetup     === createGlobalSetup("kmd")');
  printInfo('');
  printInfo('Verifying equivalence (both create functions):');
  printInfo(`  Pre-built algodGlobalSetup:    ${typeof algodGlobalSetup}`);
  printInfo(`  createGlobalSetup("algod"):    ${typeof createGlobalSetup('algod')}`);


  // Summary
  printStep(10, 'Summary');
  printInfo('Key takeaways for using pre-built global setups:');
  printInfo('');
  printInfo('  1. Import the setup you need:');
  printInfo('     - algodGlobalSetup for algod mock server');
  printInfo('     - indexerGlobalSetup for indexer mock server');
  printInfo('     - kmdGlobalSetup for kmd mock server');
  printInfo('');
  printInfo('  2. Create tests/globalSetup.ts and re-export the setup');
  printInfo('');
  printInfo('  3. Point vitest.config.ts to your globalSetup.ts');
  printInfo('');
  printInfo('  4. Use createGlobalSetup() only when you need:');
  printInfo('     - Dynamic client type selection');
  printInfo('     - Programmatic setup configuration');
  printInfo('');
  printInfo('  5. Combine multiple setups by calling them in sequence');


  printSuccess('Pre-built global setups example completed!');
}


main();

Other examples in Testing

Section titled “Other examples in Testing”