docs: add swapper execution testing requirements by NeOMakinG · Pull Request #11523 · shapeshift/web

NeOMakinG · 2025-12-24T11:19:17Z

Summary

Adds comprehensive testing requirements for swapper-related PRs to ensure actual swap execution verification before merging to production.

Problem

Previously, swapper integration PRs could be merged without executing actual swaps, relying only on quote fetching verification. This approach missed critical issues that only surface during transaction execution:

Fee calculation accuracy
Balance update correctness
Transaction completion reliability
Edge case handling
Cross-chain bridge functionality

Solution

This PR establishes clear testing requirements for all swapper-related work:

When Required

Execute actual swaps for PRs involving:

New swapper integrations (Bebop, Portals, Jupiter, etc.)
Swapper behavior changes (fees, quotes, routes)
Chain adapter modifications affecting swaps
Quote aggregation changes

Minimum Testing Scope

At least 2 successful swaps per PR
Primary + secondary swap directions
Comprehensive testing checklist:
- Quote accuracy verification
- Balance update confirmation
- Fee estimation validation
- Transaction completion
- Error handling
- Multi-chain support (if applicable)
- Price impact accuracy
- Slippage tolerance

Documentation Template

Provides a standardized template for documenting swap execution test results in PR comments, including:

Pre/post-swap balances
Quote details and verification
Transaction hashes and explorer links
Observed issues or limitations

Example Report

References .playwright-mcp/swap-execution-test-report.md as a comprehensive testing example showing:

Plasma (XPL) swap via Relay (cross-chain bridge)
SUI swap via Cetus (native DEX)

Both swaps executed successfully with accurate rates and balance updates.

Benefits

Production Readiness: Catch execution-specific issues before merging
Quality Assurance: Ensure swaps actually work, not just quote fetching
Documentation: Standardized test reporting for review
Best Practices: Clear guidelines for all swapper integrations

Testing

See the newly added section in docs/testing.md:

Comprehensive swapper integration testing requirements
Testing checklist and best practices
Documentation template
Example test reports

Summary by CodeRabbit

Documentation
- Added comprehensive testing guidelines for swapper integration, including testing scope, verification checklist, methodology, local development setup instructions, documentation standards, best practices, and example test reports.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Add comprehensive testing requirements for swapper-related PRs to ensure actual swap execution verification before merging. Key additions: - When swap execution testing is required (new integrations, behavior changes, etc.) - Minimum testing scope (2+ successful swaps) - Comprehensive testing checklist - Testing methodology and best practices - Required test documentation template - Reference to example test reports This ensures production readiness for all swapper integrations by requiring real swap execution tests, not just quote fetching. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

coderabbitai · 2025-12-24T11:19:23Z

📝 Walkthrough

Walkthrough

Documentation update adds comprehensive guidance for swapper integration testing to docs/testing.md. The new section covers when testing is required, scope specifications, verification checklists, methodology, local development procedures, documentation requirements, best practices, and example test reports.

Changes

Cohort / File(s)	Summary
Swapper Integration Testing Documentation `docs/testing.md`	Added extensive documentation section covering testing requirements, scope (minimum swaps, cross-chain tests), comprehensive testing checklist, methodology, local development steps, test documentation guidelines, best practices, and example test reports

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

feat: add testing scenarios and testing agent #11491: Adds overlapping swapper integration and test-scenario documentation that complements this PR's comprehensive swapper testing guidance.

Suggested reviewers

gomesalexandre
0xApotheosis

Poem

🐰 Hops of joy, the docs now gleam,
Testing swaps—a thorough dream!
Checklists, steps, and best-practice ways,
Documentation brightens all our days! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add swapper execution testing requirements' directly and clearly summarizes the main change—adding documentation about testing requirements for swapper execution.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch docs/swapper-execution-testing-requirements

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between bfcc0df and b627560.

📒 Files selected for processing (1)

docs/testing.md

🧰 Additional context used

🧠 Learnings (8)

📓 Common learnings

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/error-handling.mdc:0-0
Timestamp: 2025-11-24T21:20:17.804Z
Learning: Applies to **/swapper{s,}/**/*.{ts,tsx} : ALWAYS use `makeSwapErrorRight` for swapper errors with `TradeQuoteError` enum for error codes and provide detailed error information

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/**/*.test.ts : Write unit tests for swapper methods and API endpoints

Learnt from: CR
Repo: shapeshift/web PR: 0
File: .cursor/rules/swapper.mdc:0-0
Timestamp: 2025-11-24T21:20:57.909Z
Learning: Applies to packages/swapper/src/swappers/*/*.ts : Reuse executeEvmTransaction utility for EVM-based swappers instead of implementing custom transaction execution

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10323
File: src/pages/RFOX/components/Stake/components/StakeSummary.tsx:112-114
Timestamp: 2025-08-22T13:00:44.879Z
Learning: NeOMakinG prefers to keep PR changes minimal and focused on the core objectives, avoiding cosmetic or defensive code improvements that aren't directly related to the PR scope, even when they would improve robustness.

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10128
File: .cursor/rules/error-handling.mdc:266-274
Timestamp: 2025-07-29T10:35:22.059Z
Learning: NeOMakinG prefers less nitpicky suggestions on documentation and best practices files, finding overly detailed suggestions on minor implementation details (like console.error vs logger.error) too granular for cursor rules documentation.

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10380
File: src/pages/Dashboard/components/AccountList/AccountTable.tsx:60-0
Timestamp: 2025-09-02T08:34:08.157Z
Learning: NeOMakinG prefers code review comments to focus only on actual PR changes, not pre-existing code issues, unless there are critical security or correctness concerns directly related to the new functionality.

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10234
File: src/components/MultiHopTrade/hooks/useGetTradeQuotes/hooks/useTrackTradeQuotes.ts:42-86
Timestamp: 2025-08-08T11:41:22.794Z
Learning: NeOMakinG prefers not to include refactors in move-only PRs; such suggestions should be deferred to follow-up issues instead of being applied within the same PR.

Learnt from: NeOMakinG
Repo: shapeshift/web PR: 10380
File: src/components/Table/Table.theme.ts:177-180
Timestamp: 2025-09-02T12:38:46.940Z
Learning: NeOMakinG prefers to defer technical debt and CSS correctness issues (like improper hover selectors) to follow-up PRs when the current PR is already large and focused on major feature implementation, even when the issues are valid from a usability/technical perspective.