test: add integration tests for Intuition Protocol

[simonas-notcat]

Summary

This PR adds a comprehensive integration test suite for testing the GitHub Action against a live Intuition Protocol testnet deployment. This enables end-to-end validation of the action's core functionality including atom creation, triple operations, and complete attestation workflows.

Integration Tests Added

• Intuition Protocol Integration Tests

  • atoms.integration.test.ts: Tests atom creation, retrieval, and management operations
  • client.integration.test.ts: Tests client initialization, authentication, and error handling
  • triples.integration.test.ts: Tests triple creation, deposits, redemptions, and batch operations

• Service Integration Tests

  • attestation.integration.test.ts: Tests complete attestation workflow including batch processing, error handling, and edge cases

Test Infrastructure

• Test environment setup with live testnet configuration (__tests__/integration/setup/test-env.ts)
• GitHub API mocking helpers for realistic test scenarios (__tests__/integration/helpers/github-mocks.ts)
• Comprehensive test data fixtures (__tests__/integration/helpers/test-data.ts)
• .env.integration.example template for configuration
• jest.integration.config.js for integration test configuration
• Dedicated README with setup instructions (__tests__/integration/README.md)

GitHub Workflow

• New workflow: test-attestation-post-merge.yml
• Runs integration tests after merges to main
• Executes on push to main and pull requests to main
• Supports manual workflow dispatch for on-demand testing
• Secured with required environment variables

Documentation & Configuration

• Updated main README with integration testing section
• Added integration test setup instructions
• Updated .gitignore to exclude local .env files
• Added npm run test:integration script to package.json

Source Code Improvements

• Enhanced error handling in Intuition client methods
• Improved type exports for better testability
• Network configuration refinements for testnet consistency
• Minor code improvements to support integration testing

Testing

This test suite complements the existing unit tests (68 tests, 36.53% coverage) and provides confidence that the action works correctly with real blockchain interactions.

To run integration tests locally:

# Copy and configure environment variables
cp .env.integration.example .env.integration

# Edit .env.integration with your testnet credentials

# Run integration tests
npm run test:integration

Test Plan

• Integration tests pass locally against testnet
• Unit tests continue to pass
• Bundle is up to date
• Code formatting and linting pass
• Documentation is clear and complete

🤖 Generated with Claude Code

[claude]

Pull Request Review: Integration Tests for Intuition Protocol

Summary

This PR adds comprehensive integration testing infrastructure for the Intuition GitHub Action. The implementation is well-structured, thoroughly documented, and follows best practices. Overall, this is an excellent addition that significantly improves the project's test coverage and reliability.

✅ Strengths

1. Excellent Test Architecture

• Clear separation between unit and integration tests with dedicated Jest configs
• Well-organized test structure: atoms, triples, client, and attestation test suites
• Good use of helper utilities (test-data.ts, github-mocks.ts) for DRY code
• Proper environment setup with validation in test-env.ts

2. Comprehensive Test Coverage

The integration tests cover critical paths:

• ✅ Atom creation and idempotency
• ✅ Triple creation and deposits
• ✅ Transaction confirmations and cost tracking
• ✅ End-to-end attestation workflows
• ✅ Error handling modes (fail vs warn)
• ✅ Multi-contributor scenarios

3. Security-Conscious Design

• Proper .gitignore for .env.local files
• Clear warnings about real blockchain transactions
• Masked private key display in console output (test-env.ts:51)
• Dedicated testnet wallet recommendations

4. Excellent Documentation

• Comprehensive __tests__/integration/README.md with setup instructions
• Clear cost estimates and execution time expectations
• .env.integration.example with helpful inline comments and warnings
• Updated main README with integration test section

5. Smart Post-Merge Workflow

The test-attestation-post-merge.yml workflow is well-designed:

• Only runs on actual merges (not just closes)
• Validates outputs thoroughly with regex and JSON parsing
• Provides Intuition Explorer links for verification
• Non-blocking with continue-on-error and failure-mode: warn

🔍 Areas for Improvement

1. Error Handling in triples.ts (Minor)

Location: src/intuition/triples.ts:102-103, triples.ts:148-149

The TransactionFailedError is instantiated with undefined as the second argument:

throw new TransactionFailedError(
  `Failed to deposit to triple: ...`,
  undefined  // ⚠️ What is this parameter?
)

Recommendation: Review the TransactionFailedError constructor signature. If the second parameter is optional, omit it. If it should contain the original error, pass error instead of undefined.

2. Test Environment Validation (Minor)

Location: __tests__/integration/setup/test-env.ts:40

The private key validation is basic:

if (\!privateKey?.startsWith('0x') || privateKey.length \!== 66) {
  throw new Error(...)
}

Recommendation: Add a check to verify the key contains only valid hex characters:

