|
| 1 | +# Cosmos SDK Test Framework |
| 2 | + |
| 3 | +This directory contains the test framework for Cosmos SDK-based coins. The framework is designed to be configurable and extensible, allowing tests to run for any Cosmos-based blockchain through configuration rather than requiring individual coin modules. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The test framework consists of: |
| 8 | + |
| 9 | +1. A test utilities directory (`testUtils/`) that contains: |
| 10 | + - Type definitions (`types.ts`) |
| 11 | + - Data generation functions (`generators.ts`) |
| 12 | + - Utility functions (`utils.ts`) |
| 13 | + - A centralized data loader (`index.ts`) |
| 14 | + |
| 15 | +2. Coin-specific test data files in the resources directory (e.g., `cosmos.ts`, `cronos.ts`) |
| 16 | + |
| 17 | +3. Helper functions for tests in the unit directory |
| 18 | + |
| 19 | +## Directory Structure |
| 20 | + |
| 21 | +``` |
| 22 | +modules/sdk-coin-cosmos/test/ |
| 23 | +├── README.md # This documentation |
| 24 | +├── resources/ # Coin-specific test data |
| 25 | +│ ├── cosmos.ts # Cosmos test data |
| 26 | +│ └── cronos.ts # Cronos test data |
| 27 | +├── testUtils/ # Test utilities |
| 28 | +│ ├── index.ts # Main exports and data loader |
| 29 | +│ ├── types.ts # Type definitions |
| 30 | +│ ├── generators.ts # Data generation functions |
| 31 | +│ └── utils.ts # Utility functions |
| 32 | +└── unit/ # Unit tests |
| 33 | + ├── getBuilderFactory.ts # Builder factory utility |
| 34 | + └── ... (other test files) |
| 35 | +``` |
| 36 | + |
| 37 | +## Loading Test Data |
| 38 | + |
| 39 | +To load test data in your tests, use the `getTestData` function: |
| 40 | + |
| 41 | +```typescript |
| 42 | +import { getTestData, getAvailableTestCoins } from '../testUtils'; |
| 43 | + |
| 44 | +// Get all available test coins |
| 45 | +const availableCoins = getAvailableTestCoins(); |
| 46 | + |
| 47 | +// For each coin, load its test data |
| 48 | +availableCoins.forEach((coinName) => { |
| 49 | + const testData = getTestData(coinName); |
| 50 | + // Use testData in your tests |
| 51 | +}); |
| 52 | +``` |
| 53 | + |
| 54 | +## Adding a New Coin to the Test Framework |
| 55 | + |
| 56 | +To add support for a new Cosmos SDK-based coin to the test framework, follow these steps: |
| 57 | + |
| 58 | +### 1. Create a New Test Data File |
| 59 | + |
| 60 | +Create a new TypeScript file in the `test/resources` directory named after your coin (e.g., `newcoin.ts`). |
| 61 | + |
| 62 | +### 2. Import Required Dependencies |
| 63 | + |
| 64 | +```typescript |
| 65 | +import { generateCoinData } from '../testUtils/generators'; |
| 66 | +``` |
| 67 | + |
| 68 | +### 3. Define Chain Configuration |
| 69 | + |
| 70 | +Define the basic chain configuration (using Cronos as an example): |
| 71 | + |
| 72 | +```typescript |
| 73 | +export const chainConfig = { |
| 74 | + name: 'Cronos POS', |
| 75 | + coin: 'cronos', |
| 76 | + testName: 'Testnet Cronos POS', |
| 77 | + testCoin: 'tcronos', |
| 78 | + family: 'cronos', |
| 79 | + decimalPlaces: 8, |
| 80 | + baseDenom: 'basetcro', |
| 81 | + chainId: 'testnet-croeseid-4', |
| 82 | + addressPrefix: 'tcro', |
| 83 | + validatorPrefix: 'tcrocncl', |
| 84 | +}; |
| 85 | +``` |
| 86 | + |
| 87 | +### 4. Define Default Values |
| 88 | + |
| 89 | +Define default values that will be used throughout the configuration: |
| 90 | + |
| 91 | +```typescript |
| 92 | +export const DEFAULTS = { |
| 93 | + senderAddress: 'tcro1e9rxy3j3wph0lqjxr0ynu0t3zjfnhc0csyldtl', |
| 94 | + pubKey: 'AtlNaLjd5ijapNfxJCzOJV4pdMBouEomADHNgQEPulHL', |
| 95 | + privateKey: 'peFJjp2ECSNTRdKBfVhv8aGgoUBbmYPp2+l9prY5zjc=', |
| 96 | + recipientAddress1: 'tcro1rhs402vnjf7369yyjkk0nrskupmfl4yxpnaahj', |
| 97 | + recipientAddress2: 'tcro1u73cmemdgd5qx06cmtehr3z5pgswtar65f9sp54', |
| 98 | + sendMessageTypeUrl: '/cosmos.bank.v1beta1.MsgSend', |
| 99 | + sendAmount: '10000', |
| 100 | + feeAmount: '30000', |
| 101 | + gasLimit: 500000, |
| 102 | + validatorAddress1: 'tcrocncl1s4ggq2zuzvwg5k8vnx2xfwtdm4cz6wtnuqkl7a', |
| 103 | + validatorAddress2: 'tcrocncl163tv59yzgeqcap8lrsa2r4zk580h8ddr5a0sdd', |
| 104 | +}; |
| 105 | +``` |
| 106 | + |
| 107 | +### 5. Define Test Transactions |
| 108 | + |
| 109 | +Define test transactions with minimal required fields: |
| 110 | + |
| 111 | +```typescript |
| 112 | +export const TEST_SEND_TX = { |
| 113 | + hash: 'AF0E060E0B5FD6041010B7A93340A045286F48D03CDCC81C4C29D11730334AD1', |
| 114 | + signature: '5H3a5WlZS3yvL+muU8qPB1IlYBxvuu7vIDOQuIc0JMU06kNtj8arKQLH9NGEpweu3u84KXYURA+Qxo8AzoO8Zw==', |
| 115 | + signedTxBase64: 'CowBCokBChwvY29zbW9zLmJhbmsudjFiZXRhMS5Nc2dTZW5kEmkKK3Rjcm8xZTlyeHkzajN3cGgwbHFqeHIweW51MHQzempmbmhjMGNzeWxkdGwSK3Rjcm8xcmhzNDAydm5qZjczNjl5eWprazBucnNrdXBtZmw0eXhwbmFhaGoaDQoIYmFzZXRjcm8SATESawpQCkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohAtlNaLjd5ijapNfxJCzOJV4pdMBouEomADHNgQEPulHLEgQKAggBGAoSFwoRCghiYXNldGNybxIFMzAwMDAQoMIeGkDkfdrlaVlLfK8v6a5Tyo8HUiVgHG+67u8gM5C4hzQkxTTqQ22PxqspAsf00YSnB67e7zgpdhRED5DGjwDOg7xn', |
| 116 | + accountNumber: 10, |
| 117 | + sequence: 10, |
| 118 | + sendAmount: '1', |
| 119 | +}; |
| 120 | + |
| 121 | +// Define other test transactions... |
| 122 | +``` |
| 123 | + |
| 124 | +### 6. Generate Complete Coin Data |
| 125 | + |
| 126 | +Use the `generateCoinData` function to generate the complete coin data: |
| 127 | + |
| 128 | +```typescript |
| 129 | +export const cronos = generateCoinData(chainConfig, DEFAULTS, { |
| 130 | + TEST_SEND_TX, |
| 131 | + TEST_SEND_TX2, |
| 132 | + TEST_SEND_MANY_TX, |
| 133 | + TEST_TX_WITH_MEMO, |
| 134 | +}); |
| 135 | + |
| 136 | +export default cronos; |
| 137 | +``` |
| 138 | + |
| 139 | +### 7. Ensure Coin is Registered in BitGo Statics |
| 140 | + |
| 141 | +Make sure your coin is properly registered in the `@bitgo/statics` package. The test framework uses this to get coin configurations. |
| 142 | + |
| 143 | +### 8. Test Your Implementation |
| 144 | + |
| 145 | +Run the tests to verify that your coin implementation works correctly: |
| 146 | + |
| 147 | +```bash |
| 148 | +npm run test -- --grep="Cosmos" |
| 149 | +``` |
| 150 | + |
| 151 | +## Helper Functions |
| 152 | + |
| 153 | +The framework provides several helper functions to make it easier to create test data: |
| 154 | + |
| 155 | +- `generateCoinData`: Generates complete coin test data from chain config, defaults, and test transactions |
| 156 | +- `generateAddresses`: Generates test addresses from default values |
| 157 | +- `generateBlockHashes`: Generates standard block hashes for testing |
| 158 | +- `generateTxIds`: Generates transaction IDs from test transactions |
| 159 | +- `generateCoinAmounts`: Generates coin amounts for testing |
| 160 | +- `generateSendMessage`: Creates a standard transaction message for sending tokens |
| 161 | +- `generateGasBudget`: Creates a standard gas budget |
| 162 | +- `getTestData`: Loads test data for a specific coin |
| 163 | +- `getAvailableTestCoins`: Gets all available test coins |
| 164 | + |
| 165 | +## Best Practices |
| 166 | + |
| 167 | +1. **Minimize Configuration**: Keep your configuration minimal by defining only the essential properties. |
| 168 | +2. **Use Default Values**: Define default values that can be reused throughout the configuration. |
| 169 | +3. **Leverage Helper Functions**: Use the provided helper functions to generate common data structures. |
| 170 | +4. **Consistent Naming**: Follow the naming conventions used in existing test data files. |
| 171 | +5. **Complete Test Coverage**: Ensure your test data covers all the required fields and edge cases. |
| 172 | +6. **Documentation**: Add comments to explain any coin-specific peculiarities or requirements. |
0 commit comments