WIP: Mdbook

.github/workflows/mdbook.yml

@@ -0,0 +1,38 @@
+name: Deploy
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch 
+      pages: write  # To push to a GitHub Pages site
+      id-token: write # To update the deployment status
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install latest mdbook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir mdbook
+          curl -sSL $url | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+      - name: Build Book
+        run: |
+          cd docs/sdk-manual
+          mdbook build
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: 'book'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -9,4 +9,5 @@ react-unit-tester/.cache
 js-wdio-mobile/evinced-reports
 evinced-dot-net/sdk
 evinced-dot-net/bin
-playwright-bdd/evinced-reports
+playwright-bdd/evinced-reports
+docs/sdk-manual/book/

docs/sdk-manual/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Max Dobeck"]
+language = "en"
+src = "src"
+title = "Evinced SDK Manual"
+description = "Manual for using and deploying Evinced SDKs. Mobile and Web."

docs/sdk-manual/src/SUMMARY.md

@@ -0,0 +1,38 @@
+# Summary
+[Evinced SDKs - Intro](./evinced_sdks_intro.md)
+- [Obtaining Evinced](./propogation.md)
+- [Authentication](./auth.md)
+
+# Scanning
+- [Continuous Mode - Web](./cont_mode/cont_intro.md)
+    - [Playwright JS](./cont_mode/playwright_js.md)
+    - [WebdriverIO Web](./cont_mode/wdio_web.md)
+    - [Cypress](./cont_mode/cypress.md)
+    - [Java Selenium](./cont_mode/java_selenium.md)
+    - [Cucumber BDD](./cont_mode/bdd.md)
+- [Continuous Mode - Mobile](./cont_mode/mobile.md)
+    - [Android Espresso](./cont_mode/espresso.md)
+    - [iOS XCUI](./cont_mode/xcui.md)
+    - [WebdriverIO Mobile](./cont_mode/wdio_mobile.md)
+    - [Appium](./cont_mode/appium.md)
+- [Analyze](./analyze_mode.md)
+
+# Reporting
+- [Anatomy of the Evinced Report](./the-report.md)
+    - [Aggregrated Reporting](./aggr_reporting.md)
+    - [Filtering](./filtering_reports.md)
+
+# Validations
+- [Validations](./validations/validations_intro.md)
+    - [Axe](./validations/axe.md)
+    - [Skip Validations](./validations/skip.md)
+
+# Reference
+- [Continuos Integration](./continuous_integration.md)
+- [Config](./config/additional_features.md)
+    - [evConfig File](./config/evConfig.md)
+    - [Skip Validations](./config/skip_validations.md)
+    - [Toggles](./config/toggles.md)
+    - [Upload to Platform](./config/upload_to_platform.md)
+# Contributing
+- [For Authors](./contributing.md)

docs/sdk-manual/src/aggr_reporting.md

@@ -0,0 +1 @@
+# Aggregrated Reporting

docs/sdk-manual/src/analyze_mode.md

@@ -0,0 +1,10 @@
+# Analyze
+
+## Playwright JS
+
+The `evAnalyze` method provides a simple way to scan a single page for accessibility issues. This is useful for quick assessments or when you need to analyze specific page states.
+
+js-playwright/tests/evAnalyze.spec.js
+```javascript
+{{#include ../../../js-playwright/tests/evAnalyze.spec.js:5:12}}
+```

docs/sdk-manual/src/auth.md

