Feedback in naming and documentation

Author: latin-panda

packages/web-forms/e2e/README.md

@@ -1,30 +1,30 @@
-# E2E Tests for `@getodk/web-forms`
+# 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.
 
-## Folder Structure
+## Folder structure
 
 The E2E tests are located in `packages/web-forms/e2e/`. Here's the structure and purpose of each directory:
 
 ```
 e2e/
 ├── fixtures/         # Sample forms and data for testing.
 ├── 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 components, etc.
-        ├── GeopointComponent.ts  # Example of a reusable control for the geopoint question type.
+    ├── 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.
         ├── FormPage.ts           # Example of a full page representation for a form.
 ├── specs/            # Test specification files.
         ├── geopoint.test.ts      # Example of a test file for the geopoint question type.
 ```
 
-### Key Components
+### Key concepts
 
 - **Fixtures**: Reusable test data (e.g., sample XForms) to simulate real-world use cases. Add new forms here as needed.
 - **Page Objects**: Implements the [Page Object Model (POM)](https://playwright.dev/docs/pom) pattern to encapsulate UI interactions, enhancing test readability and maintainability.
 - **Specs**: Test files organized by feature (e.g., rendering, submission). Name new tests descriptively to reflect their coverage.
 
-## Getting Started
+## Getting started
 
 1. **Build the project**
    In the root folder run:
@@ -46,13 +46,8 @@ e2e/
    yarn workspace @getodk/web-forms test:e2e <filepath, e.g. e2e/specs/geopoint.test.ts>
    ```
 
-3. **Add new tests**
-   - Create fixtures in `fixtures/` if needed.
-   - Update or add Page Objects in `page-objects/` for new UI elements.
-   - Write tests in `specs/` with descriptive names.
-
 ## Contributing
 
-- Keep tests focused: one feature per file.
+- Keep tests focused.
 - Use POM methods in `pages-objects/` for UI actions.
 - Add fixtures for new scenarios instead of hardcoding data.

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

@@ -1,6 +1,7 @@
 import { expect, Page } from '@playwright/test';
 
-const BASE_URL = 'http://localhost:5173';
+const DEV_BASE_URL = 'http://localhost:5173';
+const BUILD_BASE_URL = 'http://localhost:5174';
 
 export class PreviewPage {
 	private readonly page: Page;
@@ -9,15 +10,17 @@ export class PreviewPage {
 		this.page = page;
 	}
 
-	async goToPage() {
-		await this.page.goto(BASE_URL);
+	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.
 	 *
-	 * @TODO Add support for uploading XML forms from /e2e/fixtures directory for test-specific scenarios
-	 *
 	 * @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

packages/web-forms/e2e/specs/build/preview-form-render.test.ts

@@ -3,10 +3,10 @@ import { PreviewPage } from '../../page-objects/pages/PreviewPage.js';
 
 test('Build includes component-defined styles', async ({ page }) => {
 	const previewPage = new PreviewPage(page);
-	await previewPage.goToPage();
+	await previewPage.goToBuildPage();
 
 	// This ensures that the application is loaded before proceeding forward.
-	await expect(page.getByText('Demo Forms').first()).toBeVisible();
+	await expect(page.getByText('ODK Web Forms Preview').first()).toBeVisible();
 
 	// Get the (Sass-defined) large breakpoint size
 	// [In theory, if we can get this and it's not a number, we've already validated styles. Below expands on that to leave some breadcrumbs]

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();
+		}
+	});
+});

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

@@ -12,7 +12,7 @@ test.describe('Geopoint Question Type', () => {
 			formPage = new FormPage(page);
 
 			const previewPage = new PreviewPage(page);
-			await previewPage.goToPage();
+			await previewPage.goToDevPage();
 			await previewPage.openDemoForm('geopoint', 'geopoint.xml', 'Geopoint');
 		});
 
@@ -33,11 +33,11 @@ test.describe('Geopoint Question Type', () => {
 			await formPage.expectLabel('Where are you filling out the survey?');
 			await formPage.expectHint('(No autosave)');
 			await formPage.geopoint.openDialog();
-			await formPage.geopoint.expectGeopointDialog('Finding your location', '10m - Good accuracy');
+			await formPage.geopoint.expectGeopointDialog('Finding your location', '10 m - Good accuracy');
 			await formPage.geopoint.saveLocation();
 
 			await formPage.geopoint.expectGeopointFormattedValue(
-				['Accuracy: 10m', 'Latitude: 40.7128', 'Longitude: -74.006'],
+				['Accuracy: 10 m', 'Latitude: 40.7128', 'Longitude: -74.006'],
 				'Good accuracy'
 			);
 		});
@@ -52,11 +52,14 @@ test.describe('Geopoint Question Type', () => {
 
 			await formPage.expectLabel('Where are you filling out the survey?');
 			await formPage.geopoint.openDialog();
-			await formPage.geopoint.expectGeopointDialog('Finding your location', '500m - Poor accuracy');
+			await formPage.geopoint.expectGeopointDialog(
+				'Finding your location',
+				'500 m - Poor accuracy'
+			);
 			await formPage.geopoint.saveLocation();
 
 			await formPage.geopoint.expectGeopointFormattedValue(
-				['Accuracy: 500m', 'Latitude: 80.5128', 'Longitude: -99.9099'],
+				['Accuracy: 500 m', 'Latitude: 80.5128', 'Longitude: -99.9099'],
 				'Poor accuracy'
 			);
 		});
@@ -70,11 +73,14 @@ test.describe('Geopoint Question Type', () => {
 			});
 
 			await formPage.geopoint.openDialog();
-			await formPage.geopoint.expectGeopointDialog('Finding your location', '350m - Poor accuracy');
+			await formPage.geopoint.expectGeopointDialog(
+				'Finding your location',
+				'350 m - Poor accuracy'
+			);
 			await formPage.geopoint.saveLocation();
 
 			await formPage.geopoint.expectGeopointFormattedValue(
-				['Accuracy: 350m', 'Latitude: 79.5128', 'Longitude: -95.9099'],
+				['Accuracy: 350 m', 'Latitude: 79.5128', 'Longitude: -95.9099'],
 				'Poor accuracy'
 			);
 
@@ -86,11 +92,11 @@ test.describe('Geopoint Question Type', () => {
 			});
 
 			await formPage.geopoint.retryCapture();
-			await formPage.geopoint.expectGeopointDialog('Finding your location', '7m - Good accuracy');
+			await formPage.geopoint.expectGeopointDialog('Finding your location', '7 m - Good accuracy');
 			await formPage.geopoint.saveLocation();
 
 			await formPage.geopoint.expectGeopointFormattedValue(
-				['Accuracy: 7m', 'Latitude: 80.5128', 'Longitude: -99.9099'],
+				['Accuracy: 7 m', 'Latitude: 80.5128', 'Longitude: -99.9099'],
 				'Good accuracy'
 			);
 		});
@@ -107,7 +113,7 @@ test.describe('Geopoint Question Type', () => {
 			formPage = new FormPage(page);
 
 			const previewPage = new PreviewPage(page);
-			await previewPage.goToPage();
+			await previewPage.goToDevPage();
 			await previewPage.openDemoForm('geopoint', 'geopoint.xml', 'Geopoint');
 		});
 

packages/web-forms/e2e/specs/geopoint.test.ts

@@ -9,7 +9,7 @@ test.describe('Note Question Type', () => {
 		formPage = new FormPage(page);
 
 		const previewPage = new PreviewPage(page);
-		await previewPage.goToPage();
+		await previewPage.goToDevPage();
 		await previewPage.openDemoForm('notes', '2-all-possible-notes.xml', 'Notes');
 	});
 
@@ -48,7 +48,7 @@ test.describe('Note Question Type', () => {
 
 		await formPage.expectLabel('A note with geopoint type');
 		await formPage.geopoint.expectGeopointFormattedValue([
-			'Accuracy: 150m',
+			'Accuracy: 150 m',
 			'Latitude: 38.253094215699576',
 			'Longitude: 21.756382658677467',
 		]);