You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository contains the rendering logic for articles on theguardian.com. It is a monorepo with 2 projects, `apps-rendering` and `dotcom-rendering`.
3
+
This repository contains the rendering logic for theguardian.com and for a subset of articles in the live apps.
4
4
5
-
## Developer setup
6
-
7
-
Install [Node.js](https://nodejs.org).
8
-
9
-
We recommend using [fnm](https://github.com/Schniz/fnm). It is great at managing multiple versions of Node.js on one machine.
10
-
11
-
> You may find it useful to add `--version-file-strategy recursive` to the [`fnm` shell setup](https://github.com/Schniz/fnm?tab=readme-ov-file#shell-setup). This will set the active Node version to first version it finds in the current directory _or_ any parent directory.
12
-
13
-
Once Node is installed, make sure you're using the correct package manager by [enabling corepack](https://github.com/nodejs/corepack?tab=readme-ov-file#utility-commands):
14
-
15
-
```sh
16
-
corepack enable
17
-
```
18
-
19
-
> [!NOTE]
20
-
>
21
-
> If you're using `asdf`, you'll need to run `asdf reshim nodejs` after running `corepack enable`.
22
-
23
-
## Install
24
-
25
-
Run `pnpm install` in the root directory of this project to install packages.
5
+
It is a monorepo with 2 projects, `apps-rendering` and `dotcom-rendering`.
26
6
27
7
## Run
28
8
29
-
You should always `cd` into the correct subdirectory before running commands (e.g `make dev` for dotcom-rendering, or `pnpm watch` for apps-rendering) except for storybook.
30
-
31
9
### `apps rendering`
32
10
33
11
Go to [apps rendering](apps-rendering/README.md) for more details.
@@ -38,15 +16,9 @@ Go to [dotcom rendering](dotcom-rendering/README.md) for more details.
38
16
39
17
## Root actions
40
18
41
-
Most commands are run from within each project but the following are managed from the monorepo root:
19
+
Most commands are run from within each project but the following can be run from the root:
42
20
43
-
### Storybook/Chromatic
21
+
### Storybook
44
22
45
23
`pnpm storybook` - Runs Storybook for all projects
46
24
`pnpm build-storybook` - Builds Storybook for all projects
47
-
48
-
Chromatic now runs at project level. `cd` into the project dir and run `pnpm chromatic -t [CHROMATIC PROJECT TOKEN]`
49
-
50
-
You can find the token in the project Chromatic instance.
51
-
52
-
To run Chromatic in CI on your pr, add the `run_chromatic` label once you're ready to check for visual regressions.
The dotcom-rendering github account is set up to merge PRs into main instead of rebase. Merge commits are useful to quickly revert things when there is a major incident - whereas with rebase you might have to revert a whole load of commits.
Tests are run using [Jest](https://jestjs.io). You can run the full unit test suite locally by running:
5
+
Unit tests are run using [Jest](https://jestjs.io).
6
+
7
+
You can run the full unit test suite locally by running:
6
8
7
9
```bash
8
10
make test
@@ -26,50 +28,55 @@ Alternatively, you can use `watch` mode to have jest run the suite as files are
26
28
pnpm test --watch
27
29
```
28
30
29
-
##Writing tests
31
+
### Location
30
32
31
-
Tests should be colocated with the module/Component under test and should end with the suffix `.test.ts` or `.test.tsx`.
33
+
Unit tests should be colocated with the module under test and should end with the suffix `.test.ts` or `.test.tsx`.
32
34
33
35
For example:
34
-
`components/ShareCount.tsx`
35
-
`components/ShareCount.test.tsx`
36
36
`lib/cookie.ts`
37
37
`lib/cookie.test.ts`
38
38
39
-
## React Testing Library tests
39
+
## Component tests
40
40
41
-
To test components we use [react-testing-library](https://github.com/kentcdodds/react-testing-library). This a testing utility that allows you to tests against the rendered DOM, output from your component. The utility makes you write tests from a “user-perspective”, asserting against user-facing properties.
41
+
To test components we use [react-testing-library](https://github.com/testing-library/react-testing-library). It allows you to tests agains the rendered DOM output of your component. The library makes you write tests from a "user-perspective", asserting against user-facing properties.
42
42
43
-
### Do test
43
+
### Location
44
44
45
-
When we write tests for Components, we should test the render logic and not the internal implementation details.
45
+
Component tests should be colocated with the component under test and should end with the suffix `.test.tsx`.
46
46
47
-
Test the expected behavior of a component: what it renders, how the props it receives alter what's rendered and how user interactions and events that trigger changes of state alter what's rendred.
47
+
For example:
48
+
`components/ShareCount.tsx`
49
+
`components/ShareCount.test.tsx`
48
50
49
-
Look for conditional statements (ternaries, if statements, and switch statements) in the render method for clues about what to test. You should always test your public interface (the props your component takes). For example, if the Component under test takes a prop which is a function that is executed onClick we can test it’s executed by simulating a click on the Component under test.
51
+
## Visual tests
50
52
51
-
### Don't test
53
+
We use [Storybook](https://storybook.js.org/) and [Chromatic](https://www.chromatic.com/) to create visual regression tests.
52
54
53
-
Tests that require you to duplicate the application code exactly. These tests will be brittle. For example if a component renders with a height 10px, if you test that the component has a height 10px and you then update the Component so it’s height is 11px then you’ll have to update your test, even though the component’s behavior has not changed. Don’t test inline styles, unless the value can change based on props/state.
55
+
To run Storybook locally:
54
56
55
-
Don't assert against behaviours covered by the library code. EG. Testing types of properties passed to the component, this is unnecessary.
57
+
`pnpm storybook`
56
58
57
-
### Snapshots
59
+
To run Chromatic locally:
58
60
59
-
Jest [Snapshot](https://jestjs.io/docs/en/snapshot-testing) tests make sure the rendered output of a UI Component does not change unexpectedly.
61
+
`pnpm chromatic -t [CHROMATIC PROJECT TOKEN]`
60
62
61
-
We will **not** be writing snaphot test Components for the following reasons:
63
+
You can find the token in the project Chromatic instance.
62
64
63
-
- Snapshots immortalize a Component’s current markup as the true markup, regardless of whether or not the component is correct.
64
-
- Too easy to fix tests without fixing underlying bugs simplu by running `jest --u` override command.
65
-
- Increased risk of false negatives and false positives - If the tests fail when there are no bugs, that is a false negative. If the tests pass when there are bugs present, that is a false positive.
66
-
- Developer time required to check snapshot test failures when simple non-breaking changes introduced, plus developer time required to review snapshot output in Pull Requests.
65
+
To run Chromatic in CI on your pr, add the `run_chromatic` label once you're ready to check for visual regressions.
67
66
68
-
## Playwright tests
67
+
### Location
68
+
69
+
Storybook tests should be colocated with the component(s) under test and should end with the suffix `.stories.tsx`.
70
+
71
+
For example:
72
+
`components/Avatar.tsx`
73
+
`components/Avatar.stories.tsx`
69
74
70
-
[Playwright](https://playwright.dev/) offers a solution for integration tests where tests are executed in a real browser. By executing at this level it provides a realistic representation of a user interacting with the page.
75
+
## E2E tests
71
76
72
-
### How to run locally
77
+
[Playwright](https://playwright.dev/) offers a solution for E2E tests where tests are executed in a real browser.
78
+
79
+
Only create a Playwright test when a full browser environment is required.
73
80
74
81
The first time you run Playwright you will be asked to install a local browser, which you can do with the following command:
75
82
@@ -81,8 +88,45 @@ To run the tests on the command line in headless mode:
81
88
82
89
`make playwright-run`
83
90
84
-
To open the tests in the Playwright UI:
91
+
To open the tests in the Playwright UI, with hot reloading:
85
92
86
93
`make playwright-open`
87
94
88
-
Changes to the tests and implementation code will hot reload.
95
+
### Location
96
+
97
+
Playwright tests are located in the [playwright](../playwright/) directory and should end with the suffix `e2e.spec.ts`.
98
+
99
+
For example:
100
+
`lightbox.e2e.spec.ts`
101
+
102
+
## Testing strategy
103
+
104
+
### Testing pyramid
105
+
106
+
Understand the testing pyramid:
107
+
https://circleci.com/blog/testing-pyramid/
108
+
109
+
### Do test
110
+
111
+
When we write tests for Components, we should test the render logic and not the internal implementation details.
112
+
113
+
Test the expected behaviour of a component: what it renders, how the props it receives alter what's rendered and how user interactions and events that trigger changes of state alter what's rendered.
114
+
115
+
Look for conditional statements (ternaries, if statements, and switch statements) in the render method for clues about what to test. You should always test your public interface (the props your component takes). For example, if the Component under test takes a prop which is a function that is executed onClick we can test it’s executed by simulating a click on the Component under test.
116
+
117
+
### Don't test
118
+
119
+
Tests that require you to duplicate the application code exactly. These tests will be brittle. For example if a component renders with a height 10px, if you test that the component has a height 10px and you then update the Component so its height is 11px then you’ll have to update your test, even though the component’s behaviour has not changed. Don’t test inline styles, unless the value can change based on props/state.
120
+
121
+
Don't assert against behaviours covered by the library code. EG. Testing types of properties passed to the component, this is unnecessary.
122
+
123
+
### Snapshots
124
+
125
+
Jest [Snapshot](https://jestjs.io/docs/en/snapshot-testing) tests make sure the rendered output of a UI Component does not change unexpectedly.
126
+
127
+
We will **not** be writing snapshot test Components for the following reasons:
128
+
129
+
- Snapshots immortalise a Component’s current markup as the true markup, regardless of whether or not the component is correct.
130
+
- Too easy to fix tests without fixing underlying bugs simply by running `jest --u` override command.
131
+
- Increased risk of false negatives and false positives - If the tests fail when there are no bugs, that is a false negative. If the tests pass when there are bugs present, that is a false positive.
132
+
- Developer time required to check snapshot test failures when simple non-breaking changes introduced, plus developer time required to review snapshot output in Pull Requests.
0 commit comments