@salesforcedevs/sfdocs-e2e 0.6.134-cache-test-2 → 1.0.0-alpha.0

package/README.md

@@ -1,63 +1,193 @@
-# E2E for Content repo
+# @salesforcedevs/sfdocs-e2e
 
-We can run e2e cases on example-repository
+End-to-end test suite for SFDocs portal pages, built on [WebdriverIO](https://webdriver.io/) + Mocha. It runs headless Chrome tests against a live (or locally served) SFDocs portal and generates Allure reports with video recordings on failure.
 
-Command to run
+This package is **published independently** from the rest of the monorepo. It is not released as part of the standard `yarn release` workflow — see [Publishing](#publishing) below.
 
-```
-yarn test:e2e
+---
+
+## What it tests
+
+Tests are organised into three suites, each targeting a different surface:
+
+| Suite           | Config file                  | Default base URL        | Spec paths                                |
+| --------------- | ---------------------------- | ----------------------- | ----------------------------------------- |
+| `static-portal` | `static-portal-wdio.conf.js` | `http://localhost:3000` | `src/portal/specs/`, `src/shared/specs/`  |
+| `portal`        | `portal-wdio.conf.js`        | `http://localhost:3001` | `src/portal/specs/`, `src/shared/specs/`  |
+| `search`        | `search-wdio.conf.js`        | `http://localhost:3000` | `src/portal/specs/scope.search.*.test.ts` |
+
+**Shared specs** (`src/shared/specs/`) cover UI components that exist on both portal and content-repo pages:
+
+- Anchor headings, banners, breadcrumbs, callout content
+- Code blocks, doc phase badges, dev-center links
+- Error routes, guides, overview pages, page titles
+- Redoc references, references, videos
+
+**Portal specs** (`src/portal/specs/`) cover portal-specific pages:
+
+- `/docs` landing page, `/docs/apis` landing page
+- Media mapper, scoped search (guides and references)
+
+**Content-repo specs** (`src/content-repo/specs/`) cover the content-repository portal:
+
+- Homepage, guide and reference pages, component specifications
+- Nav header, tabset, media mapper, sitemap
+
+---
+
+## Running tests locally
+
+### Prerequisites
+
+- Node.js and Yarn installed
+- Google Chrome installed (ChromeDriver version is auto-detected from your local Chrome installation)
+- A running SFDocs portal at the target base URL
+
+### Run against the static portal (default)
+
+```bash
+# 1. Build and serve the static portal (from the monorepo root or example-portal package)
+yarn build:static:portal
+yarn start:static:portal   # serves on http://localhost:3000
+
+# 2. Run the static-portal suite
+yarn test:e2e:static:portal
 ```
 
-# E2E for Portal
+### Run against the live portal
 
-To run portal e2e test cases, we need portal to run first.
+```bash
+# Portal must be running on http://localhost:3001
+yarn test:e2e:portal
+```
 
-`yarn start:portal`
+### Run scope search tests
 
-Note: This will take a bit time as it will download all the required repositories mentioned in docsportal.config.json
+```bash
+yarn test:scope-search
+```
 
-## How to run test cases
+### Override the base URL
 
-Once the portal is running at localhost:3001, in a separate terminal - run
+Pass the `E2E_BASE_URL` environment variable to point tests at any environment:
 
-`yarn test:e2e:portal`
+```bash
+E2E_BASE_URL=https://staging.example.com yarn test:e2e:static:portal
+```
 
-This will run the test cases as needed.
+---
 
-### Browser compatibility test
+## Using as a CLI in external projects
 
-in doc-framework-monorepo/packages/e2e/portal-wdio-conf.js
+This package ships a `sfdocs-e2e` binary so consuming projects can run the suite without cloning this repo.
 
-uncomment the below lines
+### Install
 
+```bash
+npm install --save-dev @salesforcedevs/sfdocs-e2e
+# or
+yarn add --dev @salesforcedevs/sfdocs-e2e
 ```
-    capabilities: [
-        // SFDOCs team: For chrome only. If we want debug check the above statement
-        defaultCapabilities[0],
-        {
-             browserName: 'firefox'
-        }
-    ],
+
+### Run
+
+```bash
+# Defaults: static-portal config, http://localhost:3000
+npx sfdocs-e2e
+
+# Custom base URL
+npx sfdocs-e2e --baseUrl http://localhost:8080
+
+# Choose a config suite
+npx sfdocs-e2e --config portal
+npx sfdocs-e2e --config static-portal
+npx sfdocs-e2e --config search
+
+# Help
+npx sfdocs-e2e --help
 ```
 
-### If you want to run with production URl
+### Environment variables
+
+| Variable                | Description                                                                       |
+| ----------------------- | --------------------------------------------------------------------------------- |
+| `E2E_BASE_URL`          | Base URL of the site under test (overridden by `--baseUrl`)                       |
+| `CHROME_DRIVER_VERSION` | Pin a specific ChromeDriver version (auto-detected locally; set explicitly in CI) |
+
+---
 
-in doc-framework-monorepo/packages/e2e/portal-wdio-conf.js
+## Test results and reports
+
+Results are written to `_results_/` inside the package directory:
+
+```
+_results_/
+  static-portal/
+    allure-raw/        # Allure XML + video attachments
+    videos/            # MP4 recordings of failed tests
+    wdio-*.log         # Browser driver logs
+```
 
-change the `baseUrl` property as needed. For private space apps (as we need TMP auth) - we need to pass
-user pwd as below.
+To generate and open an Allure HTML report:
 
+```bash
+npx allure generate _results_/static-portal/allure-raw -o _results_/static-portal/allure-report --clean
+npx allure open _results_/static-portal/allure-report
 ```
-    //baseUrl:"https://beta:cloudwalker@beta.developer.salesforce.com",
+
+---
+
+## Publishing
+
+This package is **excluded from the monorepo's standard release script** (`scripts/release_npm.sh`) because it is an independent test utility with its own release cadence.
+
+### When to publish
+
+Publish a new version when:
+
+- New test suites or specs are added
+- The CLI runner (`bin/run-e2e.js`) is updated
+- WebdriverIO or other test dependencies are upgraded
+- Config files are changed in a way that affects consumers
+
+### How to publish
+
+Always validate with an alpha release first, then promote to stable.
+
+**1. Publish an alpha (for testing)**
+
+```bash
+cd packages/e2e
+yarn publish --tag alpha --new-version 1.0.0-alpha.0
 ```
 
-### What if you want allure reports
+The `alpha` dist-tag means `npm install @salesforcedevs/sfdocs-e2e` will **not** resolve this version by default — consumers must opt in explicitly:
 
-After that just run the below command
+```bash
+# Install latest alpha
+yarn add --dev @salesforcedevs/sfdocs-e2e@alpha
 
+# Or pin to a specific alpha version
+yarn add --dev @salesforcedevs/sfdocs-e2e@1.0.0-alpha.0
 ```
-allure generate allure generate packages/e2e/_results_/allure-raw  --clean && allure open --clean && allure open
+
+Iterate on alphas as needed (`1.0.0-alpha.1`, `1.0.0-alpha.2`, ...) until the release is validated.
+
+**2. Promote to stable**
+
+```bash
+yarn publish --tag latest --new-version 1.0.0
 ```
 
-Note: If allure is not available in your PC, it may throw error.
-Please make sure either adding allure globally or run it from node_modules.
+**3. Future releases — bump and publish**
+
+```bash
+# Bug fix
+yarn publish --tag latest --new-version 1.0.1
+
+# New feature
+yarn publish --tag latest --new-version 1.1.0
+
+# Breaking change
+yarn publish --tag latest --new-version 2.0.0
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/sfdocs-e2e",
-  "version": "0.6.134-cache-test-2",
+  "version": "1.0.0-alpha.0",
   "description": "E2E test suite for SFDocs static portal pages (SSG)",
   "license": "ISC",
   "bin": {
@@ -35,6 +35,5 @@
   },
   "devDependencies": {
     "@types/mocha": "^10.0.1"
-  },
-  "gitHead": "5c846e08135126b2e8fdcf6d752f97eea13fbbae"
+  }
 }