chore: updated docs

avantifellows · Sep 9, 2024 · 3aa60c5 · 3aa60c5
1 parent bd080e3
commit 3aa60c5
Show file tree

Hide file tree

Showing 6 changed files with 214 additions and 8 deletions.
diff --git a/docs/CI_CD.md b/docs/CI_CD.md
@@ -0,0 +1,23 @@
+# CI/CD Documentation
+
+This pipeline is set up to ensure our code is clean, reliable, and thoroughly tested before it hits the main branch. Here's how it flows:
+
+<details>
+
+<summary>CI/CD Flow Diagram</summary>
+
+![CI CD Flow](./images/ci-cd-flow.png)
+
+</details>
+
+### Github Action Workflows
+
+1. **[Large File Checks](../.github/workflows/checks.yml)**: We check for any oversized files. We don’t want anything over 5MB sneaking into the repository.
+
+2. **[Code Quality Checks](../.github/workflows/checks.yml)**: Next, we run our code through ESLint and Prettier. This step makes sure everything is properly formatted and free of linting issues.
+
+3. **[Unit Tests](../.github/workflows/tests.yaml)**: After that, Jest comes into play to run our unit tests. This checks if all the components and functions are behaving as they should be, catching any issues early on.
+
+4. **[E2E Tests](../.github/workflows/tests.yaml)**: Finally, we dive into the E2E tests with Cypress. We run these tests in both Chrome and Firefox, making sure the app works as expected across different browsers. These tests also use MSW to mock APIs, ensuring our server-side rendering (SSR) flows are tested just right.
+
+> Once the CI checks are cleared, our code automatically gets deployed using **_AWS Amplify_**.
diff --git a/docs/E2E-TESTING.md b/docs/E2E-TESTING.md
@@ -0,0 +1,74 @@
+# E2E Flow with Cypress and MSW for SSR
+
+In our end-to-end (E2E) testing, we use Cypress paired with MSW to mock APIs, especially for testing server-side rendering (SSR) flows. Here’s why this combo works so well:
+
+**_Why Cypress?_**
+
+Cypress is great for E2E testing because it lets us interact with the app just like a user would. We can simulate clicks, form submissions, and other interactions, then check if everything responds as expected. It's fast, reliable, and integrates smoothly with our development workflow.
+
+**_Why MSW?_**
+
+When it comes to SSR, things can get tricky because server-side logic often depends on external APIs. That’s where MSW (_Mock Service Worker_) comes in. By mocking these API calls, MSW allows us to simulate various backend responses directly in our tests. This way, we can test how the app behaves without relying on the actual backend, which can be slow, unpredictable, or difficult to control.
+
+**_How It Works Together_**
+
+Cypress handles the user interactions, while MSW ensures that the SSR logic gets the data it expects, regardless of what’s going on with the real backend. This setup gives us confidence that our SSR pages will render correctly and that our app’s UI will behave as intended, even in edge cases.
+
+### How to Run It?
+
+To run the application with the mock server enabled, follow these steps:
+
+1. **Set Up Environment Variables**: Copy the .env.example and set the environment variables. Make sure to set the `APP_ENV="testing"` to use msw.
+
+2. **Start the Application**: Run the application.
+
+   ```bash
+   npm run build
+   npm run start
+   ```
+
+> The mock server will automatically start if APP_ENV is set to "testing".
+
+3. **Verify Mock Server Activation**: When the application starts, you should see console logs confirming that the mock server has been started:
+
+   ```bash
+   Starting Mock Server...
+   Mock Server Started!
+   ```
+
+4. **Run E2E Tests**: To run your end-to-end tests, just execute:
+
+   ```bash
+   npm run test:cypress
+   ```
+
+### Key Files to Know
+
+- **Mock Handlers:** `cypress/mocks/handlers.ts`
+
+  This file contains the API mocking logic for SSR. It defines handlers for API routes, simulating requests like fetching sessions, creating sessions, and patching session data.
+
+- **Mock Data:** `cypress/mocks/mockdata.ts`
+
+  This data simulates user input in forms and is used by the handlers to respond to requests.
+
+- **Initial Sessions Data:** `cypress/fixtures/initial_sessions.json`
+
+  This file contains the initial data that's mocked as if it were in the database. The mock server uses this data to simulate a real backend.
+
+- **E2E Test Files:**
+
+  - `cypress/e2e/quiz.cy.ts`: Tests related to quiz sessions.
+  - `cypress/e2e/live.cy.ts`: Tests related to live sessions.
+
+- **Support File:** `cypress\support\index.ts`
+
+  Custom commands to test flow easily.
+
+  - `customInput(name: string, value: string)`
+  - `customSelect(name: string, option: Option)`
+  - `customMultiSelect(name: string, options: Option[])`
+  - `customSwitch(name: string, value: boolean)`
+  - `customDatePicker(name: string, value: Date)`
+  - `customCheckbox(name: string, values: any[])`
+  - `checkDisabled(selector: string[])`
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
@@ -52,28 +52,137 @@
 - **_action-type_** - `create` | `edit` | `duplicate`
 - **_active-step_** - `basic` | `platform` | `timeline`
 
-## Diagrams
+## Sample Session
 
 <details>
