Qa

How to Use This Checklist

For each item:

• PASS: The item meets the requirement. Note what you verified.
• FAIL: The item does not meet the requirement. Include specific evidence (file path, screenshot description, error message).
• N/A: The item does not apply to this dApp (e.g., no token approvals needed).

Report format:

## QA Report: [dApp Name]
Date: [date]
Reviewer: [agent name]
Deployment URL: [url]
Repository: [repo url]

### Results Summary
- PASS: X
- FAIL: Y
- N/A: Z

### Detailed Findings
[Each item below with PASS/FAIL/N/A and evidence]

Section 1: Button States and Transaction Flow

1.1 Individual Button Loading States

Requirement: Every button that triggers an onchain transaction has its OWN independent loading/disabled state.

How to test:

1. Open browser devtools, go to Network tab, enable "Slow 3G" throttling
2. Click a transaction button
3. While that button is loading, verify OTHER buttons are NOT also showing loading/disabled state
4. Verify the clicked button shows a spinner AND is disabled (cannot be clicked again)

What to look for in code:

# Search for shared isLoading state — this is a FAIL
grep -r "isLoading" packages/nextjs/
# Each onchain button should use its own isMining from useScaffoldWriteContract

PASS criteria: Each button has independent state. Clicking "Deposit" does not disable "Withdraw."

FAIL criteria: Multiple buttons share a single isLoading variable, OR a button can be clicked multiple times while a transaction is pending.

1.2 Double-Click Prevention

Requirement: After clicking a transaction button, it must be immediately disabled until the transaction completes or fails.

How to test:

1. Click a transaction button rapidly (double-click, triple-click)
2. Only ONE transaction should be submitted to the wallet

PASS criteria: Only one wallet prompt appears regardless of click speed.

FAIL criteria: Multiple wallet prompts appear, or multiple transactions are submitted.

1.3 Approval Flow

Requirement: Token interactions follow the three-step flow: Switch Network (if needed) -> Approve Token -> Execute Transaction. Only ONE button is visible at each step.

How to test:

1. Connect wallet on wrong network — should see "Switch to [Chain]" button only
2. Switch network — should see "Approve [Token]" button only (if approval needed)
3. Approve — should see the action button ("Deposit 100 USDC") only
4. Execute — should show loading, then success

What to look for in code:

# Search for approval logic
grep -rn "approve\|allowance" packages/nextjs/
# Verify conditional rendering (if/else, not three buttons side by side)

PASS criteria: One button visible at each step, clear labels indicating the action.

FAIL criteria: Multiple action buttons visible simultaneously, OR no approval step for ERC-20 transfers, OR generic "Submit" labels without token name/amount.

Section 2: Wallet Connection

2.1 Fresh Wallet Connection

Requirement: A user with no prior connection to this dApp can connect their wallet and interact.

How to test:

1. Open the dApp in an incognito/private browser window
2. Click "Connect Wallet"
3. Select a wallet provider
4. Verify the connection succeeds
5. Verify the UI updates to show the connected address

PASS criteria: Clean connection flow, address displayed after connecting.

FAIL criteria: Connection fails, UI does not update, or error appears.

2.2 Network Switching

Requirement: If the user is on the wrong network, the dApp prompts them to switch.

How to test:

1. Connect wallet on a different network than the dApp expects
2. Attempt to perform an action
3. Should see a "Switch to [Chain]" prompt

PASS criteria: Clear prompt to switch networks, switching works when clicked.

FAIL criteria: Transaction is attempted on wrong network, cryptic error, or no network prompt.

2.3 Disconnect and Reconnect

Requirement: Disconnecting and reconnecting works without page refresh.

How to test:

1. Connect wallet
2. Disconnect
3. Reconnect
4. Verify all functionality still works

PASS criteria: Full functionality after reconnect without refresh.

FAIL criteria: Stale state, errors, or need to refresh the page.

Section 3: Scaffold-ETH 2 Branding Cleanup

3.1 Default Branding Removed

Requirement: The dApp should NOT look like a default Scaffold-ETH 2 app. Custom branding should be applied.

What to check:

• Page title is NOT "Scaffold-ETH 2 App" or similar default
• Favicon is NOT the Scaffold-ETH default
• Header/footer does not say "Scaffold-ETH" (unless it is a Scaffold-ETH project)
• Default example pages are removed (Debug Contracts page is for development only)
• Default hero section or landing page content is customized
• Meta tags (og:title, og:description, og:image) are set for the actual project

What to look for in code:

# Check page title
grep -r "Scaffold-ETH\|scaffold-eth\|SE-2" packages/nextjs/app/layout.tsx
# Check meta tags
grep -r "og:title\|og:description\|og:image" packages/nextjs/
# Check for debug page still accessible in production
ls packages/nextjs/app/debug/

PASS criteria: App has its own identity — title, favicon, branding, and content.

FAIL criteria: Any default Scaffold-ETH branding visible in production.

3.2 Debug Page Removed or Hidden

