From a0f96c8902cc82b32af1c940f65d14b8d1985477 Mon Sep 17 00:00:00 2001 From: BrunoQuaresma Date: Tue, 2 Jan 2024 18:48:07 +0000 Subject: [PATCH 1/5] docs(site): update fetching data docs --- docs/contributing/frontend.md | 54 +++++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/docs/contributing/frontend.md b/docs/contributing/frontend.md index 965d80e842d6c..ac960f29537b8 100644 --- a/docs/contributing/frontend.md +++ b/docs/contributing/frontend.md @@ -99,11 +99,44 @@ the api/queries folder when it is possible. ### Where to fetch data -Finding the right place to fetch data in React apps is the million-dollar -question, but we decided to make it only in the page components and pass the -props down to the views. This makes it easier to find where data is being loaded -and easy to test using Storybook. So you will see components like `UsersPage` -and `UsersPageView`. +In the past, our approach involved creating separate components for page and +view, where the page component served as a container responsible for fetching +data and passing it down to the view. + +For instance, when developing a page to display users, we would have a +`UsersPage` component with a corresponding `UsersPageView`. The `UsersPage` +would handle API calls, while the `UsersPageView` managed the presentational +logic. + +Over time, however, we encountered challenges with this approach, particularly +in terms of excessive props drilling. To address this, we opted to fetch data in +proximity to its usage. Taking the example of displaying users, in the past, if +we were creating a header component for that page, we would have needed to fetch +the data in the page component and pass it down through the hierarchy +(`UsersPage -> UsersPageView -> UsersHeader`). Now, with advancements such as +`react-query`, data fetching can be performed directly in the `UsersHeader` +component, eliminating the need for multiple places to handle the same request +([more info](https://github.com/TanStack/query/discussions/608#discussioncomment-29735)). + +To simplify visual testing of scenarios where components are responsible for +fetching data, you can easily set the queries' value using `parameters.queries` +within the component's story. + +```tsx +export const WithQuota: Story = { + parameters: { + queries: [ + { + key: getWorkspaceQuotaQueryKey(MockUser.username), + data: { + credits_consumed: 2, + budget: 40, + }, + }, + ], + }, +}; +``` ### API @@ -237,13 +270,16 @@ another page, you should probably consider using the **E2E** approach. ### Visual testing -Test components without user interaction like testing if a page view is rendered -correctly depending on some parameters, if the button is showing a spinner if -the `loading` props are passing, etc. This should always be your first option -since it is way easier to maintain. For this, we use +Test components without user interaction like testing if a page/component is +rendered correctly depending on some parameters, if the button is showing a +spinner, if the `loading` props are passing, etc. This should always be your +first option since it is way easier to maintain. For this, we use [Storybook](https://storybook.js.org/) and [Chromatic](https://www.chromatic.com/). +> ℹ️ To learn more about testing components that fetch API data, refer to the +> [**Where to fetch data**](#where-to-fetch-data) section. + ### What should I test? Choosing what to test is not always easy since there are a lot of flows and a From e15c47a3f5543486827aeca3046b8a440a568c17 Mon Sep 17 00:00:00 2001 From: BrunoQuaresma Date: Tue, 2 Jan 2024 19:04:34 +0000 Subject: [PATCH 2/5] Update workding with Michael suggestions --- docs/contributing/frontend.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contributing/frontend.md b/docs/contributing/frontend.md index ac960f29537b8..85f95395f1333 100644 --- a/docs/contributing/frontend.md +++ b/docs/contributing/frontend.md @@ -115,7 +115,8 @@ we were creating a header component for that page, we would have needed to fetch the data in the page component and pass it down through the hierarchy (`UsersPage -> UsersPageView -> UsersHeader`). Now, with advancements such as `react-query`, data fetching can be performed directly in the `UsersHeader` -component, eliminating the need for multiple places to handle the same request +component, allowing UI elements to declare and consume their data-fetching +dependencies directly, while preventing duplicate server requests ([more info](https://github.com/TanStack/query/discussions/608#discussioncomment-29735)). To simplify visual testing of scenarios where components are responsible for From 47ffd424f669023ea420020d275e15e1f53ad3e4 Mon Sep 17 00:00:00 2001 From: BrunoQuaresma Date: Tue, 2 Jan 2024 19:05:21 +0000 Subject: [PATCH 3/5] update wording --- docs/contributing/frontend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/frontend.md b/docs/contributing/frontend.md index 85f95395f1333..dd567b0d882dd 100644 --- a/docs/contributing/frontend.md +++ b/docs/contributing/frontend.md @@ -113,7 +113,7 @@ in terms of excessive props drilling. To address this, we opted to fetch data in proximity to its usage. Taking the example of displaying users, in the past, if we were creating a header component for that page, we would have needed to fetch the data in the page component and pass it down through the hierarchy -(`UsersPage -> UsersPageView -> UsersHeader`). Now, with advancements such as +(`UsersPage -> UsersPageView -> UsersHeader`). Now, with libraries such as `react-query`, data fetching can be performed directly in the `UsersHeader` component, allowing UI elements to declare and consume their data-fetching dependencies directly, while preventing duplicate server requests From 165e2a57c0f940c960c028012613d717263bf08f Mon Sep 17 00:00:00 2001 From: Bruno Quaresma Date: Wed, 3 Jan 2024 09:19:46 -0300 Subject: [PATCH 4/5] Update docs/contributing/frontend.md Co-authored-by: Kira Pilot --- docs/contributing/frontend.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/contributing/frontend.md b/docs/contributing/frontend.md index dd567b0d882dd..1c29cef27a452 100644 --- a/docs/contributing/frontend.md +++ b/docs/contributing/frontend.md @@ -271,9 +271,7 @@ another page, you should probably consider using the **E2E** approach. ### Visual testing -Test components without user interaction like testing if a page/component is -rendered correctly depending on some parameters, if the button is showing a -spinner, if the `loading` props are passing, etc. This should always be your +We use visual tests to test components without user interaction like testing if a page/component is rendered correctly depending on some parameters, if a button is showing a spinner, if `loading` props are passed correctly, etc. This should always be your first option since it is way easier to maintain. For this, we use [Storybook](https://storybook.js.org/) and [Chromatic](https://www.chromatic.com/). From 8d7854553012878e8b1ac7b26247fb477e63e363 Mon Sep 17 00:00:00 2001 From: BrunoQuaresma Date: Wed, 3 Jan 2024 12:23:55 +0000 Subject: [PATCH 5/5] Fix format --- docs/contributing/frontend.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/contributing/frontend.md b/docs/contributing/frontend.md index 1c29cef27a452..e24fadf8f53f5 100644 --- a/docs/contributing/frontend.md +++ b/docs/contributing/frontend.md @@ -271,8 +271,10 @@ another page, you should probably consider using the **E2E** approach. ### Visual testing -We use visual tests to test components without user interaction like testing if a page/component is rendered correctly depending on some parameters, if a button is showing a spinner, if `loading` props are passed correctly, etc. This should always be your -first option since it is way easier to maintain. For this, we use +We use visual tests to test components without user interaction like testing if +a page/component is rendered correctly depending on some parameters, if a button +is showing a spinner, if `loading` props are passed correctly, etc. This should +always be your first option since it is way easier to maintain. For this, we use [Storybook](https://storybook.js.org/) and [Chromatic](https://www.chromatic.com/).