chore(#330): Adds e2e tests for default geopoint question type (#313)

- Adds minimal README file to guide contributors when adding new tests
- Adds a new folder structure
- Moves the content of wf-preview.test.ts to /e2e/test-cases/build/web-forms-preview-forms.test.ts. The original name wasn't descriptive.
- Adds new basic tests for geopoint and note question types
- Adds new page objects for fill form page, preview page and geopoint control

Author: latin-panda

.changeset/sad-pens-wear.md

@@ -0,0 +1,5 @@
+---
+'@getodk/web-forms': patch
+---
+
+Adds E2E tests for Geopoint and Notes question types

packages/web-forms/e2e/README.md

@@ -0,0 +1,54 @@
+# E2E tests for `@getodk/web-forms`
+
+This directory contains end-to-end (E2E) tests for the `@getodk/web-forms` package, which powers form filling and submission editing of ODK forms in a web browser. These tests use [Playwright](https://playwright.dev/) to simulate user interactions and ensure the package works as expected in real-world scenarios.
+
+Review the [best practices recommended by Playwright](https://playwright.dev/docs/best-practices#best-practices) before you start writing tests.
+
+## Folder structure
+
+The E2E tests are located in `packages/web-forms/e2e/`. Here's the structure and purpose of each directory:
+
+```
+e2e/
+├── page-objects/     # Page Object Model structure for e2e tests, organizing UI abstractions into pages and reusable controls.
+    ├── controls/     # Reusable controls such as form fields, UI elements, etc.
+        ├── GeopointControl.ts    # Example of a reusable control for the geopoint question type.
+    ├── pages/        # Full page representations.
+        ├── FillFormPage.ts       # Example of a full page representation for a form.
+├── test-cases/            # Test specification files.
+        ├── geopoint.test.ts      # Example of a test file for the geopoint question type.
+```
+
+## Key concepts
+
+- **Page Objects**: Implements the [Page Object Model](https://playwright.dev/docs/pom) pattern to encapsulate UI interactions, enhancing test readability and maintainability.
+- **Test Specification File**: Test files structured by feature (e.g., rendering, form submission), each holding a suite of tests targeting a specific application aspect. Use clear, descriptive names to highlight their purpose and ensure test coverage is easily identifiable.
+- **Fixtures**: Reusable test data (e.g., sample XForms) to simulate real-world use cases. Find fixtures in the [common package](../../common/src/fixtures)
+
+## Getting started
+
+1. **Build the project**
+   In the root folder run:
+
+   ```bash
+   yarn build
+   ```
+
+2. **Run tests**
+   Execute all E2E tests:
+
+   ```bash
+    yarn workspace @getodk/web-forms test:e2e
+   ```
+
+   Or run specific tests:
+
+   ```bash
+   yarn workspace @getodk/web-forms test:e2e <filepath, e.g. e2e/specs/geopoint.test.ts>
+   ```
+
+## Contributing
+
+- Keep tests focused.
+- Use page object methods in `pages-objects/` for UI actions.
+- Add [fixtures](../../common/src/fixtures) for new scenarios instead of hardcoding data.

packages/web-forms/e2e/build/wf-preview.test.ts

@@ -0,0 +1,68 @@
+import { expect, Page } from '@playwright/test';
+
+export class GeopointControl {
+	private readonly page: Page;
+
+	constructor(page: Page) {
+		this.page = page;
+	}
+
+	async expectGeopointDialog(expectedTitle: string, expectedQualityText: string) {
+		const dialogTitle = this.page
+			.locator('.geo-dialog-header-title')
+			.getByText(expectedTitle, { exact: true });
+		await expect(dialogTitle).toBeVisible();
+
+		const accuracyQuality = this.page
+			.locator('.geopoint-information .geo-quality')
+			.getByText(expectedQualityText, { exact: true });
+		await expect(accuracyQuality).toBeVisible();
+	}
+
+	async expectGeopointFormattedValue(expectedLocation: string[], expectedQuality?: string) {
+		for (const location of expectedLocation) {
+			const formattedValue = this.page
+				.locator('.geopoint-formatted-value')
+				.getByText(location, { exact: true });
+			await expect(formattedValue).toBeVisible();
+		}
+
+		if (expectedQuality) {
+			const quality = this.page
+				.locator('.geopoint-value .geo-quality')
+				.getByText(expectedQuality, { exact: true });
+			await expect(quality).toBeVisible();
+		}
+	}
+
+	async expectGeopointErrorMessage(expectedMessage: string[]) {
+		const message = this.page
+			.locator('.geopoint-error')
+			.getByText(expectedMessage, { exact: true });
+		await expect(message).toBeVisible();
+	}
+
+	async openDialog(index = 0) {
+		const buttons = this.page
+			.locator('.geopoint-control')
+			.getByText('Get location', { exact: true });
+		const button = buttons.nth(index);
+		await button.scrollIntoViewIfNeeded();
+		await expect(button).toBeVisible();
+		await button.click();
+	}
+
+	async saveLocation() {
+		const button = this.page
+			.locator('.geo-dialog-footer')
+			.getByText('Save location', { exact: true });
+		await expect(button).toBeVisible();
+		await button.click();
+	}
+
+	async retryCapture() {
+		const button = this.page.locator('.geopoint-value').getByText('Try again', { exact: true });
+		await expect(button).toBeVisible();
+		await button.click();
+	}
+}

packages/web-forms/e2e/page-objects/controls/GeopointControl.ts

@@ -0,0 +1,65 @@
+import { expect, Page } from '@playwright/test';
+import { GeopointControl } from '../controls/GeopointControl.js';
+
+export class FillFormPage {
+	private readonly page: Page;
+
+	public readonly geopoint: GeopointControl;
+
+	constructor(page: Page) {
+		this.page = page;
+		this.geopoint = new GeopointControl(page);
+	}
+
+	private async expectTextAtIndex(
+		locator: string,
+		expectedText: string,
+		index: number,
+		expectVisible = true
+	) {
+		const texts = this.page.locator(locator);
+		const text = texts.nth(index).getByText(expectedText, { exact: true });
+
+		if (expectVisible) {
+			await text.scrollIntoViewIfNeeded();
+			return expect(text).toBeVisible();
+		}
+
+		return expect(text).not.toBeVisible();
+	}
+
+	private async expectText(locator: string, expectedText: string) {
+		const text = this.page.locator(locator).getByText(expectedText, { exact: true });
+		await text.scrollIntoViewIfNeeded();
+		await expect(text).toBeVisible();
+	}
+
+	async expectNoteAtIndex(expectedNoteText: string, index: number, expectVisible?: boolean) {
+		await this.expectTextAtIndex(
+			'.note-control .note-value',
+			expectedNoteText,
+			index,
+			expectVisible
+		);
+	}
+
+	async expectNote(expectedNoteText: string) {
+		await this.expectText('.note-control .note-value', expectedNoteText);
+	}
+
+	async expectLabelAtIndex(expectedLabelText: string, index: number, expectVisible?: boolean) {
+		await this.expectTextAtIndex('.control-text label', expectedLabelText, index, expectVisible);
+	}
+
+	async expectLabel(expectedLabelText: string) {
+		await this.expectText('.control-text label', expectedLabelText);
+	}
+
+	async expectHintAtIndex(expectedHintText: string, index: number, expectVisible?: boolean) {
+		await this.expectTextAtIndex('.control-text .hint', expectedHintText, index, expectVisible);
+	}
+
+	async expectHint(expectedHintText: string) {
+		await this.expectText('.control-text .hint', expectedHintText);
+	}
+}

packages/web-forms/e2e/page-objects/pages/FillFormPage.ts

@@ -0,0 +1,50 @@
+import { expect, Page } from '@playwright/test';
+
+const DEV_BASE_URL = 'http://localhost:5173';
+const BUILD_BASE_URL = 'http://localhost:5174';
+
+export class PreviewPage {
+	private readonly page: Page;
+
+	constructor(page: Page) {
+		this.page = page;
+	}
+
+	async goToDevPage() {
+		await this.page.goto(DEV_BASE_URL);
+	}
+
+	async goToBuildPage() {
+		await this.page.goto(BUILD_BASE_URL);
+	}
+
+	/**
+	 * Opens a preexisting demo form by navigating through the demo forms UI.
+	 *
+	 * @param {string} accordionName - The name of the demo forms category accordion
+	 * @param {string} formLinkName - The exact name of the demo form link to open
+	 * @param {string} formTitle - The expected title of the form, used to verify successful loading
+	 * @returns {Promise<void>} Resolves when the form is successfully loaded and verified
+	 */
+	async openDemoForm(accordionName: string, formLinkName: string, formTitle: string) {
+		const demoSection = this.page
+			.locator('.dev-form-list-component')
+			.getByText('Demo Forms for DEV');
+		await demoSection.scrollIntoViewIfNeeded();
+		await expect(demoSection).toBeVisible();
+
+		const accordion = this.page.locator('.category-list').getByText(accordionName, { exact: true });
+		await accordion.scrollIntoViewIfNeeded();
+		await expect(accordion).toBeVisible();
+		await accordion.click();
+
+		const link = this.page.locator('.form-list').getByText(formLinkName, { exact: true });
+		await link.scrollIntoViewIfNeeded();
+		await expect(link).toBeVisible();
+		await link.click();
+
+		// Wait for form to load and verify the form title ensuring the form is ready.
+		const title = this.page.locator('.form-title').getByRole('heading', { name: formTitle });
+		await expect(title).toBeVisible();
+	}
+}

packages/web-forms/e2e/page-objects/pages/PreviewPage.ts

@@ -1,7 +1,9 @@
 import { expect, test } from '@playwright/test';
+import { PreviewPage } from '../../page-objects/pages/PreviewPage.js';
 
 test('Build includes component-defined styles', async ({ page }) => {
-	await page.goto('http://localhost:5174/');
+	const previewPage = new PreviewPage(page);
+	await previewPage.goToBuildPage();
 
 	// This ensures that the application is loaded before proceeding forward.
 	await expect(page.getByText('ODK Web Forms Preview').first()).toBeVisible();

packages/web-forms/e2e/build/style.test.ts renamed to packages/web-forms/e2e/specs/build/style.test.ts

@@ -0,0 +1,30 @@
+import { expect, test } from '@playwright/test';
+import { PreviewPage } from '../../page-objects/pages/PreviewPage.js';
+
+test.describe('Web Forms Preview Demo Forms', () => {
+	test('demo forms load', async ({ context, page }) => {
+		const previewPage = new PreviewPage(page);
+		await previewPage.goToBuildPage();
+
+		const formPreviewLinks = await page.locator('.form-preview-link').all();
+
+		expect(formPreviewLinks.length).toBeGreaterThan(0);
+
+		for (const link of formPreviewLinks) {
+			const [formPreviewPage] = await Promise.all([context.waitForEvent('page'), link.click()]);
+
+			await formPreviewPage.waitForSelector(
+				'.form-initialization-status.error, .form-initialization-status.ready',
+				{
+					state: 'attached',
+				}
+			);
+
+			const [failureDialog] = await formPreviewPage.locator('.form-load-failure-dialog').all();
+
+			expect(failureDialog).toBeUndefined();
+
+			await formPreviewPage.close();
+		}
+	});
+});