7.6 KiB
E2E Test Setup Guide
Prerequisites
- Node.js ≥20.x
- npm ≥11.x
- Git
- Hardhat (for blockchain tests)
Installation
1. Install E2E Test Dependencies
cd /Users/z/work/zoo/zoo/e2e
npm install
npx playwright install
2. Fix Hardhat Dependency Issue
The contracts directory requires an additional dependency that has version conflicts. To resolve:
cd /Users/z/work/zoo/zoo/contracts
# Option 1: Install with legacy peer deps (recommended)
npm install --legacy-peer-deps
# Option 2: Install specific package if still needed
npm install --save-dev @ethersproject/hardware-wallets --legacy-peer-deps
3. Verify Installation
cd /Users/z/work/zoo/zoo/e2e
npm run test:setup
Expected output: 12 passed
Running Tests
All Tests
npm test
Specific Test Suites
# Setup verification
npm run test:setup
# Infrastructure (blockchain) tests
npm run test:infrastructure
# Smart contract tests
npm run test:contracts
# dApp UI tests
npm run test:dapps
# Integration tests
npm run test:integration
Development Mode
# UI mode (interactive)
npm run test:ui
# Headed mode (see browser)
npm run test:headed
# Debug mode
npm run test:debug
Test Structure
e2e/
├── tests/
│ ├── 00-setup/ # Environment verification
│ ├── 01-infrastructure/ # Blockchain tests
│ ├── 02-contracts/ # Smart contract tests
│ │ ├── tokens.spec.ts # ZOO, KEEPER token tests
│ │ └── governance.spec.ts # Governor, Timelock, Safe tests
│ ├── 03-dapps/ # dApp UI tests
│ │ ├── zoo-computer.spec.ts # E-commerce site tests
│ │ └── zoo-vote-dao.spec.ts # DAO governance UI tests
│ └── 04-integration/ # Full end-to-end tests
├── fixtures/ # Test utilities
│ ├── blockchain.ts # Hardhat node management
│ ├── contracts.ts # Contract deployment
│ ├── wallets.ts # Test wallets
│ └── apps.ts # dApp server management
└── helpers/ # Test helpers
├── assertions.ts # Custom assertions
└── selectors.ts # UI selectors
Known Issues
Issue 1: Hardhat Dependency Error
Error:
Error HH801: Plugin hardhat-deploy requires the following dependencies to be installed: @ethersproject/hardware-wallets.
Solution:
cd /Users/z/work/zoo/zoo/contracts
npm install --legacy-peer-deps
This resolves the peer dependency conflict between ethers v5 and v6.
Issue 2: npm "Cannot read properties of null"
Error:
npm error Cannot read properties of null (reading 'matches')
Solution: This is usually caused by corrupted npm cache. Fix with:
npm cache clean --force
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps
Issue 3: Port Already in Use
Error:
Error: Port 8545 is already in use
Solution:
# Find and kill process using port 8545
lsof -ti:8545 | xargs kill -9
# Or restart blockchain fixture (automatic in tests)
Issue 4: Test Timeout
Error:
Error: Blockchain failed to start within 30000ms
Solution: Increase timeout in test configuration or ensure Hardhat dependencies are installed properly.
DAO Testing Workflow
1. Start Local Blockchain
cd /Users/z/work/zoo/zoo/contracts
npx hardhat node
This starts a local blockchain on port 8545 with 20 test accounts.
2. Deploy Governance Contracts
# In another terminal
cd /Users/z/work/zoo/zoo/contracts
npx hardhat run scripts/deploy-governance.ts --network localhost
This deploys:
- ZOO Token (governance token)
- Governor (proposal/voting)
- Timelock (execution delay)
3. Start Vote dApp
cd /Users/z/work/zoo/zoo/dao-governance/app
npm run dev
Visit: http://localhost:3004
4. Run DAO Tests
cd /Users/z/work/zoo/zoo/e2e
npm run test:dapps -- zoo-vote-dao.spec.ts
Safe Multisig Setup
Prerequisites
Safe multisig testing requires:
- Safe master copy contract deployed
- Safe proxy factory deployed
- Multiple owner addresses
- Threshold configuration
Deployment
// Example Safe configuration
const safeConfig = {
owners: [address1, address2, address3],
threshold: 2, // 2 of 3 required
to: ethers.constants.AddressZero,
data: '0x',
fallbackHandler: ethers.constants.AddressZero,
paymentToken: ethers.constants.AddressZero,
payment: 0,
paymentReceiver: ethers.constants.AddressZero
};
Testing
# Run Safe integration tests
npm run test:contracts -- governance.spec.ts
CI/CD Integration
GitHub Actions Example
name: E2E Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 20
- name: Install dependencies
run: |
cd contracts && npm install --legacy-peer-deps
cd ../e2e && npm install
- name: Install Playwright
run: cd e2e && npx playwright install --with-deps
- name: Run tests
run: cd e2e && npm test
- name: Upload results
if: always()
uses: actions/upload-artifact@v3
with:
name: playwright-report
path: e2e/playwright-report/
Performance Targets
- Setup tests: <1s ✅
- Infrastructure tests: ~30s
- Contract tests: ~60s
- dApp tests: ~180s (per browser)
- Integration tests: ~120s
- Total suite: <390s (6.5 minutes)
Test Coverage
Current Status
✅ Setup (12 tests) - All passing
- Environment verification
- Dependency checks
- Directory structure validation
⚠️ Infrastructure (15 tests) - Pending Hardhat fix
- Blockchain lifecycle
- Transaction handling
- State management
✅ Contract Tests (30 tests) - Ready
- Token contracts (15 tests)
- Governance contracts (15 tests)
- Safe multisig integration
✅ dApp Tests (20 tests) - Ready
- Zoo Computer e-commerce (10 tests)
- Zoo Vote DAO (10 tests)
📝 Integration Tests - To be implemented
- Full user journeys
- Cross-contract interactions
- Multi-dApp workflows
Troubleshooting
Debug Mode
# Enable verbose logging
DEBUG=pw:api npm test
# Run specific test with debug
npm run test:debug -- tests/02-contracts/governance.spec.ts
View Test Report
npm run report
Opens HTML report with:
- Test results
- Screenshots (on failure)
- Videos (on failure)
- Trace files (on retry)
Check Background Processes
# View running background processes
ps aux | grep -E 'hardhat|node|npm'
# Kill all node processes
killall node
Contributing
When adding new tests:
- Follow existing test patterns
- Use fixtures for setup/teardown
- Add helpful console.log statements
- Update this SETUP.md if adding new requirements
- Run full test suite before committing
Resources
- Playwright Documentation
- Hardhat Documentation
- OpenZeppelin Governor
- Safe (Gnosis Safe)
- Zoo Documentation
Support
For issues or questions:
- Check this SETUP.md
- Review test output and error messages
- Check GitHub Issues
- Review Playwright traces for failed tests