fixup! Add writing-tests-guidelines.md (#612)

Author: bedrich-schindler

mkdocs.yml

@@ -142,7 +142,9 @@ nav:
           - Translations: 'docs/customize/translations.md'
       - Contribute:
           - General Guidelines: 'docs/contribute/general-guidelines.md'
-          - Testing Guidelines: 'docs/contribute/testing-guidelines.md'
+          - Testing Guidelines:
+              - Testing: 'docs/contribute/testing-guidelines.md'
+              - Writing Tests: 'docs/contribute/writing-tests-guidelines.md'
           - API Guidelines: 'docs/contribute/api.md'
           - Composition: 'docs/contribute/composition.md'
           - CSS Guidelines: 'docs/contribute/css.md'

src/docs/contribute/writing-tests-guidelines.md

@@ -1,4 +1,4 @@
-# Playwright Testing Structure
+## Playwright Testing Structure
 
 This document outlines the structure and guidelines for writing Playwright
 tests, ensuring consistency and maintainability throughout the codebase.
@@ -7,8 +7,10 @@ tests, ensuring consistency and maintainability throughout the codebase.
 
 Playwright tests are organized into multiple files and folders, each
 serving a specific purpose.
+
 The complete component structure should be as follows:
 
+```text
 <ComponentName>/
 ├── __tests__/
 │   ├── <ComponentName>.spec.tsx-snapshots/
@@ -17,6 +19,7 @@ The complete component structure should be as follows:
 │   ├── <ComponentName>.spec.tsx
 │   ├── <ComponentName>.story.tsx
 ├── ...rest component files
+```
 
 - `<ComponentName>` - Root folder of the component, named after
 the component itself.
@@ -29,12 +32,13 @@ described below.
 in tests. These components should be functional without requiring any
 properties to be passed from the tests.
 
-## <ComponentName>.spec.tsx File Structure
+##  File Structure of `<ComponentName>.spec.tsx`
 
 Playwright tests follow a structured format to ensure readability
 and scalability. Each displayed level represents a `test.describe(...)` block.
 The structure consists of:
 
+```text
 <ComponentName>/
 ├── base/
 │   ├── visual/
@@ -45,6 +49,7 @@ The structure consists of:
 │   ├── visual/
 │   ├── non-visual/
 │   ├── functionality/
+```
 
 - `<ComponentName>` - Groups all tests for the tested component.
 - `base` - Contains component tests without any additional layout.
@@ -60,11 +65,11 @@ Test block categories can be expanded or removed depending on the nature
 of the tested component and whether a predefined test block is applicable
 in a specific case.
 
-## <ComponentName>.story.tsx File Structure
+##  File Structure of `<ComponentName>.story.tsx`
 
 The `<ComponentName>.story.tsx` file should include all component variants
 tested in `<ComponentName>.spec.tsx`. Components should be organized
-in the following order:  
+in the following order:
 
 1. Component for normal tests (`<ComponentName>ForTest`)
 2. Component for `ref` attribute tests (`<ComponentName>ForRefTest`)
@@ -75,14 +80,14 @@ in the following order:
 
 Each test case should follow the properties defined in the `PropTest` type.
 This type includes the properties `name`, `onBeforeTest`, `onBeforeSnapshot`,
-and `props`, which define the component setup for the actual test case.  
+and `props`, which define the component setup for the actual test case.
 
 - `name` - The name of the test case, following the naming conventions
-described in the next chapter.  
+described in the next chapter.
 - `onBeforeTest` - A function called before the test and component render.
   It should perform any environment tweaks necessary for the defined test.
 - `onBeforeSnapshot` - A function called after the component is rendered
-and before its comparison against the snapshot.  
+and before its comparison against the snapshot.
 - `props` - The properties passed to the component in the defined
 test scenario.
 
@@ -114,8 +119,8 @@ ordered alphabetically under the category of color.
 
   ```
 
-- When possible, try to re-use globally predefined `propTests`
-for visual tests,located in `tests/playwright/propTests`.
+- When possible, try to re-use globally defined `propTests`
+for visual tests, located in `tests/playwright/propTests`.
 
 - Naming convention for propTests `name` property should follow this pattern:
 
@@ -130,65 +135,150 @@ for visual tests,located in `tests/playwright/propTests`.
 - For all possible combinations of multiple `propTests` should be used
 function `mixPropTests`.
 
-## Test Structure Example
+## Templates
+
+### Template for `<ComponentName>.story.tsx`
+
+```tsx
+import React from 'react';
+import type { HTMLAttributes } from 'react';
+import { ComponentName } from '..';
+
+// Types for story component will be improved when we have full TypeScript support
+type ComponentForTestProps = HTMLAttributes<HTMLDivElement>;
+type ComponentForRefTestProps = ComponentForTestProps & {
+    testRefAttrName: string;
+    testRefAttrValue: string;
+};
+
+export const ComponentForTest = ({
+    ...props
+} : ComponentForTestProps) => (
+    <ComponentName
+        requiredPropA="value-a"
+        requiredPropB="value-b"
+        {...props}
+    />
+);
+
+// Story for `ref` prop, if applicable
+export const ComponentForRefTest = ({
+    testRefAttrName,
+    testRefAttrValue,
+    ...props
+} : ComponentForRefTestProps) => {
+    const ref = useRef<HTMLDivElement>(undefined);
+
+    useEffect(() => {
+        ref.current?.setAttribute(testRefAttrName, testRefAttrValue);
+    }, [testRefAttrName, testRefAttrValue]);
+
+    return (
+        <Component
+            {...props}
+            ref={ref}
+        />
+    );
+};
+
+```
+
+### Template for `<ComponentName>.spec.tsx`
+
+```tsx
+import React from 'react';
+import {
+    expect,
+    test,
+} from '@playwright/experimental-ct-react';
+import { propTests } from '../../../../tests/playwright';
+import { ComponentNameForTest } from './ComponentName.story';
 
-```jsx
 test.describe('ComponentName', () => {
-  test.describe('base', () => {
-    test.describe('visual', () => {
-      [
-        // propTests and mix of propTests
-      ].forEach(({
-        name,
-        onBeforeTest,
-        onBeforeSnapshot,
-        props,
-      }) => {
-        test(name, async ({
-          mount,
-          page,
-        }) => {
-          if (onBeforeTest) {
-            await onBeforeTest(page);
-          }
-
-          const component = await mount(
-            <ComponentName
-              {...props}
-            />,
-          );
-
-          if (onBeforeSnapshot) {
-            await onBeforeSnapshot(page, component);
-          }
-
-          const screenshot = await component.screenshot();
-          expect(screenshot).toMatchSnapshot();
+    test.describe('base', () => {
+        test.describe('visual', () => {
+            [
+                ...propTests.defaultComponentPropTest,
+                // ...propTests.propTestA,
+                // ...mixPropTests([
+                //    ...propTests.propTestX,
+                //    ...propTests.propTestY,
+                // ]),
+            ].forEach(({
+                name,
+                onBeforeTest,
+                onBeforeSnapshot,
+                props,
+            }) => {
+                test(name, async ({
+                    mount,
+                    page,
+                }) => {
+                    if (onBeforeTest) {
+                        await onBeforeTest(page);
+                    }
+
+                    const component = await mount(
+                        <ComponentNameForTest
+                            {...props}
+                        />,
+                    );
+
+                    if (onBeforeSnapshot) {
+                        await onBeforeSnapshot(page, component);
+                    }
+
+                    const screenshot = await component.screenshot();
+                    expect(screenshot).toMatchSnapshot();
+                });
+            });
         });
-      });
-    });
 
-    test.describe('non-visual', () => {
-      /* Non-visual tests. */
-    });
+        test.describe('non-visual', () => {
+            // Test for `id` prop, if applicable
+            test('id', async ({ mount }) => {
+                const component = await mount(
+                    <ComponentForTest
+                        id="test-id"
+                    />,
+                );
+
+                await expect(component).toHaveAttribute('id', 'test-id');
+                // Test the rest of internal IDs
+            });
+
+            // Test for `ref` prop, if applicable
+            test('ref', async ({ mount }) => {
+                const component = await mount(
+                    <ComponentForRefTest
+                        testRefAttrName="test-ref"
+                        testRefAttrValue="test-ref-value"
+                    />,
+                );
+
+                await expect(component).toHaveAttribute('test-ref', 'test-ref-value');
+            });
+
+            // Other non-visual tests
+        });
 
-    test.describe('functionality', () => {
-      /* Functional tests. */
+        test.describe('functionality', () => {
+            // Functional tests
+        });
     });
-  });
 
-  test.describe('formLayout', () => {
-    test.describe('visual', () => {
-      /* Visual tests as in `base` block. */
-    });
+    test.describe('formLayout', () => {
+        test.describe('visual', () => {
+            // Visual tests as in `base` block
+        });
 
-    test.describe('non-visual', () => {
-      /* Non-visual tests as in `base` block. */
-    });
+        test.describe('non-visual', () => {
+            // Non-visual tests as in `base` block
+        });
 
-    test.describe('functionality', () => {
-      /* Functional tests as in `base` block. */
+        test.describe('functionality', () => {
+            // Functional tests as in `base` block
+        });
     });
-  });
 });
 ```