📝 Introduction
Recently, I took on an interesting open-source issue — writing end-to-end (E2E) tests for the Google Maps integration in the sahat/hackathon-starter project.
What seemed like a simple task turned out to be full of unexpected technical challenges, and through solving them, I gained valuable experience in both testing strategy and open-source collaboration.
🎯 Project Background
Hackathon Starter is a popular Node.js boilerplate that integrates various third-party APIs and services.
Its Google Maps example demonstrates how to embed an interactive map in a webpage with features such as:
- Custom markers
- Font Awesome icons integration
- Info windows
- Map controls
- Boundary restrictions
The goal of Issue #1428 was to implement comprehensive E2E test coverage for this page.
🔍 Technical Exploration
Initial Analysis and Tool Selection
I began by analyzing the project’s existing test setup:
- Test Framework: Playwright (already configured)
-
Environment setup: Dual
.envconfiguration (.envvstest/.env.test) -
Target page:
/api/google-maps
Why Playwright?
- Powerful browser automation
- Rich element locator options
- Network request interception
- Cross-browser support
The First Major Discovery — window.map.getCenter() Problem
At first, I tried using window.map.getCenter() to verify the map’s center position.
However, it didn’t work as expected. After inspecting the source code, I found that the map object wasn’t accessible globally — meaning the test couldn’t directly call Google Maps API methods.
This discovery made me realize that many standard map testing approaches wouldn’t apply in this implementation.
🧪 Testing Strategy
Faced with limited API access, I designed a multi-layered testing strategy:
- DOM-level validation – verify key elements and containers
- Script validation – confirm Google Maps API is correctly loaded
- Map tile detection – ensure the map visually loads
- Custom marker testing – verify custom markers and info windows
🚫 The Challenge of Error Handling Tests
Simulating API Key Failure
At first, I almost overlooked the scenario where the app might fail to connect to the Google Maps API — because after setting up the environment, the connection always worked smoothly.
It wasn’t until one day, during a random network interruption, that I accidentally discovered the app had a built-in mechanism for handling API connection failures. That unexpected finding reminded me how easy it is to miss edge cases when everything “just works.”
To validate this behavior, I used Playwright’s request interception feature to simulate a failed API request:
await page.route('**/maps/api/js*', route => {
route.abort('failed');
});
Why Complete Error Verification Matters
Initially, I only checked either the error title or message.
Later, I realized that complete error validation should check both — ensuring the app gracefully handles and communicates failures to users.
This experience taught me that covering as many runtime scenarios as possible in testing — even rare or “unlikely” ones — often reveals hidden robustness (or fragility) in the application.
🎛️ The Center Map Button Dilemma
The “Center Map” button turned out to be the most challenging test item.
Although the implementation worked correctly in the UI, the test couldn’t verify its effect because the map variable wasn’t globally exposed.
Current Testing Limitations
✅ Button existence
✅ Button visibility
❌ Unable to verify recentering behavior
Proposed Solutions
- Modify source code to include
window.map = map(global reference) - Alternative check: monitor map tile or CSS transform changes
- Visual regression: compare before/after screenshots
📊 Final Test Results
After multiple iterations and optimizations, I implemented 7 comprehensive test cases:
| Test Category | Coverage | Status |
|---|---|---|
| Page Load & Element Display | DOM validation | ✅ |
| Google Maps JS API Load | Script validation | ✅ |
| Map Initialization & Custom Elements | Functional verification | ✅ |
| API Error Handling | Failure scenario simulation | ✅ |
| Map Controls & Interactions | UI interaction testing | ✅ |
| Font Awesome Icons & Marker Position | Visual check | ✅ |
| Marker Click & Info Window | Content verification | ✅ |
Coverage Highlights
- 🌐 Web fundamentals
- 🗺️ Map API integration
- 🚨 Error handling
- 🖱️ User interactions
- 🎨 Visual consistency
🎓 Key Learnings and Reflections
Technical Takeaways
- Mastered Playwright: Advanced usage of element locators, network interception, and JS evaluation.
- API Integration Testing: Learned alternative strategies when direct API access isn’t possible.
- Error Handling: Realized the importance of verifying complete error content.
Project Management Insights
- Task Decomposition: Broke down complex testing goals into smaller, achievable units.
- Iterative Improvement: Started with basic tests and gradually expanded coverage.
- Clear Communication: Documented limitations and proposed solutions clearly in GitHub issues.
Open Source Experience
- Understanding the Codebase: Deeply reading existing implementation is crucial.
- Respecting Original Design: Extend coverage without disrupting functionality.
- Constructive Contribution: Don’t just point out problems — propose practical solutions.
🔮 Future Outlook
This experience gave me a deeper understanding of E2E testing. In future projects, I plan to:
- Perform testability analysis before implementation
- Document testing strategy rationale and known limitations
- Continuously monitor and improve test coverage
📚 Conclusion
What started as a “simple Google Maps test” turned into a comprehensive testing journey covering API integration, error handling, and user interaction.
This process not only strengthened my technical skills but also deepened my appreciation for the open-source community.
Every technical limitation can be an opportunity for innovation.
Every debugging session can lead to meaningful learning.
If you’re interested in this topic, feel free to check out my contribution on GitHub:
Top comments (0)