revised docs and shadow report env names, breaking change

Author: petermsouzajr

README.md

@@ -32,11 +32,11 @@ Our package bridges Cypress and Playwright test runs with Google Sheets or CSV,
 
 After installing `qa-shadow-report` using the command:
 
-    `npm i qa-shadow-report`
+    npm i qa-shadow-report
 
 you will then need to run the command:
 
-    `npx qasr-setup`
+    npx qasr-setup
 
 this initiates a series of `Yes` or `No` questions to guide you through setting up the tool for your testing framework and package manager. You may choose to exit the setup at any time by entering `EXIT`, which is not recommended. If you exit setup, you will then need to restart using the command `npx qasr-setup`
 
@@ -105,15 +105,15 @@ Before you begin, ensure you have the following packages and authentication. You
 
 `npm install --save-dev mochawesome mochawesome-merge`
 
-- **Google Spreadsheet ID:** Place the sheet's URL directly in an environment variable: `https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160`.
+- **Google Spreadsheet URL:** Place the sheet's URL directly in an environment variable: `https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160`.
 - **Service Account Credentials for Google Sheets:** Follow the detailed guide from `node-google-spreadsheet` they have a great document describing Google Service Accounts [node-google-spreadshee: Google Service Account](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication?id=authentication-methods)
-  to set up and safely store your credentials, updating `shadowReportConfig.*` (`js`, or `ts`) with the path to these credentials. Use `.gitignore` to secure your credentials within your project.
+  to set up and safely store your credentials. update `shadowReportConfig.*` (`js`, or `ts`) with the path to these credentials. Use `.gitignore` to secure your credentials within your project. Allow your service account to Edit the Google Sheet by sharing the google sheet with the service account emial address as an Editor.
 - **qa-shadow-report configuration file:** Usually installed by the setup wizard in the root of your Cypress project, named: `shadowReportConfig.*` (`js`, or `ts`).
 
   - `teamNames`: An array of identifiers representing different teams within your organization that may use or contribute to the testing process.
   - `testTypes`: Specifies the types of tests included in your project, such as API tests or UI tests, to help organize and filter test executions.
   - `testCategories`: Defines the categories of tests your project includes, such as smoke tests for quick checks or sanity tests for verifying vital features after builds.
-  - `googleSpreadsheetId`: The unique identifier for your Google Sheets project, found within the URL of your Google Sheet. This is used to integrate and sync test result data.
+  - `googleSpreadsheetUrl`: The URL of your Google Sheet. This is used to integrate and sync test result data.
   - `googleKeyFilePath`: The file path to your Google service account credentials, which are required to authenticate and interact with Google Sheets API.
   - `testData`: The file path to where your test results in JSON format are stored, typically generated by Cypress or another testing framework.
   - `csvDownloadsPath`: The directory path where the generated CSV files will be saved. This is useful for users who prefer to download and review test results in a CSV format.
@@ -132,7 +132,7 @@ Before you begin, ensure you have the following packages and authentication. You
       'smoke',
       'sanity',
     ],
-    googleSpreadsheetId: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
+    googleSpreadsheetUrl: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
     googleKeyFilePath: 'googleCredentials.json',
     testData: 'cypress/results/output.json',
     csvDownloadsPath: 'downloads'
@@ -168,9 +168,9 @@ Adjust these scripts as needed for your project's requirements.
 
 Before you begin, ensure you have the following packages and authentication, you can run the command `npx qasr-setup` which initiates a couple of Yes or No questions to guide you through setting up the tool for your testing framework and package manager:
 
-- **Google Spreadsheet ID:** Place the sheet's URL directly in an environment variable: `https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160`.
+- **Google Spreadsheet URL:** Place the sheet's URL directly in an environment variable: `https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160`.
 - **Service Account Credentials for Google Sheets:** Follow the detailed guide from `node-google-spreadsheet` they have a great document describing Google Service Accounts [node-google-spreadshee: Google Service Account](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication?id=authentication-methods)