-<summary>Architecture</summary>
-
-![Architecture Diagram](../docs/images/architecture.png)
+<summary>Sample Quiz Session</summary>
+
+```json
+{
+  "auth_type": "ID",
+  "created_by_id": null,
+  "end_time": "2024-08-26T16:00:00Z",
+  "id": 825,
+  "id_generation": false,
+  "inserted_at": "2024-08-19T11:54:57",
+  "is_active": true,
+  "meta_data": {
+    "admin_testing_link": "https://staging-quiz.avantifellows.org/quiz/66c5fb6b23b8aa8bac7665d4?apiKey=6qOO8UdF1EGxLgzwIbQN&userId=test_admin",
+    "batch_id": "HaryanaStudents_9_Foundation_24_001",
+    "cms_test_id": "https://cms.peerlearning.com/chapter_tests/6556f6763562d97a6300aa35",
+    "course": "Foundation",
+    "date_created": "2024-08-19T17:24:57.292Z",
+    "grade": 9,
+    "group": "HaryanaStudents",
+    "has_synced_to_bq": false,
+    "infinite_session": false,
+    "marking_scheme": "4,-1",
+    "number_of_fields_in_popup_form": "",
+    "optional_limits": "N/A",
+    "parent_id": "HR-9-Foundation-24",
+    "report_link": "https://lnk.avantifellows.org/8KdG",
+    "shortened_link": "https://lnk.avantifellows.org/Jtcn",
+    "show_answers": false,
+    "status": "success",
+    "stream": "pcmb",
+    "test_format": "mock_test",
+    "test_purpose": "one_time",
+    "test_takers_count": 10,
+    "test_type": "assessment"
+  },
+  "name": "Cypress Quiz Session",
+  "owner_id": null,
+  "platform": "quiz",
+  "platform_id": "66c5fb6b23b8aa8bac7665d4",
+  "platform_link": "66c5fb6b23b8aa8bac7665d4",
+  "popup_form": false,
+  "popup_form_id": null,
+  "portal_link": "https://staging-auth.avantifellows.org?sessionId=HaryanaStudents_66c5fb6b23b8aa8bac7665d4",
+  "purpose": {
+    "params": "quiz",
+    "type": "attendance"
+  },
+  "redirection": true,
+  "repeat_schedule": {
+    "params": [1, 2, 3, 4, 5],
+    "type": "weekly"
+  },
+  "session_id": "HaryanaStudents_66c5fb6b23b8aa8bac7665d4",
+  "signup_form": false,
+  "signup_form_id": null,
+  "start_time": "2024-08-19T10:00:00Z",
+  "type": "sign-in",
+  "updated_at": "2024-08-21T14:36:30"
+}
+```
 
 </details>
 
 <details>
+<summary>Sample Live Session</summary>
+
+```json
+{
+  "auth_type": "ID",
+  "created_by_id": null,
+  "end_time": "2024-08-23T20:00:00Z",
+  "id": 826,
+  "id_generation": false,
+  "inserted_at": "2024-08-19T12:21:29",
+  "is_active": true,
+  "meta_data": {
+    "batch_id": "HaryanaStudents_9_Foundation_24_001,HaryanaStudents_10_Foundation_24_001",
+    "date_created": "2024-08-19T17:51:28.813Z",
+    "grade": 9,
+    "group": "HaryanaStudents",
+    "number_of_fields_in_popup_form": "",
+    "parent_id": "",
+    "shortened_link": "https://lnk.avantifellows.org/L7gH",
+    "status": "success",
+    "subject": "Maths,Physics",
+    "test_takers_count": 10
+  },
+  "name": "Cypress Live Session Edit",
+  "owner_id": null,
+  "platform": "youtube",
+  "platform_id": "jfKfPfyJRdk",
+  "platform_link": "https://www.youtube.com/live/jfKfPfyJRdk",
+  "popup_form": false,
+  "popup_form_id": null,
+  "portal_link": "https://staging-auth.avantifellows.org?sessionId=HaryanaStudents_HaryanaStudents_9_Foundation_24_001,HaryanaStudents_10_Foundation_24_001_45523_jfKfPfyJRdk",
+  "purpose": {
+    "sub-type": "liveclass"
+  },
+  "redirection": true,
+  "repeat_schedule": {
+    "params": [1, 2, 3, 4, 5, 6, 7],
+    "type": "weekly"
+  },
+  "session_id": "HaryanaStudents_HaryanaStudents_9_Foundation_24_001,HaryanaStudents_10_Foundation_24_001_45523_jfKfPfyJRdk",
+  "signup_form": false,
+  "signup_form_id": null,
+  "start_time": "2024-08-19T08:00:00Z",
+  "type": "sign-in",
+  "updated_at": "2024-08-19T12:28:26"
+}
+```
 
-<summary>Sequence Diagram</summary>
+</details>
 
-![Sequence Diagram](../docs/images/sequence.png)
+## Diagrams
+
+<details>
+<summary>Architecture</summary>
+
+![Architecture Diagram](./images/architecture.png)
 
 </details>
 
 <details>
 
-<summary>CI/CD Flow Diagram</summary>
+<summary>Sequence Diagram</summary>
 
-![CI CD Flow](../docs/images/ci-cd-flow.png)
+![Sequence Diagram](./images/sequence.png)
 
 </details>
 

diff --git a/docs/images/architecture.png b/docs/images/architecture.png
diff --git a/docs/images/ci-cd-flow.png b/docs/images/ci-cd-flow.png
diff --git a/docs/images/sequence.png b/docs/images/sequence.png