Requirement: The Debug Contracts page (/debug) should not be accessible in production.

How to test: Navigate to /debug in the production deployment.

PASS criteria: Page returns 404 or redirects, or is behind authentication.

FAIL criteria: Debug page is publicly accessible with contract interaction tools.

Section 4: Data Display

4.1 USD Values Present

Requirement: Every token amount in the UI has a USD equivalent displayed alongside it.

What to check:

• ETH amounts show USD value
• ERC-20 token amounts show USD value
• Gas estimates show USD cost
• Portfolio/balance views show total USD value

PASS criteria: USD values present next to all token amounts.

FAIL criteria: Any token amount displayed without USD equivalent.

4.2 Token Decimals Correct

Requirement: Token amounts are displayed with correct decimal precision.

What to check:

• ETH: 18 decimals internally, display 4-6 decimal places
• USDC: 6 decimals internally, display 2 decimal places
• USDT: 6 decimals internally, display 2 decimal places
• DAI: 18 decimals internally, display 2 decimal places
• WBTC: 8 decimals internally, display 6-8 decimal places

How to test:

1. Check a known balance against what the block explorer shows
2. Verify the decimal places match

What to look for in code:

# Search for hardcoded 18 decimals (common mistake for USDC/USDT)
grep -rn "parseEther\|formatEther" packages/nextjs/
# USDC/USDT should use parseUnits(amount, 6) / formatUnits(amount, 6)

PASS criteria: All token amounts display correctly with appropriate precision.

FAIL criteria: Token amounts off by orders of magnitude (USDC showing as 0.000001 instead of 1.0), or too many/few decimal places.

4.3 Large Numbers Formatted

Requirement: Large numbers are human-readable with comma separators or abbreviations.

What to check:

• 1000000 should display as 1,000,000 or 1M
• 0.000000001 should NOT be displayed — show < 0.0001 or similar

PASS criteria: All numbers are formatted for readability.

FAIL criteria: Raw unformatted numbers displayed.

4.4 Address Display

Requirement: All Ethereum addresses use proper display components with ENS resolution.

What to check:

• No raw 42-character hex strings displayed in the UI
• Addresses are truncated (0x742d...2bD28)
• Copy-to-clipboard functionality
• Block explorer links
• ENS names resolved where available

What to look for in code:

# Search for raw address rendering
grep -rn "address.*0x\|{address}" packages/nextjs/components/
# Should be using <Address /> component
grep -rn "from.*scaffold-eth.*Address\|<Address" packages/nextjs/

PASS criteria: All addresses use <Address /> or equivalent component.

FAIL criteria: Any raw hex address displayed without truncation, copy, or explorer link.

Section 5: Error Handling

5.1 User Rejection Handled

Requirement: When a user rejects a transaction in their wallet, the UI handles it gracefully.

How to test:

1. Initiate a transaction
2. Click "Reject" in the wallet popup
3. The UI should show "Transaction cancelled" or similar — NOT an error stack trace

PASS criteria: Friendly message, no error state, button returns to clickable.

FAIL criteria: Error toast with technical message, button stays in loading state, or unhandled promise rejection in console.

5.2 Insufficient Funds Handled

Requirement: When a user does not have enough ETH for gas, the error message is clear.

How to test: Attempt a transaction with a wallet that has near-zero ETH balance.

PASS criteria: Message like "Insufficient ETH for gas" or similar human-readable text.

FAIL criteria: Raw error message like "insufficient funds for intrinsic transaction cost."

5.3 Revert Reasons Displayed

Requirement: When a contract call reverts, the revert reason is shown in human-readable form.

How to test: Trigger a known revert condition (e.g., try to withdraw more than your balance).

PASS criteria: Clear message explaining why the transaction failed.

FAIL criteria: Generic "Transaction failed" with no context, or raw hex revert data.

5.4 Network Errors Handled

Requirement: If the RPC endpoint is unreachable, the UI handles it gracefully.

How to test: Disconnect internet briefly, or check what happens with a slow connection.

PASS criteria: Error message about connectivity, retry option.

FAIL criteria: Blank page, infinite spinner, or unhandled exception.

Section 6: Mobile Testing

6.1 Layout and Responsiveness

Requirement: The dApp is fully functional on mobile viewport sizes.

How to test:

1. Open in browser devtools with mobile viewport (375px width)
2. Check every page
3. Verify no horizontal scrolling
4. Verify all buttons are tappable (minimum 44px height)
5. Verify text is readable

PASS criteria: Full functionality, no layout breaks, readable text.

FAIL criteria: Horizontal scroll, overlapping elements, text too small, buttons too small to tap.

6.2 Mobile Wallet Connection

Requirement: Wallet connection works on mobile devices.

How to test: Open the dApp in a mobile wallet's in-app browser (MetaMask mobile, Coinbase Wallet mobile).

PASS criteria: Wallet connects, transactions can be signed.

FAIL criteria: Connection fails, wallet not detected, or signing does not work.

6.3 Address and Number Overflow