-  to set up and safely store your credentials, updating `shadowReportConfig.*` (`js`, or `ts`) with the path to these credentials. Use `.gitignore` to secure your credentials within your project.
+  to set up and safely store your credentials. update `shadowReportConfig.*` (`js`, or `ts`) with the path to these credentials. Use `.gitignore` to secure your credentials within your project. Allow your service account to Edit the Google Sheet by sharing the google sheet with the service account emial address as an Editor.
 - **Playwright Configuration**: In the `playwright.config.js` file, specify the reporter like this:
 
   ```js
@@ -183,7 +183,7 @@ Before you begin, ensure you have the following packages and authentication, you
   - `teamNames`: An array of identifiers representing different teams within your organization that may use or contribute to the testing process.
   - `testTypes`: Specifies the types of tests included in your project, such as API tests or UI tests, to help organize and filter test executions.
   - `testCategories`: Defines the categories of tests your project includes, such as smoke tests for quick checks or sanity tests for verifying vital features after builds.
-  - `googleSpreadsheetId`: The URL of your Google Sheet. This is used to integrate and sync test result data.
+  - `googleSpreadsheetUrl`: The URL of your Google Sheet. This is used to integrate and sync test result data.
   - `googleKeyFilePath`: The file path to your Google service account credentials, which are required to authenticate and interact with Google Sheets API.
   - `testData`: The file path to where your test results in JSON format are stored, typically generated by Cypress or another testing framework.
   - `scvDownloadsPath`: The directory path where the generated CSV files will be saved. This is useful for users who prefer to download and review test results in a CSV format.
@@ -202,7 +202,7 @@ Before you begin, ensure you have the following packages and authentication, you
       'smoke',
       'sanity',
     ],
-    googleSpreadsheetId: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
+    googleSpreadsheetUrl: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
     googleKeyFilePath: 'googleCredentials.json',
     testData: 'cypress/results/output.json',
     csvDownloadsPath: 'downloads'
@@ -232,7 +232,7 @@ In this example, running npm run playwright-test will:
 
 ### To Generate Reports In Sheets
 
-    All commands require that test report data is present, in this example, the report data is generated by the testing framework.
+All commands require that test suite result data is present, in this example, the test suite data is generated by the testing framework, either Cypress or Playwright.
 
 - **To run the root `qa-shadow-report` functionality**
 
@@ -261,7 +261,7 @@ In this example, running npm run playwright-test will:
   - This command processes the data from the test results and create a detailed report.
   - A new Sheet Tab will be created with the current day's title (e.g., `Mar 24, 2024`), to which this detailed report will be written.
   - If the Sheet has Tabs for the previous month (e.g., current month is April and sheet tabs exist for `Mar 24, 2024`, `Mar 25, 2024`), then a monthly summary will be generated with that previous month's data (`Summary Mar 2024`).
-  - The report will fail if JSON test result data is not present.
+  - The report will fail if test result data is not present in JSON format.
   - Duplicate Sheet Tabs are not created by defualt, to create a duplicate Tab, use the flag `--duplicate`.
 
 - **To run the daily report only**
@@ -311,7 +311,7 @@ module.exports = {
     'wilkins',
     'canonicus',
   ],
-  googleSpreadsheetId: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
+  googleSpreadsheetUrl: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
   googleKeyFilePath: 'googleCredentials.json',
   testData: '[framework]/results/output.json',
   csvDownloadsPath: 'downloads'
@@ -364,7 +364,7 @@ module.exports = {
         'accessibility',
         'mobile',
       ],
-      googleSpreadsheetId: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
+      googleSpreadsheetUrl: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
       googleKeyFilePath: 'googleCredentials.json',
       testData: '[framework]/results/output.json',
       csvDownloadsPath: 'downloads'
@@ -404,7 +404,7 @@ module.exports = {
         'alpha',
         'beta',
       ],
-      googleSpreadsheetId: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
+      googleSpreadsheetUrl: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
       googleKeyFilePath: 'googleCredentials.json',
       testData: '[framework]/results/output.json',
       csvDownloadsPath: 'downloads'
@@ -488,7 +488,7 @@ module.exports = {
         'alpha',
         'beta',
       ],
-      googleSpreadsheetId: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
+      googleSpreadsheetUrl: 'https://docs.google.com/spreadsheets/d/1Y8tQWmo3oSB3zIlr1mySs/edit?gid=160#gid=19160',
       googleKeyFilePath: 'googleCredentials.json',
       testData: '[framework]/results/output.json',
       csvDownloadsPath: 'downloads'
@@ -527,13 +527,13 @@ The `cypress/grep` package has a Tags feature, which allows you to add an Object
 
 By integrating `cypress/grep`, you can run subsets of tests based on your annotations, which aligns perfectly with your team's naming conventions and test categorization.
 
-### GitHub CI/CD
+### CI/CD
 
 This package is best suited for automated nightly runs, enabling teams to efficiently monitor project status and collaborate on test results every morning.
 
-**Integrating Google Sheets Credentials with GitHub Actions:**
+**Integrating Google Sheets Credentials with CI/CD:**
 
-For seamless integration in GitHub Actions, as required for manual package operation, the Google Sheets credentials need to be appropriately configured. Given the length constraints of GitHub secrets, it may be necessary to compact the Google Sheets key using GPG encryption.
+For seamless integration into CI/CD pipelines, the Google Sheets credentials need to be appropriately configured. Given the length constraints of most CI/CD environment variables, it may be necessary to compact the Google Sheets key using GPG encryption.
 
 **Steps for Secure Key Management**
 
@@ -542,22 +542,22 @@ For seamless integration in GitHub Actions, as required for manual package opera
    - **Generate a GPG Key Pair:** If not already available, generate a new GPG key pair using the command `gpg --gen-key`.
    - **Encrypt the Secret File:** For a secret file named `google-key.json`, encrypt it by executing `gpg --output google-key.json.gpg --symmetric --cipher-algo AES256 google-key.json`.
 
-2. **Storing Encrypted Secrets in GitHub**
+2. **Storing Encrypted Secrets in Repository/CI Environmen**
 
    - **Repository Storage:** Include the encrypted file (`google-key.json.gpg`) in the repository.
-   - **Creating a GitHub Secret:** Generate a GitHub secret named `GPG_PASSPHRASE` containing the passphrase used for file encryption.
+   - **Creating a CI/CD Environment Variable:** Generate a secret named `GPG_PASSPHRASE` containing the passphrase used for file encryption.
 
-3. **Decrypting the Secret in GitHub Actions**
-   - **Workflow Modification:** Incorporate steps in your GitHub Actions workflow to decrypt the secret file using the stored passphrase. The modifications should align with your project's encryption setup.
+3. **Decrypting the Secret in CI/CD**
+   - **Workflow Modification:** Incorporate steps in your CI/CD workflow to decrypt the secret file using the stored passphrase. The modifications should align with your project's encryption setup.
 
-**Note:** A suitable GitHub Action configuration is required for this process to function correctly:
+**GitHub Actions Example:**
 
-```
+```yaml
 name: Nightly regression and report
 
 on:
   schedule:
-    - cron: "0 1 * * *" # Runs daily at 1 AM UTC
+    - cron: '0 1 * * *' # Runs daily at 1 AM UTC
   push:
     branches:
       - main
@@ -573,7 +573,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "21"
+          node-version: '21'
 
       - name: Install GPG
         run: sudo apt-get install -y gpg
@@ -588,16 +588,62 @@ jobs:
         run: echo "GOOGLE_KEY_FILE_PATH=$(pwd)/googleCredentials.json" >> $GITHUB_ENV
 
       - name: Install dependencies
-        run: npm install --legacy-peer-deps
+        run: npm install
 
       - name: Run QA regression tests
         run: npm run cypress:nightly
 ```
 
