03/04: migrate from google maps to nominatim api

Author: kettanaito

exercises/03.guides/03.problem.recording-tests/app/components/user-dropdown.tsx

@@ -28,6 +28,7 @@ export function UserDropdown() {
 					>
 						<Img
 							className="size-8 rounded-full object-cover"
+							role="presentation"
 							alt={user.name ?? user.username}
 							src={getUserImgSrc(user.image?.objectKey)}
 							width={256}

exercises/03.guides/03.solution.recording-tests/README.mdx

@@ -2,4 +2,31 @@
 
 ## Summary
 
-1.
+1. Install the Playwright extension in VS Code. Show where and how.
+2. Showcase the extension in the sidebar once it's installed. See how it merges with the same extension from Vitest. Neat!
+
+---
+
+1. Before recording the tests, check the "Show browser" option in the "Settings" of the extension.
+2. Run the test. You can see that PW spawned in a headful mode, but the browser window doesn't close once the test is done. I will use that to record!
+3. Right-click on the test case in the list of tests and "Go to Test". The test case opens. Put the cursor at the blank space before the test's end.
+4. Finally, in the extension sidebar, click "Record at cursor".
+
+---
+
+1. In the browser window, notice how an UI overlay appeared. It has the controls to help with recording my interactions with the app.
+2. I scroll to the "Name" field on the page and change the user's name to "John Doe".
+3. I click "Save changes" the same way the user would.
+4. Now, let's verify that the change has been applied. I click on the user profile at the top right corner, then go to the "Profile" page.
+5. I can see the updated user name, but now I need to help Playwright see it also. In the overlay panel, I choose "Assert visibility" and click on the heading element with the updated user name.
+
+---
+
+1. Let's take a look at the recorded test. See how all my actions have been recorded, and the visibility assertion has been translated to the `expect` call.
+2. I'm done with the recording, so all I have to do is close the browser window.
+3. Now, let's run this test. Here's the result.
+
+---
+
+1. The role of the recording. It's a tool to make the process faster not to _replace_ the process. Playwright won't always output the best locators, and sometimes your app will be to blame. If you lack proper accessibility attributes, Playwright will have no choice but to resort to locating the elements by their DOM order, for example, which is less than ideal.
+2. Use the recording as a draft of the test. Polish it (or the app), introduce additional behaviors, like assertion messages or retryable assertions, and have yourself a great test done much faster.

exercises/03.guides/04.solution.api-mocking/README.mdx

@@ -1,8 +1,16 @@
 # API mocking
 
-Good job! 👏
+1. Install `msw` and `@msw/playwright` dependencies.
+2. Head to `tests/text-extend.ts` and in the `Fixtures` interface, describe a new fixture called `network`. Use the type from the `@msw/playwright` package to annotate it.
+3. Implement the `network` fixture. Use `defineNetworkFixture()` from the package, provide it with the handlers and the browser `context`. Start, use, and stop, awaited. Then, set `{ auto: true }` because I want for API mocking to always be applied, even if this fixture isn't explicitly used in a test.
+4. To make this fixture more flexible, I will create an option fixture called `handlers`. Annotate it as `Array<AnyHandler>`, then implement it as `[[], { option: true }]`. This way, individual tests and even entire test projects can define their own list of request handlers to affect the network.
 
-Please wait for the others to finish so we could go through the solution to this exercise together.
+---
+
+1. Now, let's use `network` in the test. Reference it and use `network.use()` to apply request handlers for the Google API requests I want to intercept.
+2. Respond with a mocked response (use the `HttpResponse` helper from `msw`).
+
+---
 
 ## Related materials
 

exercises/03.guides/04.solution.api-mocking/app/components/forms.tsx

@@ -213,7 +213,7 @@ export function ComboboxField({
 	labelProps: React.LabelHTMLAttributes<HTMLLabelElement>
 	inputProps: React.TextareaHTMLAttributes<HTMLInputElement> & { key: any }
 	errors?: ListOfErrors
-	options: Array<{ label: string; value: string }>
+	options: Array<{ id: string | number; label: string; value: string }>
 	className?: string
 }) {
 	const fallbackId = useId()
@@ -230,7 +230,7 @@ export function ComboboxField({
 	const [query, setQuery] = useState<string>('')
 
 	const [filtered, setFiltered] = useState<
-		Array<{ label: string; value: string }>
+		Array<{ id: string | number; label: string; value: string }>
 	>([])
 
 	const filterOptions = useCallback(
@@ -285,7 +285,7 @@ export function ComboboxField({
 						<CommandList>
 							{filtered.map((option) => (
 								<CommandItem
-									key={option.value}
+									key={option.id}
 									value={option.value}
 									onSelect={() => {
 										control.change(option.value)

exercises/03.guides/04.solution.api-mocking/app/routes/users+/$username_+/__note-editor.tsx

@@ -57,12 +57,11 @@ export const NoteEditorSchema = z.object({
 	location: z.string().optional(),
 })
 
-export type GoogleFindPlaceApiResponse = {
-	candidates: Array<{
-		place_id: string
-		formatted_address: string
-	}>
-}
+export type NominatimSearchResponse = Array<{
+	addresstype: 'country' | 'city'
+	place_id: number
+	display_name: string
+}>
 
 export function NoteEditor({
 	note,
@@ -89,22 +88,23 @@ export function NoteEditor({
 	const imageList = fields.images.getFieldList()
 
 	const { data: locationSuggestions } = useQuery<
-		GoogleFindPlaceApiResponse | undefined
+		NominatimSearchResponse | undefined
 	>({
-		queryKey: ['location-suggestions'],
+		queryKey: ['location-suggestions', fields.location.value],
 		queryFn: async ({ signal }) => {
 			await new Promise((resolve) => setTimeout(resolve, 300))
 
 			if (!signal.aborted && fields.location.value) {
-				const url = new URL(
-					'https://maps.googleapis.com/maps/api/place/findplacefromtext/json',
-				)
-				url.searchParams.set('key', 'FOO')
-				url.searchParams.set('input', fields.location.value)
-				url.searchParams.set('inputtype', 'textquery')
-				url.searchParams.set('fields', 'place_id,formatted_address')
+				const url = new URL('https://nominatim.openstreetmap.org/search')
+				url.searchParams.set('q', fields.location.value)
+				url.searchParams.set('format', 'jsonv2')
 				const response = await fetch(url)
-				return response.json() as Promise<GoogleFindPlaceApiResponse>
+				const locations = (await response.json()) as NominatimSearchResponse
+				return locations.filter(
+					(location) =>
+						location['addresstype'] === 'city' ||
+						location['addresstype'] === 'country',
+				)
 			}
 		},
 		enabled: !!fields.location.value,
@@ -144,9 +144,10 @@ export function NoteEditor({
 						/>
 						<ComboboxField
 							options={
-								locationSuggestions?.candidates.map((candidate) => ({
-									label: candidate.formatted_address,
-									value: candidate.formatted_address,
+								locationSuggestions?.map((location) => ({
+									id: location.place_id,
+									label: location.display_name,
+									value: location.display_name,
 								})) || []
 							}
 							labelProps={{ children: 'Location' }}

exercises/03.guides/04.solution.api-mocking/package.json

@@ -120,7 +120,7 @@
   "devDependencies": {
     "@epic-web/config": "^1.20.1",
     "@faker-js/faker": "^9.7.0",
-    "@msw/playwright": "^0.4.2",
+    "@msw/playwright": "^0.6.4",
     "@playwright/test": "^1.57.0",
     "@react-router/dev": "^7.5.3",
     "@sly-cli/sly": "^2.1.1",
@@ -149,7 +149,7 @@
     "eslint": "^9.26.0",
     "fs-extra": "^11.3.0",
     "jsdom": "^25.0.1",
-    "msw": "^2.7.6",
+    "msw": "^2.12.10",
     "npm-run-all": "^4.1.5",
     "playwright-persona": "^0.2.8",
     "prettier": "^3.5.3",

exercises/03.guides/04.solution.api-mocking/tests/e2e/notes-create.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw'
-import { type GoogleFindPlaceApiResponse } from '#app/routes/users+/$username_+/__note-editor.tsx'
+import { type NominatimSearchResponse } from '#app/routes/users+/$username_+/__note-editor.tsx'
 import { test, expect } from '#tests/test-extend.ts'
 
 test('displays location suggestions when creating a new note', async ({
@@ -9,21 +9,21 @@ test('displays location suggestions when creating a new note', async ({
 	page,
 }) => {
 	network.use(
-		http.get<never, never, GoogleFindPlaceApiResponse>(
-			'https://maps.googleapis.com/maps/api/place/findplacefromtext/json',
+		http.get<never, never, NominatimSearchResponse>(
+			'https://nominatim.openstreetmap.org/search',
 			() => {
-				return HttpResponse.json({
-					candidates: [
-						{
-							place_id: 'f02cda9e-d6d0-437b-9f82-1c5652e12af2',
-							formatted_address: 'San Francisco',
-						},
-						{
-							place_id: '77886276-dc77-4399-a39e-037378ac4c34',
-							formatted_address: 'San Jose',
-						},
-					],
-				})
+				return HttpResponse.json([
+					{
+						place_id: 1,
+						addresstype: 'city',
+						display_name: 'San Francisco',
+					},
+					{
+						place_id: 2,
+						addresstype: 'city',
+						display_name: 'San Jose',
+					},
+				])
 			},
 		),
 	)

exercises/03.guides/04.solution.api-mocking/tests/test-extend.ts

@@ -1,5 +1,6 @@
-import { createNetworkFixture, type NetworkFixture } from '@msw/playwright'
+import { defineNetworkFixture, type NetworkFixture } from '@msw/playwright'
 import { test as testBase, expect } from '@playwright/test'
+import { type AnyHandler } from 'msw'
 import {
 	definePersona,
 	combinePersonas,
@@ -15,6 +16,7 @@ interface Fixtures {
 		...args: Parameters<typeof href<T>>
 	) => Promise<void>
 	authenticate: AuthenticateFunction<[typeof user]>
+	handlers: Array<AnyHandler>
 	network: NetworkFixture
 }
 
@@ -54,7 +56,19 @@ export const test = testBase.extend<Fixtures>({
 		})
 	},
 	authenticate: combinePersonas(user),
-	network: createNetworkFixture(),
+	handlers: [[], { option: true }],
+	network: [
+		async ({ context, handlers }, use) => {
+			const network = defineNetworkFixture({
+				context,
+				handlers,
+			})
+			await network.enable()
+			await use(network)
+			await network.disable()
+		},
+		{ auto: true },
+	],
 })
 
 export { expect }