Many features need data from third-party services. In this lesson you integrate geocoding, maps and a title-autocomplete API from JavaScript, and learn to test code that talks to external services.
Important
Work on this lesson in
buildermode.
Learning goals
- You can explain what is involved when a browser talks to a third-party service: API keys, CORS, rate limits, and why some calls belong on your server instead.
- You can integrate a third-party JavaScript library (e.g. a map) and call a JSON API from the browser to enrich your UI.
- You can design your JavaScript so a test can query its state through a small API, and drive it from a feature spec.
- You can build a find-as-you-type suggestion that stays correct when responses arrive out of order, and lets the user override the suggestion.
- You can test code that talks to an external service in two ways — against the real service, or against a fake with the same interface — and explain the trade-offs.
- You can keep end-to-end tests stable by putting external integrations behind feature flags.
Resources
Read what's new to you, skim what's familiar, skip what you already master. Stop when you can meet the learning goals.
Your agent can also generate an overview, a tutorial or an explanation for anything here, tailored to what you already know. Just ask.
Maps and geocoding
- 📄 Leaflet quick start Show archive.org snapshot — a map with a marker in a few lines; load Leaflet from their CDN Show archive.org snapshot for this exercise
- 📄 Getting started with Leaflet and OpenStreetMap tiles Show archive.org snapshot — free tiles for educational use
- 📄 Nominatim search API Show archive.org snapshot — free geocoding of an address to coordinates
Movie data
- 📄 TMDB API: getting started Show archive.org snapshot and the search/movie endpoint Show archive.org snapshot — free for non-commercial use with an API key and attribution; CORS is open, so the browser can call it directly
Talking to APIs from the browser and testing it
- 📄 Concurrency issues with find-as-you-type boxes — our card on out-of-order responses
- 📄
Capybara:
evaluate_scriptShow archive.org snapshot — querying your JavaScript's state from a feature spec - 📄 Using feature flags to stabilize flaky E2E tests — our card
Exercises
Maps
- In MovieDB, add a new field “Principal filming location”.
- In a movie’s show view, geocode that location and show a Google map centered around it
- Now write an E2E feature that tests that the map shows the correct location.
Hints
- The purpose of this lesson to learn interacting with external APIs from JavaScript. Even though this exercise can be implemented trivially by embedding a
Google Maps iframe
Show archive.org snapshot
, don't do that for the purpose of learning. Instead you should work with JavaScript-consumable APIs, either by calling functions of a client library or by making your own HTTP requests using
fetch(). - To implement this exercise you will need two external services: One to transform an address string to geographical coordinates ("geocoding") and one to display a map centered around given coordinates.
- Google Maps offers both geocoding and map display APIs. If you want to use Google Maps, you need to sign up for an API key.
- A free alternative for educational use is using Leaflet.js Show archive.org snapshot with an OpenStreetMap Tile Provider Show archive.org snapshot . You can geocode an address with the Nominatim API Show archive.org snapshot (it supports CORS requests).
- Your JavaScript that creates and centers the map should expose an API that lets you query the current map position from your test.
- Your test can use
evaluate_script(...)Show archive.org snapshot to talk with that JavaScript.
Note
Adding leaflet to your build pipeline is quite tricky, as the JS script needs to know the fingerprinted image URLs e.g. of the marker icon on the map. For the sake of this specific exercise, we recommend integrating Leaflet using their CDN solution Show archive.org snapshot instead.
Title autocomplete
- In MovieDB's movie form, suggest matching movie titles as the user types into the title field, using
The Movie Database (TMDB) API
Show archive.org snapshot
(free for non-commercial use; register for an API key and attribute TMDB in your footer).
- Use the movie search endpoint Show archive.org snapshot ; it supports CORS, so you can call it directly from the browser.
- When the user picks a suggestion, prefill the release year from the result.
- The user can ignore the suggestions and type freely.
- Also read this card for an issue you might encounter.
Testing
Write an E2E feature that tests the functionality above. Implement the test using two different techniques:
- Actually talk to the TMDB API during tests.
- Only in tests, replace the JavaScript function that talks to the TMDB API with a fake implementation that maps a fixed list of queries to their suggestions.
- It should have the same API as your original TMDB client.
- The fixed list can be part of your fake implementation. If it helps your test, your fake implementation might also expose an additional API to change the list.
Talk with your mentor about the pros and cons of each approach.
Tip
Use feature flags to disable the title autosuggestion and map rendering in tests. Enable each feature only for tests that actually care about the corresponding functionality.