+**GitLab CI Example:**  
+(Note: To schedule nightly runs, set up a pipeline schedule in your GitLab project settings.)
+
+```yaml
+stages:
+  - test
+
+nightly_regression:
+  stage: test
+  image: cypress/browsers:22.12.0
+  allow_failure: true
+  before_script:
+    - apt-get update && apt-get install -y gnupg
+    - git checkout $CI_COMMIT_REF_NAME
+  script:
+    - echo "$GPG_PASSPHRASE" | gpg --batch --yes --passphrase-fd 0 --output googleCredentials.json --decrypt googleCredentials.json.gpg
+    - export GOOGLE_KEY_FILE_PATH=$(pwd)/googleCredentials.json
+    - npm install
+    - npm run cypress:nightly
+  only:
+    - main
+```
+
+**AWS CodeBuild Example:**
+For AWS CodeBuild, you can set up a comparable configuration using a `buildspec.yml` file:
+
+```yaml
+version: 0.2
+
+phases:
+  install:
+    runtime-versions:
+      nodejs: 21
+    commands:
+      - apt-get update && apt-get install -y gnupg
+  pre_build:
+    commands:
+      - echo "Decrypting Google Sheets Key..."
+      - echo $GPG_PASSPHRASE | gpg --batch --yes --passphrase-fd 0 --output googleCredentials.json --decrypt googleCredentials.json.gpg
+      - export GOOGLE_KEY_FILE_PATH=$(pwd)/googleCredentials.json
+  build:
+    commands:
+      - npm install
+      - npm run cypress:nightly
+```
+
 Additional Notes:
 
 - **Security:** Be cautious with the passphrase and the encrypted file. If someone gains access to both, they can decrypt your secret.