if (\!privateKey?.startsWith('0x') || 
    privateKey.length \!== 66 ||
    \!/^0x[0-9a-fA-F]{64}$/.test(privateKey)) {
  throw new Error('INTUITION_PRIVATE_KEY must be a valid hex string (0x + 64 hex chars)')
}

3. Workflow Validation Edge Cases (Minor)

Location: .github/workflows/test-attestation-post-merge.yml:83

The contributor count validation allows zero:

if \! [[ "$count" =~ ^[0-9]+$ ]] || [ "$count" -eq 0 ]; then

This is correct! However, the error message could be more specific:

echo "ERROR: contributor-count must be a positive number (got: $count)"

4. Missing Type Safety in Tests

Location: __tests__/integration/services/attestation.integration.test.ts:338

Type assertion using as any:

expect(summary2.projectAtomTxHash).toBe('0x0' as any)

Recommendation: Use proper type assertion:

expect(summary2.projectAtomTxHash).toBe('0x0' as Hex)

(Import Hex type from viem if not already imported)

5. Hardcoded Network Reference

Location: __tests__/integration/setup/test-env.ts:55

console.log(`Network: Base Sepolia (testnet)`)

Recommendation: The action now uses "Intuition Testnet" (not Base Sepolia) based on the updated README. Update the console message to match:

console.log(`Network: Intuition Testnet`)

6. Potential Race Conditions in Integration Tests

Good: Tests already use --runInBand in package.json:43 to run sequentially.

Observation: Some tests may still have conflicts if run multiple times simultaneously (e.g., by different developers). The timestamp-based unique suffixes help, but consider documenting this limitation in the integration README.

🛡️ Security Considerations

✅ Good Security Practices:

1. No hardcoded private keys
2. Proper .gitignore entries
3. Clear warnings about testnet-only wallets
4. Private key masking in console output
5. GitHub secrets used correctly in workflow

⚠️ Recommendations:

1. Consider adding a pre-commit hook to prevent accidentally committing .env.local or .env files with keys
2. Document wallet rotation best practices for the testnet wallet in the README

📊 Performance Considerations

✅ Well-Designed:

• Appropriate timeouts (2-6 minutes) for blockchain operations
• Sequential execution (--runInBand) to avoid race conditions
• Retry logic with exponential backoff
• Balance checking before operations to fail fast

💡 Suggestions:

1. Consider adding a "smoke test" subset that runs faster for quick validation
2. Document expected costs per test suite (you've done this well in the README!)

🧪 Test Quality

✅ Excellent:

• Tests verify actual blockchain state (transaction hashes, block numbers)
• Proper assertions on cost tracking and idempotency
• Edge cases covered (existing atoms, multiple contributors, error modes)
• Realistic test data with timestamps for uniqueness

💡 Suggestions:

1. Consider adding a test that verifies the actual on-chain data matches expected values (could query the Intuition SDK to verify atom/triple properties)
2. Add a test for the maximum number of contributors in a batch to identify gas limits

📝 Documentation Quality

✅ Outstanding:

• Integration README is comprehensive and helpful
• Cost estimates are provided
• Troubleshooting section is excellent
• Clear warnings about real blockchain usage

💡 Minor Improvements:

1. Add a "Quick Start" section at the top of __tests__/integration/README.md
2. Consider adding a diagram showing the test flow (optional)

🔧 Code Quality

✅ Strengths:

• TypeScript types properly imported and used
• ESM imports follow project conventions (.js extensions)
• Error handling is consistent
• Logging is appropriate (using core.info, core.debug, console.log)

Source Code Changes Review:

src/intuition/client.ts (client.ts:86-97):

• ✅ Good addition of balance checking on client creation
• ✅ Proper use of retry logic
• ✅ Informative logging

src/intuition/atoms.ts & src/intuition/triples.ts:

• ✅ Minimal changes (just type exports)
• ✅ Maintains backward compatibility

🎯 Overall Assessment

Aspect	Rating	Notes
Code Quality	⭐⭐⭐⭐⭐	Clean, well-structured, follows conventions
Test Coverage	⭐⭐⭐⭐⭐	Comprehensive coverage of critical paths
Documentation	⭐⭐⭐⭐⭐	Excellent README and inline documentation
Security	⭐⭐⭐⭐⭐	Proper handling of secrets and warnings
Performance	⭐⭐⭐⭐☆	Good, minor optimization opportunities

✅ Recommendation

APPROVE - This PR is ready to merge with the minor suggestions above addressed in future iterations (none are blocking).

🚀 Post-Merge Actions

1. Ensure INTUITION_PRIVATE_KEY secret is configured in repository settings
2. Fund the testnet wallet with tTRUST from the faucet
3. Monitor the first post-merge workflow run to verify everything works
4. Consider documenting the cost per month for running integration tests (if run regularly)

---

Great work on this comprehensive integration test suite! This will significantly improve confidence in the action's reliability when working with real blockchain transactions. 🎉