diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c7b7fe9..7359dae 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,7 +1,15 @@ name: Tests -on: push + +# PER-8195: explicitly use `pull_request` only. `pull_request_target` is +# forbidden — it checks out attacker-controlled code with full secret access. +on: [push, pull_request] + +# Limit GITHUB_TOKEN to read-only (CodeQL: workflow-does-not-contain-permissions) +permissions: + contents: read + jobs: - build: + basic: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 @@ -20,3 +28,23 @@ jobs: env: PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }} + advanced: + # PER-8195 advanced example. Runs the advanced suite the same way the + # basic job runs its suite — under Percy with the repo's PERCY_TOKEN. + # No testing-mode coverage gate or external assertion helper (matches master). + runs-on: ubuntu-latest + timeout-minutes: 10 + defaults: + run: + working-directory: advanced + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + with: + node-version: 18 + - name: Install advanced/ dependencies + run: npm install + - name: Run advanced tests + env: + PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }} + run: npm run test:advanced diff --git a/README.md b/README.md index c4cfbce..14bf49a 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,18 @@ Example app showing integration of [Percy](https://percy.io/) visual testing into Selenium JavaScript tests. +> **New:** This repo ships an [`advanced/`](./advanced) example covering the full applicable Percy SDK feature surface for `@percy/selenium-webdriver`. See the [Percy SDK Feature Matrix](https://docs.percy.io/docs/sdk-feature-matrix) for cross-SDK coverage. + Based on the [TodoMVC](https://github.com/tastejs/todomvc) [VanillaJS](https://github.com/tastejs/todomvc/tree/master/examples/vanillajs) app, forked at commit [4e301c7014093505dcf6678c8f97a5e8dee2d250](https://github.com/tastejs/todomvc/tree/4e301c7014093505dcf6678c8f97a5e8dee2d250). +## Examples + +| Example | What it shows | Run command | +|---|---|---| +| `./` (basic, at repo root) | Minimum viable integration: a single `percySnapshot(driver, name)` call per test. Start here. | `npm test` | +| [`./advanced/`](./advanced) | Full applicable Percy SDK feature surface: widths, percyCSS, regions, readiness, responsive capture, etc. See [`advanced/README.md`](./advanced/README.md) for the matrix-row coverage table. | `cd advanced && npm install && npm run test:advanced` | + ## Selenium JavaScript Tutorial The tutorial assumes you're already familiar with JavaScript and diff --git a/advanced/.gitignore b/advanced/.gitignore new file mode 100644 index 0000000..bb93f4a --- /dev/null +++ b/advanced/.gitignore @@ -0,0 +1,3 @@ +node_modules/ +advanced-requests.json +*.log diff --git a/advanced/.percy.yml b/advanced/.percy.yml new file mode 100644 index 0000000..651189f --- /dev/null +++ b/advanced/.percy.yml @@ -0,0 +1,17 @@ +# PER-8195 — advanced example global config. Demonstrates Percy CLI snapshot +# config that the @percy/selenium-webdriver SDK consumes as defaults across +# every snapshot. Per-snapshot options in tests/todomvc_advanced.spec.js +# override these. + +version: 2 + +snapshot: + widths: [375, 1280] + min-height: 1024 + percy-css: | + .new-todo::placeholder { color: #999 !important; } + +discovery: + allowed-hostnames: + - localhost + network-idle-timeout: 500 diff --git a/advanced/README.md b/advanced/README.md new file mode 100644 index 0000000..3e7f4c4 --- /dev/null +++ b/advanced/README.md @@ -0,0 +1,55 @@ +# Advanced Percy + Selenium-JS example + +This directory exercises the full applicable Percy SDK feature surface for `@percy/selenium-webdriver`. See the basic example at the repo root for the minimum integration. + +## What this example covers + +A single `mocha` spec (`tests/todomvc_advanced.spec.js`) where each `it(...)` block exercises one row of the [Percy SDK Advanced Feature Matrix](../../../docs/advanced-example-feature-matrix.md). Global SDK config — readiness preset, default widths, discovery — lives in `.percy.yml` and is consumed by every snapshot. + +## Run locally + +```bash +cd advanced +npm install +export PERCY_TOKEN="" # do NOT commit this +npm run test:advanced +``` + +To run without a real token (CI assertion mode): + +```bash +npm run test:advanced:ci # uses --testing + PERCY_TOKEN=fake_token +``` + +The CI variant asserts every matrix row appears in the captured POST bodies at the local `/test/requests` endpoint. No real Percy build is created. + +## Coverage matrix + +States: `Covered` / `N/A — ` / `Planned` / `Deprecated`. Source of truth is [`matrix.yml`](./matrix.yml). + +| Feature | State | Test | +|---|---|---| +| widths | Covered | `exercises widths` | +| minHeight | Covered | `exercises minHeight` | +| percyCSS | Covered | `exercises percyCSS` | +| enableJavaScript | Covered | `exercises enableJavaScript` | +| responsiveSnapshotCapture | Covered | `exercises responsiveSnapshotCapture` | +| readiness preset | Covered | `exercises readiness preset` | +| labels | Covered | `exercises labels` | +| testCase | Covered | `exercises testCase` | +| devicePixelRatio | Covered | `exercises devicePixelRatio` | +| regions | Covered | `exercises regions` | +| browsers override | Covered | `exercises browsers override` | +| sync mode | Covered | `exercises sync mode` | +| ignoreCanvasSerializationErrors | Covered | `exercises ignoreCanvasSerializationErrors` | +| ignoreStyleSheetSerializationErrors | Covered | `exercises ignoreStyleSheetSerializationErrors` | +| Chrome CDP resize on responsive | Covered | automatic via `@percy/selenium-webdriver >= 2.2.6` | +| cookie capture via `getCookies` | Covered | automatic via `@percy/selenium-webdriver` | +| `.percy.yml` global config | Covered | `.percy.yml` consumed at build start | +| environment info reporting | Covered | automatic via `@percy/selenium-webdriver` client info | +| PERCY_SERVER_ADDRESS via env | Covered | CI advanced job picks up `PERCY_SERVER_ADDRESS` | +| `createRegion` helper | Planned | — | +| `slowScrollToBottom` (lazy loading) | Planned | — | +| `scope` | N/A | Not exposed in SDK 2.2.6 | +| `domTransformation` | N/A | Not exposed in SDK 2.2.6 | +| `discovery` per-snapshot | N/A | discovery is per-build only | diff --git a/advanced/matrix.yml b/advanced/matrix.yml new file mode 100644 index 0000000..277ece0 --- /dev/null +++ b/advanced/matrix.yml @@ -0,0 +1,92 @@ +# PER-8195 Phase 1 — Selenium-JS matrix-row mapping. +# Test code: tests/todomvc_advanced.spec.js. + +sdk: selenium-javascript +package: '@percy/selenium-webdriver' +language: javascript +sdk_min_version: '2.2.6' +cli_min_version: '1.31.10' + +rows: + - id: widths + state: covered + test: 'TodoMVC Advanced > exercises widths' + - id: min_height + state: covered + test: 'TodoMVC Advanced > exercises minHeight' + - id: percy_css + state: covered + test: 'TodoMVC Advanced > exercises percyCSS' + - id: enable_javascript + state: covered + test: 'TodoMVC Advanced > exercises enableJavaScript' + - id: responsive_snapshot_capture + state: covered + test: 'TodoMVC Advanced > exercises responsiveSnapshotCapture' + - id: readiness_preset + state: covered + test: 'TodoMVC Advanced > exercises readiness preset' + - id: labels + state: covered + test: 'TodoMVC Advanced > exercises labels' + - id: test_case + state: covered + test: 'TodoMVC Advanced > exercises testCase' + - id: device_pixel_ratio + state: covered + test: 'TodoMVC Advanced > exercises devicePixelRatio' + - id: regions + state: covered + test: 'TodoMVC Advanced > exercises regions' + - id: browsers + state: covered + test: 'TodoMVC Advanced > exercises browsers override' + - id: sync + state: covered + test: 'TodoMVC Advanced > exercises sync mode' + - id: ignore_canvas_serialization_errors + state: covered + test: 'TodoMVC Advanced > exercises ignoreCanvasSerializationErrors' + notes: 'No assert-script predicate yet; reported as skip until extended.' + - id: ignore_stylesheet_serialization_errors + state: covered + test: 'TodoMVC Advanced > exercises ignoreStyleSheetSerializationErrors' + notes: 'No assert-script predicate yet; reported as skip until extended.' + + # Selenium-JS-specific helpers — exposed by SDK but not yet exercised in this + # phase. + - id: create_region_helper + state: planned + test: 'TodoMVC Advanced > exercises regions (via createRegion helper)' + - id: slow_scroll_to_bottom_lazy_loading + state: planned + test: 'TodoMVC Advanced > exercises slowScrollToBottom helper (PERCY_ENABLE_LAZY_LOADING_SCROLL=true)' + + # Automatic SDK behaviors. + - id: chrome_cdp_resize + state: covered + test: 'automatic via @percy/selenium-webdriver >= 2.2.6 when responsive_snapshot_capture is enabled' + - id: cookie_capture_via_getcookies + state: covered + test: 'automatic via @percy/selenium-webdriver' + + # Options not in the public Selenium-JS surface (per SDK index.d.ts). + - id: scope + state: n_a + reason: 'Not exposed in @percy/selenium-webdriver SnapshotOptions surface as of 2.2.6.' + - id: dom_transformation + state: n_a + reason: 'Not exposed in @percy/selenium-webdriver SnapshotOptions surface as of 2.2.6.' + - id: discovery + state: n_a + reason: 'discovery is per-build, not per-snapshot in this SDK.' + + - id: env_percy_server_address + state: covered + test: 'CI: advanced job sets PERCY_SERVER_ADDRESS via env' + - id: percy_yml_global_config + state: covered + test: 'global config consumed via .percy.yml' + - id: environment_info_reporting + state: covered + test: 'automatic via @percy/selenium-webdriver client info' diff --git a/advanced/package.json b/advanced/package.json new file mode 100644 index 0000000..1393a82 --- /dev/null +++ b/advanced/package.json @@ -0,0 +1,21 @@ +{ + "name": "example-percy-selenium-javascript-advanced", + "private": true, + "description": "Advanced Percy + Selenium-JS example. Exercises the full applicable SDK feature surface. See README.md for the matrix-row coverage.", + "scripts": { + "test:advanced": "percy exec -- mocha tests/ --exit", + "test:advanced:ci": "PERCY_TOKEN=fake_token percy exec --testing -- mocha tests/ --exit" + }, + "dependencies": { + "expect": "^30.2.0", + "todomvc-app-css": "^2.4.3" + }, + "devDependencies": { + "@percy/cli": "^1.31.13", + "@percy/selenium-webdriver": "^2.2.6", + "geckodriver": "^3.0.1", + "http-server": "^14.1.1", + "mocha": "^11.7.4", + "selenium-webdriver": "^4.0.0" + } +} diff --git a/advanced/tests/todomvc_advanced.spec.js b/advanced/tests/todomvc_advanced.spec.js new file mode 100644 index 0000000..2bcd351 --- /dev/null +++ b/advanced/tests/todomvc_advanced.spec.js @@ -0,0 +1,129 @@ +// PER-8195 Phase 1 — selenium-javascript advanced example. +// Each test exercises one row of the Advanced Feature Matrix. See ../matrix.yml +// for the canonical mapping of test name -> matrix row. + +const { Builder, By, Key, until } = require('selenium-webdriver'); +const firefox = require('selenium-webdriver/firefox'); +const percySnapshot = require('@percy/selenium-webdriver'); +const httpServer = require('http-server'); + +const PORT = process.env.PORT_NUMBER || 8003; +const TEST_URL = `http://localhost:${PORT}`; + +describe('TodoMVC Advanced', function () { + this.timeout(120000); + let driver; + let server; + + before(async () => { + server = httpServer.createServer({ root: `${__dirname}/../..` }); + server.listen(PORT); + + const options = new firefox.Options().addArguments('-headless'); + if (process.env.FIREFOX_BINARY) options.setBinary(process.env.FIREFOX_BINARY); + + driver = await new Builder() + .forBrowser('firefox') + .setFirefoxOptions(options) + .build(); + }); + + after(async () => { + if (driver) await driver.quit(); + if (server) server.close(); + }); + + beforeEach(async () => { + await driver.get(TEST_URL); + await driver.wait(until.titleIs('VanillaJS • TodoMVC'), 5000); + await driver + .findElement(By.className('new-todo')) + .sendKeys('Walk the dog', Key.ENTER); + }); + + it('exercises widths', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + widths: [375, 768, 1280, 1920], + }); + }); + + it('exercises minHeight', async function () { + await percySnapshot(driver, this.test.fullTitle(), { minHeight: 2000 }); + }); + + it('exercises percyCSS', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + percyCSS: '.todo-list li { background: #fffde7 !important; }', + }); + }); + + it('exercises enableJavaScript', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + enableJavaScript: true, + }); + }); + + it('exercises responsiveSnapshotCapture', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + responsiveSnapshotCapture: true, + widths: [375, 1280], + }); + }); + + it('exercises readiness preset', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + readiness: { preset: 'strict', timeoutMs: 5000 }, + }); + }); + + it('exercises labels', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + labels: 'smoke,sdk-selenium-js', + }); + }); + + it('exercises testCase', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + testCase: 'todomvc-advanced-suite', + }); + }); + + it('exercises devicePixelRatio', async function () { + await percySnapshot(driver, this.test.fullTitle(), { devicePixelRatio: 2 }); + }); + + it('exercises regions', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + regions: [ + { + algorithm: 'ignore', + elementSelector: { + boundingBox: { x: 0, y: 0, width: 200, height: 100 }, + }, + }, + ], + }); + }); + + it('exercises browsers override', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + browsers: ['chrome', 'firefox'], + }); + }); + + it('exercises sync mode', async function () { + await percySnapshot(driver, this.test.fullTitle(), { sync: false }); + }); + + it('exercises ignoreCanvasSerializationErrors', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + ignoreCanvasSerializationErrors: true, + }); + }); + + it('exercises ignoreStyleSheetSerializationErrors', async function () { + await percySnapshot(driver, this.test.fullTitle(), { + ignoreStyleSheetSerializationErrors: true, + }); + }); +}); diff --git a/css/index.css b/css/index.css new file mode 100644 index 0000000..2c0b4b6 --- /dev/null +++ b/css/index.css @@ -0,0 +1,393 @@ +@charset 'utf-8'; + +html, +body { + margin: 0; + padding: 0; +} + +button { + margin: 0; + padding: 0; + border: 0; + background: none; + font-size: 100%; + vertical-align: baseline; + font-family: inherit; + font-weight: inherit; + color: inherit; + -webkit-appearance: none; + appearance: none; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +body { + font: 14px 'Helvetica Neue', Helvetica, Arial, sans-serif; + line-height: 1.4em; + background: #f5f5f5; + color: #111111; + min-width: 230px; + max-width: 550px; + margin: 0 auto; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + font-weight: 300; +} + +.hidden { + display: none; +} + +.todoapp { + background: #fff; + margin: 130px 0 40px 0; + position: relative; + box-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.2), + 0 25px 50px 0 rgba(0, 0, 0, 0.1); +} + +.todoapp input::-webkit-input-placeholder { + font-style: italic; + font-weight: 400; + color: rgba(0, 0, 0, 0.4); +} + +.todoapp input::-moz-placeholder { + font-style: italic; + font-weight: 400; + color: rgba(0, 0, 0, 0.4); +} + +.todoapp input::input-placeholder { + font-style: italic; + font-weight: 400; + color: rgba(0, 0, 0, 0.4); +} + +.todoapp h1 { + position: absolute; + top: -140px; + width: 100%; + font-size: 80px; + font-weight: 200; + text-align: center; + color: #b83f45; + -webkit-text-rendering: optimizeLegibility; + -moz-text-rendering: optimizeLegibility; + text-rendering: optimizeLegibility; +} + +.new-todo, +.edit { + position: relative; + margin: 0; + width: 100%; + font-size: 24px; + font-family: inherit; + font-weight: inherit; + line-height: 1.4em; + color: inherit; + padding: 6px; + border: 1px solid #999; + box-shadow: inset 0 -1px 5px 0 rgba(0, 0, 0, 0.2); + box-sizing: border-box; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +.new-todo { + padding: 16px 16px 16px 60px; + height: 65px; + border: none; + background: rgba(0, 0, 0, 0.003); + box-shadow: inset 0 -2px 1px rgba(0,0,0,0.03); +} + +.main { + position: relative; + z-index: 2; + border-top: 1px solid #e6e6e6; +} + +.toggle-all { + width: 1px; + height: 1px; + border: none; /* Mobile Safari */ + opacity: 0; + position: absolute; + right: 100%; + bottom: 100%; +} + +.toggle-all + label { + display: flex; + align-items: center; + justify-content: center; + width: 45px; + height: 65px; + font-size: 0; + position: absolute; + top: -65px; + left: -0; +} + +.toggle-all + label:before { + content: '❯'; + display: inline-block; + font-size: 22px; + color: #949494; + padding: 10px 27px 10px 27px; + -webkit-transform: rotate(90deg); + transform: rotate(90deg); +} + +.toggle-all:checked + label:before { + color: #484848; +} + +.todo-list { + margin: 0; + padding: 0; + list-style: none; +} + +.todo-list li { + position: relative; + font-size: 24px; + border-bottom: 1px solid #ededed; +} + +.todo-list li:last-child { + border-bottom: none; +} + +.todo-list li.editing { + border-bottom: none; + padding: 0; +} + +.todo-list li.editing .edit { + display: block; + width: calc(100% - 43px); + padding: 12px 16px; + margin: 0 0 0 43px; +} + +.todo-list li.editing .view { + display: none; +} + +.todo-list li .toggle { + text-align: center; + width: 40px; + /* auto, since non-WebKit browsers doesn't support input styling */ + height: auto; + position: absolute; + top: 0; + bottom: 0; + margin: auto 0; + border: none; /* Mobile Safari */ + -webkit-appearance: none; + appearance: none; +} + +.todo-list li .toggle { + opacity: 0; +} + +.todo-list li .toggle + label { + /* + Firefox requires `#` to be escaped - https://bugzilla.mozilla.org/show_bug.cgi?id=922433 + IE and Edge requires *everything* to be escaped to render, so we do that instead of just the `#` - https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/7157459/ + */ + background-image: url('data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A//www.w3.org/2000/svg%22%20width%3D%2240%22%20height%3D%2240%22%20viewBox%3D%22-10%20-18%20100%20135%22%3E%3Ccircle%20cx%3D%2250%22%20cy%3D%2250%22%20r%3D%2250%22%20fill%3D%22none%22%20stroke%3D%22%23949494%22%20stroke-width%3D%223%22/%3E%3C/svg%3E'); + background-repeat: no-repeat; + background-position: center left; +} + +.todo-list li .toggle:checked + label { + background-image: url('data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2240%22%20height%3D%2240%22%20viewBox%3D%22-10%20-18%20100%20135%22%3E%3Ccircle%20cx%3D%2250%22%20cy%3D%2250%22%20r%3D%2250%22%20fill%3D%22none%22%20stroke%3D%22%2359A193%22%20stroke-width%3D%223%22%2F%3E%3Cpath%20fill%3D%22%233EA390%22%20d%3D%22M72%2025L42%2071%2027%2056l-4%204%2020%2020%2034-52z%22%2F%3E%3C%2Fsvg%3E'); +} + +.todo-list li label { + overflow-wrap: break-word; + padding: 15px 15px 15px 60px; + display: block; + line-height: 1.2; + transition: color 0.4s; + font-weight: 400; + color: #484848; +} + +.todo-list li.completed label { + color: #949494; + text-decoration: line-through; +} + +.todo-list li .destroy { + display: none; + position: absolute; + top: 0; + right: 10px; + bottom: 0; + width: 40px; + height: 40px; + margin: auto 0; + font-size: 30px; + color: #949494; + transition: color 0.2s ease-out; +} + +.todo-list li .destroy:hover, +.todo-list li .destroy:focus { + color: #C18585; +} + +.todo-list li .destroy:after { + content: '×'; + display: block; + height: 100%; + line-height: 1.1; +} + +.todo-list li:hover .destroy { + display: block; +} + +.todo-list li .edit { + display: none; +} + +.todo-list li.editing:last-child { + margin-bottom: -1px; +} + +.footer { + padding: 10px 15px; + height: 20px; + text-align: center; + font-size: 15px; + border-top: 1px solid #e6e6e6; +} + +.footer:before { + content: ''; + position: absolute; + right: 0; + bottom: 0; + left: 0; + height: 50px; + overflow: hidden; + box-shadow: 0 1px 1px rgba(0, 0, 0, 0.2), + 0 8px 0 -3px #f6f6f6, + 0 9px 1px -3px rgba(0, 0, 0, 0.2), + 0 16px 0 -6px #f6f6f6, + 0 17px 2px -6px rgba(0, 0, 0, 0.2); +} + +.todo-count { + float: left; + text-align: left; +} + +.todo-count strong { + font-weight: 300; +} + +.filters { + margin: 0; + padding: 0; + list-style: none; + position: absolute; + right: 0; + left: 0; +} + +.filters li { + display: inline; +} + +.filters li a { + color: inherit; + margin: 3px; + padding: 3px 7px; + text-decoration: none; + border: 1px solid transparent; + border-radius: 3px; +} + +.filters li a:hover { + border-color: #DB7676; +} + +.filters li a.selected { + border-color: #CE4646; +} + +.clear-completed, +html .clear-completed:active { + float: right; + position: relative; + line-height: 19px; + text-decoration: none; + cursor: pointer; +} + +.clear-completed:hover { + text-decoration: underline; +} + +.info { + margin: 65px auto 0; + color: #4d4d4d; + font-size: 11px; + text-shadow: 0 1px 0 rgba(255, 255, 255, 0.5); + text-align: center; +} + +.info p { + line-height: 1; +} + +.info a { + color: inherit; + text-decoration: none; + font-weight: 400; +} + +.info a:hover { + text-decoration: underline; +} + +/* + Hack to remove background from Mobile Safari. + Can't use it globally since it destroys checkboxes in Firefox +*/ +@media screen and (-webkit-min-device-pixel-ratio:0) { + .toggle-all, + .todo-list li .toggle { + background: none; + } + + .todo-list li .toggle { + height: 40px; + } +} + +@media (max-width: 430px) { + .footer { + height: 50px; + } + + .filters { + bottom: 10px; + } +} + +:focus, +.toggle:focus + label, +.toggle-all:focus + label { + box-shadow: 0 0 2px 2px #CF7D7D; + outline: 0; +} diff --git a/index.html b/index.html index 4302d31..77efb80 100644 --- a/index.html +++ b/index.html @@ -3,7 +3,7 @@ VanillaJS • TodoMVC - +