oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity

docs: add test scenarios for analytics and blockchain CLI commands

Browse Source
This commit is contained in:
oib
2026-03-05 09:02:13 +01:00
parent 4a13958e95
commit b14328f493
3 changed files with 297 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
docs/10_plan/cli-analytics-test-scenarios.md Normal file
View File

@@ -0,0 +1,131 @@
# CLI Analytics Commands Test Scenarios
This document outlines the test scenarios for the `aitbc analytics` command group. These scenarios are designed to verify the functionality, output formatting, and error handling of each analytics command.
## 1. `analytics alerts`
**Command Description:** View performance alerts across chains.
### Scenario 1.1: Default Alerts View
- **Command:** `aitbc analytics alerts`
- **Description:** Run the alerts command without any arguments to see all recent alerts in table format.
- **Expected Output:** A formatted table displaying alerts (or a message indicating no alerts if the system is healthy), showing severity, chain ID, message, and timestamp.
### Scenario 1.2: Filter by Severity
- **Command:** `aitbc analytics alerts --severity critical`
- **Description:** Filter alerts to show only those marked as 'critical'.
- **Expected Output:** Table showing only critical alerts. If none exist, an empty table or "No alerts found" message.
### Scenario 1.3: Time Range Filtering
- **Command:** `aitbc analytics alerts --hours 48`
- **Description:** Fetch alerts from the last 48 hours instead of the default 24 hours.
- **Expected Output:** Table showing alerts from the extended time period.
### Scenario 1.4: JSON Output Format
- **Command:** `aitbc analytics alerts --format json`
- **Description:** Request the alerts data in JSON format for programmatic parsing.
- **Expected Output:** Valid JSON array containing alert objects with detailed metadata.
---
## 2. `analytics dashboard`
**Command Description:** Get complete dashboard data for all chains.
### Scenario 2.1: JSON Dashboard Output
- **Command:** `aitbc analytics dashboard --format json`
- **Description:** Retrieve the comprehensive system dashboard data.
- **Expected Output:** A large JSON object containing:
- `chain_metrics`: Detailed stats for each chain (TPS, block time, memory, nodes).
- `alerts`: Current active alerts across the network.
- `predictions`: Any future performance predictions.
- `recommendations`: Optimization suggestions.
### Scenario 2.2: Default Dashboard View
- **Command:** `aitbc analytics dashboard`
- **Description:** Run the dashboard command without specifying format (defaults to JSON).
- **Expected Output:** Same comprehensive JSON output as 2.1.
---
## 3. `analytics monitor`
**Command Description:** Monitor chain performance in real-time.
### Scenario 3.1: Real-time Monitoring (Default Interval)
- **Command:** `aitbc analytics monitor --realtime`
- **Description:** Start a real-time monitoring session. (Note: May need manual termination `Ctrl+C`).
- **Expected Output:** A continuously updating display (like a top/htop view or appending log lines) showing current TPS, block times, and node health.
### Scenario 3.2: Custom Update Interval
- **Command:** `aitbc analytics monitor --realtime --interval 5`
- **Description:** Real-time monitoring updating every 5 seconds.
- **Expected Output:** The monitoring display updates at the specified 5-second interval.
### Scenario 3.3: Specific Chain Monitoring
- **Command:** `aitbc analytics monitor --realtime --chain-id ait-devnet`
- **Description:** Focus real-time monitoring on a single specific chain.
- **Expected Output:** Metrics displayed are exclusively for the `ait-devnet` chain.
---
## 4. `analytics optimize`
**Command Description:** Get optimization recommendations based on current chain metrics.
### Scenario 4.1: General Recommendations
- **Command:** `aitbc analytics optimize`
- **Description:** Fetch recommendations for all configured chains.
- **Expected Output:** A table listing the Chain ID, the specific Recommendation (e.g., "Increase validator count"), the target metric, and potential impact.
### Scenario 4.2: Chain-Specific Recommendations
- **Command:** `aitbc analytics optimize --chain-id ait-healthchain`
- **Description:** Get optimization advice only for the healthchain.
- **Expected Output:** Table showing recommendations solely for `ait-healthchain`.
### Scenario 4.3: JSON Output
- **Command:** `aitbc analytics optimize --format json`
- **Description:** Get optimization data as JSON.
- **Expected Output:** Valid JSON dictionary mapping chain IDs to arrays of recommendation objects.
---
## 5. `analytics predict`
**Command Description:** Predict chain performance trends based on historical data.
### Scenario 5.1: Default Prediction
- **Command:** `aitbc analytics predict`
- **Description:** Generate predictions for all chains over the default time horizon.
- **Expected Output:** Table displaying predicted trends for metrics like TPS, Block Time, and Resource Usage (e.g., "Trend: Stable", "Trend: Degrading").
### Scenario 5.2: Extended Time Horizon
- **Command:** `aitbc analytics predict --hours 72`
- **Description:** Generate predictions looking 72 hours ahead.
- **Expected Output:** Prediction table updated to reflect the longer timeframe analysis.
### Scenario 5.3: Specific Chain Prediction (JSON)
- **Command:** `aitbc analytics predict --chain-id ait-testnet --format json`
- **Description:** Get JSON formatted predictions for a single chain.
- **Expected Output:** JSON object containing predictive models/trends for `ait-testnet`.
---
## 6. `analytics summary`
**Command Description:** Get performance summary for chains over a specified period.
### Scenario 6.1: Global Summary (Table)
- **Command:** `aitbc analytics summary`
- **Description:** View a high-level summary of all chains over the default 24-hour period.
- **Expected Output:** A formatted table showing aggregated stats (Avg TPS, Min/Max block times, Health Score) per chain.
### Scenario 6.2: Custom Time Range
- **Command:** `aitbc analytics summary --hours 12`
- **Description:** Limit the summary to the last 12 hours.
- **Expected Output:** Table showing stats calculated only from data generated in the last 12 hours.
### Scenario 6.3: Chain-Specific Summary (JSON)
- **Command:** `aitbc analytics summary --chain-id ait-devnet --format json`
- **Description:** Detailed summary for a single chain in JSON format.
- **Expected Output:** Valid JSON object containing the `chain_id`, `time_range_hours`, `latest_metrics`, `statistics`, and `health_score` for `ait-devnet`.