@@ -0,0 +1,72 @@
+# Authentication
+Evinced SDKs will always require a **USER ID** and a **SECRET** of some kind. A **SECRET** could be an API key obtained from <https://hub.evinced.com> or a JSON Web Token(JWT) provided by an evinced employee.
+
+>If you are using a API key typically this is referred to as a `secret` in the `setCredentials()` method.
+>
+>If you are using a JSON Web Token then this is referred to as a `token` in the `setOfflineCredentials()` method, typically used for offline authentication where access to the public internet is restricted. 
+
+Use your local Environment variables or whatever current secret management system your team must conform to.
+
+## NodeJS Environment (JavaScript SDKs)
+### Playwright JS/TS
+[js-playwright/global.settings.js](https://github.com/GetEvinced/examples/tree/main/js-playwright/global.settings.js)
+```javascript
+{{#include ../../../js-playwright/global.settings.js:3:15}}
+```
+
+### Cypress
+[js-cypress/cypress/support/e2e.js](https://github.com/GetEvinced/examples/tree/main/js-cypress/cypress/support/e2e.js)
+```javascript
+// js-cypress/cypress/support/e2e.js
+{{#include ../../../js-cypress/cypress/support/e2e.js:27:30}}
+```
+
+### Testcafe
+[js-testcafe-web/.testcaferc.js](https://github.com/GetEvinced/examples/tree/main/js-testcafe-web/.testcaferc.js)
+```javascript
+// js-testcafe-web/.testcaferc.js
+{{#include ../../../js-testcafe-web/.testcaferc.js:17:35}}
+```
+
+### WDIO Web & Mobile
+[js-wdio-web/wdio.conf.js](https://github.com/GetEvinced/examples/tree/main/js-wdio-web/wdio.conf.js)
+```javascript
+// WEB js-wdio-web/wdio.conf.js
+{{#include ../../../js-wdio-web/wdio.conf.js:5:23}}
+```
+
+[js-wdio-mobile/test/specs/mobileTest.js](https://github.com/GetEvinced/examples/tree/main/js-wdio-mobile/test/specs/mobileTest.js)
+```javascript
+// MOBILE js-wdio-mobile/test/specs/mobileTest.js
+{{#include ../../../js-wdio-mobile/test/specs/mobileTest.js:8:13}}
+```
+
+### Unit Tester
+[nextjs-react-unit-tester/jest.setup.js](https://github.com/GetEvinced/examples/tree/main/nextjs-react-unit-tester/jest.setup.js)
+```javascript
+// nextjs-react-unit-tester/jest.setup.js
+{{#include ../../../nextjs-react-unit-tester/jest.setup.js}}
+```
+
+## Java
+### Selenium
+[java-selenium-web/src/test/java/com/krissutherland/EvincedSetupTest.java](https://github.com/GetEvinced/examples/tree/main/java-selenium-web/src/test/java/com/krissutherland/EvincedSetupTest.java)
+```java
+// java-selenium-web/src/test/java/com/krissutherland/EvincedSetupTest.java
+{{#include ../../../java-selenium-web/src/test/java/com/krissutherland/EvincedSetupTest.java:33}}
+```
+
+
+{{#include ./snippets/official_docs.md}}
+
+
+# Offline Authentication
+If there is a strict network or blocked calls then try using Offline Authentication and disabling any outbound Evinced network calls.
+
+## JavaScript frameworks
+
+```javascript
+await setOfflineCredentials({
+            serviceId: process.env.EVINCED_SERVICE_ID,
+            token: process.env.EVINCED_AUTH_TOKEN,
+        });```

docs/sdk-manual/src/config/additional_features.md

@@ -0,0 +1 @@
+# Config

docs/sdk-manual/src/config/evConfig.md

@@ -0,0 +1 @@
+# evConfig File

docs/sdk-manual/src/config/skip_validations.md

@@ -0,0 +1 @@
+# Skip Validations

docs/sdk-manual/src/config/toggles.md

@@ -0,0 +1 @@
+# Toggles

docs/sdk-manual/src/config/upload_to_platform.md

@@ -0,0 +1 @@
+# Upload to Platform

docs/sdk-manual/src/cont_mode/appium.md

@@ -0,0 +1 @@
+# Appium

docs/sdk-manual/src/cont_mode/bdd.md

@@ -0,0 +1 @@
+# Cucumber BDD

docs/sdk-manual/src/cont_mode/cont_intro.md

@@ -0,0 +1,23 @@
+# Continuous Mode
+Continuous Mode constantly scans at the start point when it is invoked. Then at the end point, when it is disabled it returns a Report. Typically this Report object is saved as an HTML, CSV, or JSON file.
+
+![evstop evstart lifecycle drawing](../assets/evstart-evstop-lifecycle.png)
+
+While the Scanning is enabled, events like clicks or keyboard input will be captured and automatically trigger a re-scan. Lets say for for example you have a date picker and when clicked the new date triggers several updates across the components on the page.
+
+Without continous mode you'd have to know in your tests where this UI change happens, add a method calling for an a11y scan. This is time intensive and error prone.
+
+With Evinced's Continuous Mode you do not have to manually invoke anything! Turn it on at the beginning of the test then turn it off at the end of the test and collect your report. In this scenario the clicking of the date picker triggeres a rescan and any highlighting, new content, changes of colors, etc is automatically captured.
+
+![Continuous mode drawn example](../assets/cont-mode-example.png)
+
+## Enabling the Scan
+### Web
+Typically the method name is `evStart()`. This is the point in time where the Evinced SDK will start "watching" the browser for changes.
+
+## Ending the Continuous Scanning
+
+### Web
+`evStop()` is the method that will halt the scanning and immediately attempt to return a Report. This report is typically best thought of as an array of Accessibility Issues found during the test. Each Issue consists of IDs, Criticality, and other useful pieces of information. Read more in the page about [Reporting](../the-report.md).
+
+{{#include ../snippets/official_docs.md}}

docs/sdk-manual/src/cont_mode/cypress.md

@@ -0,0 +1 @@
+# Cypress

docs/sdk-manual/src/cont_mode/espresso.md

@@ -0,0 +1 @@
+# Android Espresso

docs/sdk-manual/src/cont_mode/java_selenium.md

@@ -0,0 +1 @@
+# Java Selenium

docs/sdk-manual/src/cont_mode/mobile.md

@@ -0,0 +1,66 @@
+# Continuous Mode - Mobile
+
+Continuous Mode for mobile applications constantly scans from the start point when invoked. At the end point, when disabled, it returns a JSON and HTML Report containing accessibility issues found during the test session. 
+
+Evinced uses screenshots as well as the view hierararchy at the time a tap, button press, or some other event occurs. Any accessibility issues found should go into the Issues list and then finally the Report when `reportStored()` or `report()` is called.
+
+## Using Mobile Continuous Mode
+
+### Android Espresso
+Use `startAnalyze()` & `stopAnalyze()` to begin continuous accessibility monitoring:
+
+```java
+// Start continuous monitoring
+evincedEngine.startAnalyze();
+// Stop continuous monitoring
+evincedEngine.stopAnalyze();
+```
+
+### iOS XCUITest
+Use `EvincedEngine.startAnalyze()` and `stopAnalyze()`:
+
+```swift
+// Start continuous analysis
+EvincedEngine.startAnalyze()
+// Stop continuous analysis
+EvincedEngine.stopAnalyze()
+```
+
+### Appium Java
+Use the similar `startAnalyze()` and `stopAnalyze()` method to start watching the test:
+
+```java
+    evincedAppiumSdk.startAnalyze();
+    evincedAppiumSdk.stopAnalyze();
+```
+
+## Generating Reports
+By default HTML and JSON reports are produced whenver the reportStored method is called.
+
+### Android Espresso
+Use `reportStored()` method to generate reports from collected data:
+
+```java
+// Generate reports for all stored accessibility data
+evincedEngine.reportStored();
+```
+
+### iOS XCUITest
+Use `reportStored()` method to generate reports from collected data:
+
+```swift
+// Generate reports for all stored accessibility data
+try EvincedEngine.reportStored(assert: false)
+```
+
+### Appium Java
+Use `report()` method for immediate accessibility analysis:
+
+```java
+// Run analysis and get the accessibility report
+Report report = evincedSdk.report();
+```
+
+The `reportStored()` method processes all accessibility data collected during the continuous scanning session and generates comprehensive reports.
+
+{{#include ../snippets/official_docs.md}}

docs/sdk-manual/src/cont_mode/playwright_js.md

@@ -0,0 +1,23 @@
+# Playwright JS
+
+## Simple evStart/EvStop
+Use this to get up and running quickly and confirm that Reports are generated as expected. Because this relies on editing each file, spec, or test directly its not a scaleable approach.
+
+[js-playwright/tests/evStartStop.spec.js](https://github.com/GetEvinced/examples/tree/main/js-playwright/tests/evStartStop.spec.js)
+```javascript
+{{#include ../../../../js-playwright/tests/evStartStop.spec.js:5:25}}
+```
+
+## With Hooks: Normal Starting Point
+This is done Per Test or .spec file typically. Normally this is a safe entry point to creating a small suite of a11y tests that will run with Evinced.
+
+[js-playwright/tests/evComplicated.spec.js](https://github.com/GetEvinced/examples/tree/main/js-playwright/tests/evComplicated.spec.js)
+```javascript
+{{#include ../../../../js-playwright/tests/evComplicated.spec.js:9:32}}
+```
+
+## With Fixtures
+[js-playwright/tests/evFixture.spec.js](https://github.com/GetEvinced/examples/tree/main/js-playwright/tests/evFixture.spec.js)
+```javascript
+{{#include ../../../../js-playwright/tests/evFixture.spec.js:1:3}}
+```

docs/sdk-manual/src/cont_mode/wdio_mobile.md

@@ -0,0 +1 @@
+# WebdriverIO Mobile

docs/sdk-manual/src/cont_mode/wdio_web.md

@@ -0,0 +1 @@
+# WebdriverIO Web

docs/sdk-manual/src/cont_mode/xcui.md

@@ -0,0 +1 @@
+# iOS XCUI

docs/sdk-manual/src/continuous_integration.md

@@ -0,0 +1 @@
+# CICD

docs/sdk-manual/src/contributing.md

@@ -0,0 +1,30 @@
+# Contributing
+Mdbook guide in mdbook: https://rust-lang.github.io/mdBook/index.html. 
+
+## Structure
+All written work is in the /src file. For a high level structure see SUMMARY.md. These are the capters. 
+
+## To build and open the book in a browser
+
+`mdbook build ./docs/sdk-manual --open` 
+
+
+
+## If actively developing use watch or serve
+`mdbook serve ./docs/sdk-manual --open` and this will open it in browser. 
+
+`mdbook watch ./docs/sdk-manual --open`
+
+Changes will be watched for but you may have to manually reload. You shouldn't but you may have to. If you want changes to happen quickly then use serve.
+
+## Code snippets
+Use backticks and the language name.
+To include a specific file use the {{# include ../path/to/file}}
+```javascript
+// js-playwright/global.settings.js
+{{#include ../../../js-playwright/global.settings.js:3:15}}
+```
+
+## Merging in git
+rebase?
+https://www.youtube.com/watch?v=DkWDHzmMvyg

docs/sdk-manual/src/evinced_sdks_intro.md

@@ -0,0 +1,22 @@
+# Chapter 1
+Official Development Docs: <https://developer.evinced.com/>
+
+All code examples: <https://github.com/GetEvinced/examples/>
+
+Evinced Software Development Kits(SDKs) will attempt to scan the screen for accessibility issues. A screen is what is available during a test, including the full Document Object Model(DOM) or Accessibility Tree. This could be a mobile app or a browser. In laymans terms it will scan what is available either one time, or continusly when an event[^event] fires.
+
+After the testing/scanning phase is completed a report is produced in a chosen format, typically HTML. This report AKA Artifact is self-contained and includes quick-fixes, in-depth details, and screenshots of the various accessibility issues found. 
+
+Once a report is generated remediation is pursued either by logging the report as a development issue or by quickly performing the suggested changes. Manual confirmation and testing of any fixes is typcially pursued with the Mobile Flow Analyzer (Desktop App) or the Web Flow Analyzer (Chrome Extension).
+
+This guide will contain code an explanation and code examples for:
+- authenticating against Evinced servers
+- setting up Continuous mode 
+- calling a single scan of the current state: Analyze mode
+- Miscellanous questions related to edge cases or larger scale usage
+
+```javascript
+{{#include ../../../js-playwright/tests/evComplicated.spec.js:9:26}}
+```
+
+[^event]: A click, tap, keypress, any sort of interaction with the web page or mobile app.

docs/sdk-manual/src/filtering_reports.md

@@ -0,0 +1 @@
+# Filtering