Requirement: Long strings (addresses, large numbers) do not break the layout.

How to test: Check all address displays and number displays at mobile width.

PASS criteria: Addresses truncated, numbers formatted, no overflow.

FAIL criteria: Any text overflows its container or causes horizontal scroll.

Section 7: Security

7.1 No Secrets in Code

Requirement: No private keys, API secrets, or sensitive credentials in the committed codebase.

How to test:

# Search for potential secrets
grep -rn "PRIVATE_KEY\|private_key\|secret\|password" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.json" .
grep -rn "0x[a-fA-F0-9]{64}" --include="*.ts" --include="*.tsx" . | grep -v "node_modules\|deployedContracts"
# Check .env files are not committed
git ls-files | grep -i "\.env"
# Check .gitignore
cat .gitignore | grep -i "env"

PASS criteria: No secrets found, .env in .gitignore, no private keys in git history.

FAIL criteria: Any secret, private key, or API key with embedded credentials found in code or git history.

7.2 RPC URLs Clean

Requirement: No RPC URLs with embedded API keys in client-side code.

How to test:

grep -rn "alchemy.com\|infura.io\|quicknode.com" --include="*.ts" --include="*.tsx" packages/nextjs/
# Should only find references via environment variables, never hardcoded keys

PASS criteria: RPC URLs use environment variables or public endpoints.

FAIL criteria: API keys visible in source code.

7.3 No Exposed Admin Functions

Requirement: Admin or owner-only functions are not callable from the production UI by regular users.

How to test: Check if there are admin panels or owner functions accessible without authentication.

PASS criteria: Admin functions are hidden or access-controlled.

FAIL criteria: Admin functions (pause, withdraw, setPrice, etc.) accessible to any connected wallet.

Section 8: Gas and Transactions

8.1 Gas Estimates Reasonable

Requirement: Gas estimates shown to users are reasonable for the operations performed.

How to test: Compare estimated gas with actual gas used for completed transactions.

PASS criteria: Estimates within 20% of actual gas used.

FAIL criteria: Estimates wildly off (2x+ or showing unreasonably high gas).

8.2 Transaction Confirmation Feedback

Requirement: Users see clear feedback for transaction lifecycle: pending -> confirmed or failed.

How to test:

1. Submit a transaction
2. Verify a "pending" or "confirming" state is shown
3. Verify a "confirmed" state appears after the transaction is mined
4. Verify a "failed" state appears if the transaction reverts

PASS criteria: Clear lifecycle feedback at each stage.

FAIL criteria: No pending state, or success shown before confirmation, or no failure feedback.

8.3 All External Calls Have Error Handling

Requirement: Every writeContractAsync, fetch, or external API call is wrapped in try/catch.

How to test:

# Search for unhandled async calls
grep -rn "writeContractAsync\|writeContract(" packages/nextjs/ | grep -v "try\|catch\|\.then"
grep -rn "await fetch(" packages/nextjs/ | grep -v "try\|catch"

PASS criteria: All external calls wrapped in error handling.

FAIL criteria: Any await call to an external service without try/catch.

Section 9: Final Checks

9.1 Console Clean

Requirement: No errors or warnings in the browser console during normal operation.

How to test: Open browser devtools console, navigate through all pages, perform all actions.

PASS criteria: No errors. Warnings acceptable only if from third-party libraries.

FAIL criteria: Any error in console during normal operation.

9.2 All Links Work

Requirement: No broken links in the application.

How to test: Click every link in the navigation, footer, and content.

PASS criteria: All links resolve correctly.

FAIL criteria: Any 404 or broken link.

9.3 Loading States for Initial Data

Requirement: Pages show loading indicators while fetching initial data, not blank/empty content.

How to test: Hard refresh (Ctrl+Shift+R) and watch the page load.

PASS criteria: Skeleton screens, spinners, or loading text while data loads.

FAIL criteria: Blank sections that suddenly populate, causing layout shift.

Report Template

Copy this template for your QA report:

## QA Report: [dApp Name]

**Date**: [date]
**Reviewer**: [agent name]
**Deployment URL**: [url]
**Repository**: [repo url]
**Chain**: [chain name and ID]

### Summary

| Category | PASS | FAIL | N/A |
|----------|------|------|-----|
| Button States | | | |
| Wallet Connection | | | |
| Branding | | | |
| Data Display | | | |
| Error Handling | | | |
| Mobile | | | |
| Security | | | |
| Gas & Transactions | | | |
| Final Checks | | | |
| **TOTAL** | | | |

### Critical Failures (must fix before ship)

1. [Finding]
2. [Finding]

### Medium Findings (should fix)

1. [Finding]
2. [Finding]

### Minor Findings (nice to fix)

1. [Finding]
2. [Finding]

### Detailed Results

[Each checklist item with PASS/FAIL/N/A and evidence]

Your job is to fill this out honestly. Do not soft-pedal failures. A FAIL is a FAIL — note exactly what is wrong and where. The build agent will use your report to fix issues.