-- **GPG Version:** Ensure that the GPG version you use locally for encryption is compatible with the version installed in the GitHub Actions runner.
+- **GPG Version:** Ensure that the GPG version you use locally for encryption is compatible with the version installed in the CI/CD environment.
 - **File Paths:** Adjust file paths in the script according to where you store the encrypted file and where the decrypted file is needed.
 
 ### Demo Branch
@@ -607,7 +653,7 @@ For those who want to see `qa-shadow-report` in action before integrating it int
 #### How to Use the Demo
 
 1. **Switch to the Demo Branch:** Navigate to our repository and switch to the branch named `demo`.
-2. **Follow the Setup Instructions:** Ensure you meet the prerequisites and follow the setup steps outlined in the [Setup Guide](#setup-guide).
+2. **Follow the Setup Instructions:** Ensure you meet the prerequisites and follow the setup steps outlined in [Installation](#installation).
 3. **Install Dependencies:**
 
    - **For General Use:**

constants.js

@@ -98,9 +98,9 @@ export const GOOGLE_SHEET_ID = () => {
 
   if (
     shadowConfigDetails &&
-    typeof shadowConfigDetails.googleSpreadsheetId === 'string'
+    typeof shadowConfigDetails.googleSpreadsheetUrl === 'string'
   ) {
-    const envVarMatch = shadowConfigDetails.googleSpreadsheetId.match(
+    const envVarMatch = shadowConfigDetails.googleSpreadsheetUrl.match(
       /^process\.env\.(\w+)$/
     );
 
@@ -112,7 +112,7 @@ export const GOOGLE_SHEET_ID = () => {
         sheetId = process.env[envVarName].split('/d/')[1].split('/')[0] || ''; // Set the value from process.env
       }
     } else {
-      sheetId = shadowConfigDetails.googleSpreadsheetId
+      sheetId = shadowConfigDetails.googleSpreadsheetUrl
         .split('/d/')[1]
         .split('/')[0]; // Use the raw config value if it's not an environment variable
     }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "qa-shadow-report",
-  "version": "1.1.34",
+  "version": "2.0.0",
   "bin": {
     "qa-shadow-report": "./cli.js",
     "qasr": "./cli.js",

scripts/postInstall.js

@@ -142,8 +142,8 @@ const createConfigFile = () => {
         // 'alpha',
         // 'beta',
       ],
-      // Google Spreadsheet URL: Replace with either the actual spreadsheet ID or an environment variable.
-      // googleSpreadsheetId: 'your-google-spreadsheet-id' OR googleSpreadsheetId: process.env.GOOGLE_SHEET_URL,
+      // Google Spreadsheet URL: Replace with either the spreadsheet URL or an environment variable.
+      // googleSpreadsheetUrl: 'your-google-spreadsheet-url' OR googleSpreadsheetUrl: process.env.GOOGLE_SHEET_URL,
 
       // Path to Google credentials file (service account JSON file): Replace with the file path or use an environment variable.
       // googleKeyFilePath: 'googleCredentials.json' OR googleKeyFilePath: process.env.GOOGLE_KEY_FILE_PATH,