-
- 
+
+ 
- chromaticWaster + BOTLANNER |
-
-
+
+
- BOTLANNER + chromaticWaster |
@@ -31,17 +31,17 @@ |
-
- 
+
+ 
- Makhubedu + capitec-oss |
-
-
+
+
- capitec-oss + Makhubedu |
+3. Add a `PROTECTED_TOKEN` secret for workflow runs with a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) as its value. (Optional)
+ - This is to enable re-triggering of workflows when a workflow commits screenshots. If this is not set a new code commit will be required to trigger the next workflow as it uses the default `GITHUB_TOKEN` instead.
+ - See [Automatic token authentication](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow) for detail.
+
+ 
+4. Clone the forked repo, checkout your branch, and run `npm ci` inside the repository root.
+5. Install the testing dependencies with `npx playwright install --with-deps`.
+6. Start up the dev server with `npm run serve` (or by launching debugging in VS Code).
### Directory Structure
When adding or editing components, please note the following key directories:
```
+
├── src
│ ├── button
│ │ ├── Button.stories.ts
+│ │ ├── Button.spec.ts
│ │ ├── Button.ts
│ │ ├── index.ts
│ │ ├── README.md
│ ├── ...
├── ...
+
```
* `src` - Contains all components in a flat structure, each named after a component, e.g. `button`. Contents:
* `Button.stories.ts` - The stories for the component.
+ * `Button.spec.ts` - The tests for the component.
* `Button.ts` - The component. *(NOTE: There might be multiple, depending on complexity and composition)*
* `index.ts` - The directory-level index, containing one or more component exports.
* `README.md` - The README for the component *(NOTE: Generated when Pull Request is merged)*.
@@ -94,6 +107,7 @@ When adding or editing components, please note the following key directories:
* **Do** use *lower case* [kebab-case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case) for component folder names, e.g. `some-component`. 🍢
* **Do** use uppercase first letter [CamelCase](https://en.wikipedia.org/wiki/Camel_case) for component file names, e.g. `SomeComponent.ts`.
* **Do** use the name of the component, suffixed with `.stories` for component story file names, e.g. `SomeComponent.stories.ts`.
+* **Do** use the name of the component, suffixed with `.spec` for component test file names, e.g. `SomeComponent.spec.ts`.
* **Do** match component name with its file name, e.g. `SomeComponent.ts` contains `export class SomeComponent { ... }`.
* **Do** prefix the custom element name with `omni-`.
* **Do not** use any verbs or prefixes within component property names, instead **do** use nouns, e.g. `mode`, `position`.
@@ -126,9 +140,23 @@ Here's a *non-exhaustive* list of requirements that are key to contributing to t
#### Stories
* **Do** use [Component Story Format (CSF) 3](https://github.com/capitec/omni-components/blob/develop/src/utils/ComponentStoryFormat.ts).
-* **Do** implement a [play function](https://github.com/capitec/omni-components/blob/develop/src/utils/PlayFunction.ts) per story to test story-specific component state and event behaviors.
* **Do** set the `data-testid` within every story template.
* **Do** ensure that stories are authored to be both dark and light theme friendly (test via the hosted documentation).
+* **Do** ensure that stories have their respective framework templates authored for each story where required.
+
+#### Tests
+* **Do** cater for behavioral testing for components that covers interaction and visual testing.
+ * **Test** the attributes of the component using assertions.
+ * **Test** visual behaviour by interactions. (Ensure mobile rendering differences are catered for)
+ * Take a screenshot of the initial state of the component.
+ * Perform interactions with the component.
+ * Take a screenshot of every change in state during the interactions.
+ * **Test** the events of the component using mock functions.
+* **Do** ensure that the test name is unique and descriptive of what will be tested.
+* **Do** ensure that the tests written result in at least 80% code coverage for the component.
+* **Do** ensure that the tests focus on user facing features of the component, not the internal workings of the component.
+* **Do** ensure that all tests pass.
+
#### Themes
* **Do** maintain each built-in theme, by ensuring all `--omni-theme-*` CSS custom properties are implemented.
@@ -136,6 +164,49 @@ Here's a *non-exhaustive* list of requirements that are key to contributing to t
> 💡 TIP: Refer to existing components, stories and themes for examples for any of the above.
+
+## Testing
+
+Tests are conducted via [Playwright](https://playwright.dev).
+
+### Running tests from shell
+
+- To run the end-to-end tests for all components on all configured browsers
+
+```sh
+npm run test
+```
+
+- To only run the end-to-end tests for all components on all configured browsers. (`npm run serve` must be run separately)
+
+```sh
+npm run test:only
+```
+
+- To run the end-to-end tests for all components only on Chromium. (`npm run serve` must be run separately)
+```sh
+npx playwright test --project=chromium
+```
+- To run the tests of a specific component on all configured browsers. (`npm run serve` must be run separately)
+```sh
+npx playwright test Component.spec.ts
+```
+
+### Running tests from Playwright Test Explorer within VSCode
+
+- Ensure that `npm run serve` is running separately.
+- Refer to the [Playwright Test Explorer](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) extension.
+
+### Viewing the test report
+
+- To view the latest test report.
+```sh
+npm run test-results
+```
+
+
+> 🔶 NOTE: Screenshot testing only asserts during CI workflows, the report will locally only show current screenshots taken, but not perform any comparisons.
+
## Pull Requests
### Requirements
* **Do** ensure the branch is up to date with the `develop` branch.
@@ -149,7 +220,5 @@ Here's a *non-exhaustive* list of requirements that are key to contributing to t
> 💡 TIP: Analyze changes locally with `npm run lint`.
* Format validation passes.
> 💡 TIP: Apply changes locally with `npm run format`.
-* All story play function tests pass.
-> 💡 TIP: Run tests locally with `npm run test`.
+* All tests pass.
-
diff --git a/README.md b/README.md
index 40f714c3a..a4c649e9f 100644
--- a/README.md
+++ b/README.md
@@ -633,17 +633,17 @@ See the [`CONTRIBUTING.md`](./CONTRIBUTING.md) guide to get involved.
|
-
-
+
+
- chromaticWaster + BOTLANNER |
-
-
+
+
- BOTLANNER + chromaticWaster |
@@ -661,17 +661,17 @@ See the [`CONTRIBUTING.md`](./CONTRIBUTING.md) guide to get involved. |
-
-
+
+
- Makhubedu + capitec-oss |
-
-
+
+
- capitec-oss + Makhubedu |