@product7/feedback-sdk 1.6.8 → 1.7.0

package/dist/docs/survey-test-cases.md

@@ -0,0 +1,398 @@
+# Survey Widget — QA Test Cases
+
+## Overview
+This document covers manual test cases for verifying the survey widget functionality across all supported survey types (NPS, CSAT, CES, Custom, and Multi-page).
+
+---
+
+## Prerequisites
+
+- SDK is initialized with a valid `workspace` and `userContext`
+- `init()` has been called successfully (session token received)
+- Browser DevTools open to monitor network requests and console
+
+---
+
+## Test Environment Setup
+
+```js
+const sdk = new FeedbackSDK({
+  workspace: 'your-workspace',
+  userContext: { user_id: 'qa_user_01', email: 'qa@example.com' }
+});
+await sdk.init();
+```
+
+---
+
+## TC-01: NPS Survey — Basic Display
+
+**Objective:** Verify NPS survey renders correctly with 11-point scale.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'nps', ratingScale: 11, title: 'How likely are you to recommend us?', lowLabel: 'Not likely', highLabel: 'Very likely' })`
+2. Observe the survey widget on screen
+
+**Expected Results:**
+- [ ] Survey widget appears at the configured position (default: bottom-right)
+- [ ] Title text is displayed: "How likely are you to recommend us?"
+- [ ] 11 score buttons are shown, numbered 0 through 10
+- [ ] "Not likely" label appears below the leftmost button
+- [ ] "Very likely" label appears below the rightmost button
+- [ ] A close (✕) button is visible in the top-right corner of the widget
+
+---
+
+## TC-02: NPS Survey — Score Selection
+
+**Objective:** Verify score buttons highlight correctly on selection.
+
+**Steps:**
+1. Show NPS survey (as in TC-01)
+2. Click score button **7**
+3. Click score button **9**
+
+**Expected Results:**
+- [ ] After clicking 7: button 7 is visually highlighted/selected
+- [ ] After clicking 9: button 9 is highlighted, button 7 is no longer highlighted
+- [ ] Only one button is selected at a time
+
+---
+
+## TC-03: NPS Survey — Submission
+
+**Objective:** Verify NPS survey submits the selected score.
+
+**Steps:**
+1. Show NPS survey with `showSubmitButton: true` and a valid `surveyId`
+2. Click score button **8**
+3. Click the **Submit** button
+4. Observe network tab
+
+**Expected Results:**
+- [ ] A POST request is sent to `/widget/surveys/{surveyId}/responses`
+- [ ] Request payload contains `rating: 8`
+- [ ] Survey widget closes after submission
+- [ ] A success notification ("Thank you for your feedback!") appears briefly
+- [ ] `survey:submitted` event is fired (verify in console with `sdk.on('survey:submitted', console.log)`)
+
+---
+
+## TC-04: NPS Survey — Submit Without Score
+
+**Objective:** Verify error message when submitting with no score selected.
+
+**Steps:**
+1. Show NPS survey with `showSubmitButton: true`
+2. Do NOT click any score button
+3. Click the **Submit** button
+
+**Expected Results:**
+- [ ] Error message "Please select a rating" appears inside the widget
+- [ ] Survey does NOT close
+- [ ] No API request is made
+- [ ] Error disappears after ~3 seconds
+
+---
+
+## TC-05: NPS Survey — Auto-submit on Select
+
+**Objective:** Verify survey auto-submits when `autoSubmitOnSelect: true`.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'nps', autoSubmitOnSelect: true, surveyId: 'survey-id' })`
+2. Click any score button
+
+**Expected Results:**
+- [ ] Survey submits immediately upon clicking a score (no submit button click needed)
+- [ ] POST request is sent with the selected score
+- [ ] Survey closes and success notification shows
+
+---
+
+## TC-06: CSAT Survey — Display and Selection
+
+**Objective:** Verify CSAT survey renders emoji buttons correctly.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'csat', title: 'How satisfied are you?' })`
+2. Click the 4th emoji (😊)
+
+**Expected Results:**
+- [ ] 5 emoji buttons are displayed (😞 😟 😐 🙂 😄)
+- [ ] Clicked emoji is visually selected/highlighted
+- [ ] Other emojis are deselected
+- [ ] Score corresponds to position (1–5)
+
+---
+
+## TC-07: CES Survey — Display and Selection
+
+**Objective:** Verify CES survey renders effort scale buttons.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'ces', title: 'How easy was it?' })`
+2. Click **Easy**
+
+**Expected Results:**
+- [ ] 5 buttons displayed: Very Difficult / Difficult / Neutral / Easy / Very Easy
+- [ ] Clicked button is highlighted
+- [ ] Other buttons are deselected
+
+---
+
+## TC-08: Survey with Feedback Text Input
+
+**Objective:** Verify optional feedback textarea appears and value is submitted.
+
+**Steps:**
+1. Show any survey with `showFeedbackInput: true` and `showSubmitButton: true`
+2. Select a score
+3. Type "Great product!" in the feedback textarea
+4. Click Submit
+
+**Expected Results:**
+- [ ] Textarea is visible below the score selection
+- [ ] Typed text appears in the textarea
+- [ ] Submitted payload includes `feedback: "Great product!"`
+
+---
+
+## TC-09: Survey Dismiss — Close Button
+
+**Objective:** Verify close button dismisses the survey.
+
+**Steps:**
+1. Show any survey
+2. Click the ✕ (close) button
+
+**Expected Results:**
+- [ ] Survey widget fades out and is removed from the DOM
+- [ ] `survey:dismissed` event is fired
+- [ ] If `onDismiss` callback was provided, it is called
+- [ ] If a valid `surveyId` was set, a POST request is sent to `/widget/surveys/{surveyId}/dismiss`
+
+---
+
+## TC-10: Survey Dismiss — Escape Key
+
+**Objective:** Verify pressing Escape closes the survey.
+
+**Steps:**
+1. Show any survey
+2. Press the **Escape** key on the keyboard
+
+**Expected Results:**
+- [ ] Survey closes (same behaviour as TC-09)
+- [ ] `survey:dismissed` event fires
+
+---
+
+## TC-11: Survey — Disabled State
+
+**Objective:** Verify survey is suppressed when `enabled: false`.
+
+**Steps:**
+1. Call `sdk.showSurvey({ surveyType: 'nps', enabled: false })`
+
+**Expected Results:**
+- [ ] No survey widget appears in the DOM
+- [ ] `showSurvey()` returns `null`
+- [ ] `survey:suppressed` event is fired with `reason: 'disabled'`
+
+---
+
+## TC-12: Survey — Position Variants
+
+**Objective:** Verify survey renders in each supported position.
+
+**Steps:**
+1. Test each position: `bottom-right`, `bottom-left`, `center`
+2. Call `sdk.showSurvey({ surveyType: 'nps', position: '<position>' })`
+
+**Expected Results:**
+| Position | Expected Appearance |
+|---|---|
+| `bottom-right` | Widget anchored to bottom-right corner |
+| `bottom-left` | Widget anchored to bottom-left corner |
+| `center` | Widget centered on screen with backdrop overlay |
+
+- [ ] For `center`: backdrop overlay is displayed behind the widget
+- [ ] Clicking the backdrop (center mode) closes the survey
+
+---
+
+## TC-13: Survey — Theme Variants
+
+**Objective:** Verify light and dark themes apply correctly.
+
+**Steps:**
+1. Test `theme: 'light'` and `theme: 'dark'`
+
+**Expected Results:**
+- [ ] Light theme: white/light background, dark text
+- [ ] Dark theme: dark background, light text
+- [ ] Theme class is applied to the survey element
+
+---
+
+## TC-14: Multi-page Survey — Navigation
+
+**Objective:** Verify multi-page survey navigates between pages correctly.
+
+**Setup:**
+```js
+sdk.showSurvey({
+  surveyId: 'multi-page-id',
+  pages: [
+    { id: 'p1', type: 'rating', title: 'Rate our product', position: 0, ratingConfig: { scale: 5 } },
+    { id: 'p2', type: 'text', title: 'Any comments?', position: 1 },
+  ]
+});
+```
+
+**Steps:**
+1. Observe page 1
+2. Click a rating button
+3. Click **Next**
+4. Observe page 2
+5. Click **Back**
+6. Observe page 1 again
+
+**Expected Results:**
+- [ ] Page 1 shows "Page 1 of 2" progress indicator
+- [ ] Action button on page 1 reads "Next"
+- [ ] After clicking Next: page 2 loads, progress shows "Page 2 of 2"
+- [ ] Page 2 has a **Back** button
+- [ ] Action button on page 2 reads "Submit"
+- [ ] After clicking Back: page 1 is shown again
+
+---
+
+## TC-15: Multi-page Survey — Validation
+
+**Objective:** Verify each page validates input before advancing.
+
+**Steps (Rating page):**
+1. Display multi-page survey on page 1 (rating type)
+2. Click **Next** without selecting a rating
+
+**Expected Results:**
+- [ ] Error message "Please select a rating" appears
+- [ ] Survey does NOT advance to page 2
+
+**Steps (Text page):**
+1. Advance to a text-type page
+2. Click **Submit** without entering any text
+
+**Expected Results:**
+- [ ] Error message "Please enter an answer" appears
+- [ ] Survey does NOT submit
+
+**Steps (Multiple choice page):**
+1. Advance to a multiple-choice page
+2. Click **Submit** without selecting any option
+
+**Expected Results:**
+- [ ] Error message "Please select an option" appears
+
+---
+
+## TC-16: Multi-page Survey — Full Submission
+
+**Objective:** Verify complete multi-page survey submits all page answers.
+
+**Steps:**
+1. Display the multi-page survey (TC-14 setup)
+2. On page 1: select a rating, click **Next**
+3. On page 2: type a comment, click **Submit**
+4. Check network request
+
+**Expected Results:**
+- [ ] POST to `/widget/surveys/{surveyId}/responses` is made
+- [ ] Payload `answers.page_answers` contains entries for both pages
+- [ ] Success notification appears after submission
+
+---
+
+## TC-17: getActiveSurveys() — Fetch and Display
+
+**Objective:** Verify active surveys can be fetched and shown programmatically.
+
+**Steps:**
+1. Call `const surveys = await sdk.getActiveSurveys()`
+2. Log result to console
+3. Call `sdk.showSurveyById(surveys[0].surveyId)`
+
+**Expected Results:**
+- [ ] `getActiveSurveys()` returns an array of survey objects
+- [ ] Each survey has `surveyId`, `surveyType`, `title` fields
+- [ ] `showSurveyById()` successfully renders the matching survey
+- [ ] Correct survey type is shown (NPS/CSAT/CES matches the fetched type)
+
+---
+
+## TC-18: showSurveyById() — Survey Not Found
+
+**Objective:** Verify error handling when survey ID doesn't exist.
+
+**Steps:**
+1. Call `await sdk.showSurveyById('nonexistent-id')`
+
+**Expected Results:**
+- [ ] Promise rejects with an error message containing "not found"
+- [ ] No survey widget appears in the DOM
+
+---
+
+## TC-19: Survey — onSubmit Callback
+
+**Objective:** Verify `onSubmit` callback receives the correct response object.
+
+**Steps:**
+1. Call:
+```js
+sdk.showSurvey({
+  surveyType: 'nps',
+  ratingScale: 11,
+  showSubmitButton: true,
+  onSubmit: (response) => console.log('onSubmit:', response)
+});
+```
+2. Select score 9 and click Submit
+3. Check console output
+
+**Expected Results:**
+- [ ] `onSubmit` is called once
+- [ ] `response.type` is `'nps'`
+- [ ] `response.score` is `9`
+- [ ] `response.timestamp` is a valid ISO date string
+
+---
+
+## TC-20: Survey — SDK Not Initialized Guard
+
+**Objective:** Verify SDK throws when survey methods are called before `init()`.
+
+**Steps:**
+1. Create SDK instance but do NOT call `init()`
+2. Call `sdk.showSurvey({ surveyType: 'nps' })`
+
+**Expected Results:**
+- [ ] Error is thrown: "SDK must be initialized before showing surveys. Call init() first."
+- [ ] No network requests are made
+
+---
+
+## Regression Checklist
+
+After any change to survey code, verify:
+
+- [ ] All 4 survey types render without console errors (NPS, CSAT, CES, Custom)
+- [ ] Score selection works for each type
+- [ ] Submit sends correct payload to the API
+- [ ] Dismiss/close cleans up the DOM (no lingering elements)
+- [ ] Multi-page navigation works forward and backward
+- [ ] `survey:shown`, `survey:submitted`, `survey:dismissed`, `survey:suppressed` events all fire at the right time
+- [ ] `autoSubmitOnSelect: true` does not show submit button
+- [ ] `enabled: false` prevents the survey from rendering