163
docs/10_plan/cli-blockchain-test-scenarios.md Normal file
View File

@@ -0,0 +1,163 @@
# CLI Blockchain Commands Test Scenarios
This document outlines the test scenarios for the `aitbc blockchain` command group. These scenarios verify the functionality, argument parsing, and output formatting of blockchain operations and queries.
## 1. `blockchain balance`
**Command Description:** Get the balance of an address across all chains.
### Scenario 1.1: Valid Address Balance
- **Command:** `aitbc blockchain balance --address <valid_address>`
- **Description:** Query the balance of a known valid wallet address.
- **Expected Output:** A formatted display (table or list) showing the token balance on each configured chain.
### Scenario 1.2: Invalid Address Format
- **Command:** `aitbc blockchain balance --address invalid_addr_format`
- **Description:** Query the balance using an improperly formatted address.
- **Expected Output:** An error message indicating that the address format is invalid.
## 2. `blockchain block`
**Command Description:** Get details of a specific block.
### Scenario 2.1: Valid Block Hash
- **Command:** `aitbc blockchain block <valid_block_hash>`
- **Description:** Retrieve detailed information for a known block hash.
- **Expected Output:** Detailed JSON or formatted text displaying block headers, timestamp, height, and transaction hashes.
### Scenario 2.2: Unknown Block Hash
- **Command:** `aitbc blockchain block 0x0000000000000000000000000000000000000000000000000000000000000000`
- **Description:** Attempt to retrieve a non-existent block.
- **Expected Output:** An error message stating the block was not found.
## 3. `blockchain blocks`
**Command Description:** List recent blocks.
### Scenario 3.1: Default Listing
- **Command:** `aitbc blockchain blocks`
- **Description:** List the most recent blocks using default limits.
- **Expected Output:** A table showing the latest blocks, their heights, hashes, and timestamps.
### Scenario 3.2: Custom Limit and Starting Height
- **Command:** `aitbc blockchain blocks --limit 5 --from-height 100`
- **Description:** List exactly 5 blocks starting backwards from block height 100.
- **Expected Output:** A table with exactly 5 blocks, starting from height 100 down to 96.
## 4. `blockchain faucet`
**Command Description:** Mint devnet funds to an address.
### Scenario 4.1: Standard Minting
- **Command:** `aitbc blockchain faucet --address <valid_address> --amount 1000`
- **Description:** Request 1000 tokens from the devnet faucet.
- **Expected Output:** Success message with the transaction hash of the mint operation.
### Scenario 4.2: Exceeding Faucet Limits
- **Command:** `aitbc blockchain faucet --address <valid_address> --amount 1000000000`
- **Description:** Attempt to request an amount larger than the faucet allows.
- **Expected Output:** An error message indicating the requested amount exceeds maximum limits.
## 5. `blockchain genesis`
**Command Description:** Get the genesis block of a chain.
### Scenario 5.1: Retrieve Genesis Block
- **Command:** `aitbc blockchain genesis --chain-id ait-devnet`
- **Description:** Fetch the genesis block details for a specific chain.
- **Expected Output:** Detailed JSON or formatted text of block 0 for the specified chain.
## 6. `blockchain head`
**Command Description:** Get the head (latest) block of a chain.
### Scenario 6.1: Retrieve Head Block
- **Command:** `aitbc blockchain head --chain-id ait-testnet`
- **Description:** Fetch the current highest block for a specific chain.
- **Expected Output:** Details of the latest block on the specified chain.
## 7. `blockchain info`
**Command Description:** Get general blockchain information.
### Scenario 7.1: Network Info
- **Command:** `aitbc blockchain info`
- **Description:** Retrieve general metadata about the network.
- **Expected Output:** Information including network name, version, protocol version, and active chains.
## 8. `blockchain peers`
**Command Description:** List connected peers.
### Scenario 8.1: View Peers
- **Command:** `aitbc blockchain peers`
- **Description:** View the list of currently connected P2P nodes.
- **Expected Output:** A table listing peer IDs, IP addresses, latency, and connection status.
## 9. `blockchain send`
**Command Description:** Send a transaction to a chain.
### Scenario 9.1: Valid Transaction
- **Command:** `aitbc blockchain send --chain-id ait-devnet --from <sender_addr> --to <recipient_addr> --data "payload"`
- **Description:** Submit a standard transaction to a specific chain.
- **Expected Output:** Success message with the resulting transaction hash.
## 10. `blockchain status`
**Command Description:** Get blockchain node status.
### Scenario 10.1: Default Node Status
- **Command:** `aitbc blockchain status`
- **Description:** Check the status of the primary connected node.
- **Expected Output:** Operational status, uptime, current block height, and memory usage.
### Scenario 10.2: Specific Node Status
- **Command:** `aitbc blockchain status --node 2`
- **Description:** Check the status of node #2 in the local cluster.
- **Expected Output:** Status metrics specifically for the second node.
## 11. `blockchain supply`
**Command Description:** Get token supply information.
### Scenario 11.1: Total Supply
- **Command:** `aitbc blockchain supply`
- **Description:** View current token economics.
- **Expected Output:** Total minted supply, circulating supply, and burned tokens.
## 12. `blockchain sync-status`
**Command Description:** Get blockchain synchronization status.
### Scenario 12.1: Check Sync Progress
- **Command:** `aitbc blockchain sync-status`
- **Description:** Verify if the local node is fully synced with the network.
- **Expected Output:** Current block height vs highest known network block height, and a percentage progress indicator.
## 13. `blockchain transaction`
**Command Description:** Get transaction details.
### Scenario 13.1: Valid Transaction Lookup
- **Command:** `aitbc blockchain transaction <valid_tx_hash>`
- **Description:** Look up details for a known transaction.
- **Expected Output:** Detailed view of the transaction including sender, receiver, amount/data, gas used, and block inclusion.
## 14. `blockchain transactions`
**Command Description:** Get latest transactions on a chain.
### Scenario 14.1: Recent Chain Transactions
- **Command:** `aitbc blockchain transactions --chain-id ait-devnet`
- **Description:** View the mempool or recently confirmed transactions for a specific chain.
- **Expected Output:** A table listing recent transaction hashes, types, and status.
## 15. `blockchain validators`
**Command Description:** List blockchain validators.
### Scenario 15.1: Active Validators
- **Command:** `aitbc blockchain validators`
- **Description:** View the list of current active validators securing the network.
- **Expected Output:** A table of validator addresses, their total stake, uptime percentage, and voting power.

