Merge pull request #618 from thejackshelton/feat/select

test(select): initial select tests

Author: thejackshelton

.changeset/few-numbers-cross.md

@@ -0,0 +1,5 @@
+---
+'@qwik-ui/headless': patch
+---
+
+Added a new contributing guide in the docs! /docs/headless/contributing

apps/website/e2e/example.spec.ts

@@ -16,7 +16,7 @@ const baseURL = process.env['BASE_URL'] || 'http://localhost:5173';
  * See https://playwright.dev/docs/test-configuration.
  */
 export default defineConfig({
-  ...nxE2EPreset(__filename, { testDir: './e2e' }),
+  ...nxE2EPreset(__filename, { testDir: './src' }),
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {
     baseURL,
@@ -37,15 +37,15 @@ export default defineConfig({
       use: { ...devices['Desktop Chrome'] },
     },
 
-    {
-      name: 'firefox',
-      use: { ...devices['Desktop Firefox'] },
-    },
+    // {
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
 
-    {
-      name: 'webkit',
-      use: { ...devices['Desktop Safari'] },
-    },
+    // {
+    //   name: 'webkit',
+    //   use: { ...devices['Desktop Safari'] },
+    // },
 
     // Uncomment for mobile browsers support
     /* {

apps/website/playwright.config.ts

@@ -104,11 +104,99 @@ Tests ensure we can sleep sound at night and know that our component behavior is
 - get the test passing by adding said feature!
 - enjoy life when refactoring 🏝️
 
-We currently use [playwright](https://playwright.dev/docs/intro) for testing.
+We strongly recommend TDD development for the headless library, and we are currently in the process of a playwright integration.
 
-> We also currently have a few cypress tests that we are migrating over to playwright.
+Currently, the component testing integration for Qwik & Playwright is in development, and we are using e2e tests for the time being. That said, most tests should be very easy to migrate later on.
 
-Shai also has a testing course that Qwik UI contributors get access to for the price of **FREE**! Don't hesitate to reach out.
+#### Getting started w/ testing
+
+Here's an example way of getting a testid of the `Hero` select docs example in `index.mdx`, without affecting any visible markup.
+
+```tsx
+<div data-testid="select-hero-test">
+  <Showcase name="hero" />
+</div>
+```
+
+Then, we get our testDriver, you can think of it as reusable code we use throughout the test. For example, in the Select component we constantly grab the listbox, trigger, etc.
+
+```tsx
+import { Locator, Page } from '@playwright/test';
+
+export type DriverLocator = Locator | Page;
+
+export function selectTestDriver<T extends DriverLocator>(locator: T) {
+  const getRoot = () => {
+    return locator.getByRole('combobox');
+  };
+
+  return {
+    ...locator,
+    locator,
+    getRoot,
+    getListbox() {
+      return getRoot().getByRole('listbox');
+    },
+    getTrigger() {
+      return getRoot().getByRole('button');
+    },
+    // get all options
+    getOptions() {
+      return getRoot().getByRole('option').all();
+    },
+  };
+}
+```
+
+Now we can write some tests:
+
+```tsx
+import { test, expect } from '@playwright/test';
+import { selectTestDriver } from './select.driver';
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('/docs/headless/select');
+});
+
+test.describe('critical functionality', () => {
+  test(`GIVEN a basic select
+        WHEN clicking on the trigger
+        THEN open up the listbox
+        AND aria-expanded should be true`, async ({ page }) => {
+    const testDriver = selectTestDriver(page.getByTestId('select-hero-test'));
+
+    const { getListbox, getTrigger } = testDriver;
+
+    await getTrigger().click();
+
+    await expect(getListbox()).toBeVisible();
+    await expect(getTrigger()).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  test(`GIVEN a basic select
+        WHEN focusing the trigger and hitting enter
+        THEN open up the listbox
+        AND aria-expanded should be true`, async ({ page }) => {
+    const testDriver = selectTestDriver(page.getByTestId('select-hero-test'));
+
+    const { getListbox, getTrigger } = testDriver;
+
+    await getTrigger().focus();
+    await page.keyboard.press('Enter');
+
+    await expect(getListbox()).toBeVisible();
+    await expect(getTrigger()).toHaveAttribute('aria-expanded', 'true');
+  });
+});
+```
+
+To run the tests, use the `pnpm playwright` (only in my branch) command, or the `nx e2e website` longform. You can also do `--ui` to open the UI mode (which is pretty awesome!)
+
+> This example is in `spec.select.tsx` in the `src/components/select` folder of the website.
+
+Once we've added a failing test with what we expect, we can now go ahead and implement the feature for that!
+
+Heads up, I (Jack) am also relatively new to playwright myself 😅. I'm guessing there is a way to not need the testDriver to be consumed on each test. Feel free to experiment!
 
 ## Docs
 

apps/website/src/routes/docs/headless/contributing/index.mdx

@@ -1,33 +1,20 @@
-import { $, component$, useSignal, useTask$ } from '@builder.io/qwik';
+import { component$, useSignal } from '@builder.io/qwik';
 import { Select, SelectListbox, SelectOption, SelectTrigger } from '@qwik-ui/headless';
 
 export default component$(() => {
-  const mockUsers = ['Tim', 'Ryan', 'Jim'];
-  const moreUsers = ['Carla', 'Rachel', 'Monica', 'Jessie', 'Abby'];
-
-  const usersSig = useSignal<string[]>([]);
-
-  useTask$(async () => {
-    usersSig.value = mockUsers;
-  });
-
-  const handleClick$ = $(() => {
-    usersSig.value = [...usersSig.value, ...moreUsers];
-  });
+  const usersSig = useSignal<string[]>(['Tim', 'Ryan', 'Jim', 'Jessie', 'Abby']);
 
   return (
-    <div>
-      <Select>
-        <SelectTrigger>Trigger</SelectTrigger>
-        <SelectListbox style={{ padding: '0px', margin: '0px', listStyle: 'none' }}>
-          <SelectOption disabled>My option</SelectOption>
-          {usersSig.value.map((user) => (
-            <SelectOption key={user}>{user}</SelectOption>
-          ))}
-        </SelectListbox>
-      </Select>
-      {/* somehow this adds more js on page load? / wakes up the framework? */}
-      <button onClick$={handleClick$}>Add more!</button>
-    </div>
+    <Select class="relative min-w-40">
+      <SelectTrigger class="w-full border-2 border-dashed border-red-400" />
+      <SelectListbox class="absolute w-full border-2 border-dashed border-green-400 bg-slate-900 p-2">
+        <SelectOption class="border-2 border-dashed border-blue-400">
+          first option!
+        </SelectOption>
+        {usersSig.value.map((user) => (
+          <SelectOption key={user}>{user}</SelectOption>
+        ))}
+      </SelectListbox>
+    </Select>
   );
 });