6
docs/10_plan/cli-checklist.md
View File

@@ -110,7 +110,7 @@ This checklist provides a comprehensive reference for all AITBC CLI commands, or
- [ ] `blockchain validators` — List blockchain validators
### **chain** — Multi-Chain Management
- [ ] `chain add` — Add a chain to a specific node
- [x] `chain add` — Add a chain to a specific node
- [ ] `chain backup` — Backup chain data
- [ ] `chain create` — Create a new chain from configuration file
- [ ] `chain delete` — Delete a chain permanently
@@ -122,7 +122,7 @@ This checklist provides a comprehensive reference for all AITBC CLI commands, or
- [ ] `chain restore` — Restore chain from backup
### **genesis** — Genesis Block Generation and Management
- [ ] `genesis create` — Create genesis block from configuration
- [x] `genesis create` — Create genesis block from configuration
- [ ] `genesis create-template` — Create a new genesis template
- [ ] `genesis export` — Export genesis block for a chain
- [ ] `genesis hash` — Calculate genesis hash
@@ -195,7 +195,7 @@ This checklist provides a comprehensive reference for all AITBC CLI commands, or
- [ ] `marketplace test` — OpenClaw marketplace testing operations
### **miner** — Mining Operations and Job Processing
- [ ] `miner concurrent-mine` — Mine with concurrent job processing
- [x] `miner concurrent-mine` — Mine with concurrent job processing
- [ ] `miner deregister` — Deregister miner from the coordinator
- [ ] `miner earnings` — Show miner earnings
- [ ] `miner heartbeat` — Send heartbeat to coordinator