apps/website/src/routes/docs/headless/select/examples/hero.tsx

@@ -10,7 +10,9 @@ import { statusByComponent } from '~/_state/component-statuses';
 
 This element is used to create a drop-down list, it's often used in a form, to collect user input.
 
-<Showcase name="hero" />
+<div data-testid="select-hero-test">
+  <Showcase name="hero" />
+</div>
 
 ## Building blocks
 

apps/website/src/routes/docs/headless/select/index.mdx

@@ -0,0 +1,25 @@
+import { Locator, Page } from '@playwright/test';
+
+export type DriverLocator = Locator | Page;
+
+export function selectTestDriver<T extends DriverLocator>(locator: T) {
+  const getRoot = () => {
+    return locator.getByRole('combobox');
+  };
+
+  return {
+    ...locator,
+    locator,
+    getRoot,
+    getListbox() {
+      return getRoot().getByRole('listbox');
+    },
+    getTrigger() {
+      return getRoot().getByRole('button');
+    },
+    // get all options
+    getOptions() {
+      return getRoot().getByRole('option').all();
+    },
+  };
+}

apps/website/src/routes/docs/headless/select/select.driver.ts

@@ -0,0 +1,37 @@
+import { test, expect } from '@playwright/test';
+import { selectTestDriver } from './select.driver';
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('/docs/headless/select');
+});
+
+test.describe('critical functionality', () => {
+  test(`GIVEN a basic select
+        WHEN clicking on the trigger
+        THEN open up the listbox
+        AND aria-expanded should be true`, async ({ page }) => {
+    const testDriver = selectTestDriver(page.getByTestId('select-hero-test'));
+
+    const { getListbox, getTrigger } = testDriver;
+
+    await getTrigger().click();
+
+    await expect(getListbox()).toBeVisible();
+    await expect(getTrigger()).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  test(`GIVEN a basic select
+        WHEN focusing the trigger and hitting enter
+        THEN open up the listbox
+        AND aria-expanded should be true`, async ({ page }) => {
+    const testDriver = selectTestDriver(page.getByTestId('select-hero-test'));
+
+    const { getListbox, getTrigger } = testDriver;
+
+    await getTrigger().focus();
+    await page.keyboard.press('Enter');
+
+    await expect(getListbox()).toBeVisible();
+    await expect(getTrigger()).toHaveAttribute('aria-expanded', 'true');
+  });
+});

apps/website/src/routes/docs/headless/select/select.spec.ts

@@ -26,5 +26,5 @@
       "path": "./tsconfig.spec.json"
     }
   ],
-  "include": ["src"]
+  "include": ["src", "src/routes/docs/headless/select/select.spec.ts"]
 }

apps/website/tsconfig.json

@@ -15,6 +15,7 @@
     "changeset": "changeset",
     "changeset.version": "changeset version && pnpm install --no-frozen-lockfile && git add --all",
     "dev": "nx serve website",
+    "playwright": "nx e2e website",
     "format.fix": "pretty-quick --staged",
     "link.dist": "cd dist/packages/kit-headless && pnpm link --global",
     "lint": "nx affected:lint",
@@ -61,7 +62,7 @@
     "@nx/vite": "17.1.3",
     "@nx/workspace": "17.1.3",
     "@oddbird/popover-polyfill": "0.3.7",
-    "@playwright/test": "^1.36.0",
+    "@playwright/test": "^1.41.2",
     "@storybook/addon-a11y": "7.6.0",
     "@storybook/addon-coverage": "^0.0.9",
     "@storybook/addon-essentials": "7.6.0",
@@ -104,7 +105,7 @@
     "eslint": "^8.48.0",
     "eslint-config-prettier": "9.0.0",
     "eslint-plugin-cypress": "^2.14.0",
-    "eslint-plugin-playwright": "^0.15.3",
+    "eslint-plugin-playwright": "^1.3.0",
     "eslint-plugin-qwik": "^1.4.0",
     "eslint-plugin-storybook": "^0.6.13",
     "focus-trap": "7.5.3",