feat(advanced): PER-8195 — advanced example for io.percy:percy-java-selenium

.github/workflows/test.yml

@@ -1,8 +1,16 @@
-name: Test
-on: push
+name: Tests
+
+# 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:
-  test:
-    name: Test
+  basic:
+    name: basic
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -19,3 +27,29 @@ jobs:
       - run: make test
         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).
+    name: advanced
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: advanced
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: 17
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - name: Install advanced/ dependencies
+        run: make install
+      - name: Run advanced tests
+        env:
+          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
+        run: make test-advanced

README.md

@@ -1,10 +1,18 @@
 # example-percy-java-selenium
 Example app used by the [Percy Java Selenium tutorial](https://docs.percy.io/docs/java-selenium-testing-tutorial) demonstrating Percy's Java Selenium integration.
 
+> **New:** This repo ships an [`advanced/`](./advanced) example covering the full applicable Percy SDK feature surface for `io.percy:percy-java-selenium`. 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: `percy.snapshot(name)` plus widths and minHeight typed overloads. Start here. | `make test` |
+| [`./advanced/`](./advanced) | Full applicable Percy SDK feature surface using both typed overloads and the `Map<String, Object> options` overload (responsive, readiness, labels, regions, devicePixelRatio, browsers, sync). See [`advanced/README.md`](./advanced/README.md) for the matrix-row coverage table. | `cd advanced && make test` |
 
 ## Java Selenium Tutorial
 

advanced/.gitignore

@@ -0,0 +1,5 @@
+target/
+*.class
+advanced-requests.json
+node_modules/
+*.log

advanced/.percy.yml

@@ -0,0 +1,15 @@
+# PER-8195 — advanced example global config for io.percy:percy-java-selenium.
+# Per-snapshot Map options in AdvancedTest 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

advanced/Makefile

@@ -0,0 +1,23 @@
+NPM=node_modules/.bin
+
+$(NPM):
+	npm install --no-save @percy/cli@^1.31.13
+
+.PHONY: install clean test test-advanced test-advanced-ci
+
+install: $(NPM)
+
+clean:
+	rm -rf target node_modules advanced-requests.json
+
+# Local run against a real PERCY_TOKEN.
+test test-advanced: install
+	$(NPM)/percy exec -- mvn test
+
+# CI run in --testing mode + capture requests file.
+test-advanced-ci: install
+	PERCY_TOKEN=fake_token $(NPM)/percy exec --testing -- bash -c '\
+		mvn test; \
+		ec=$$?; \
+		curl -fsS http://localhost:5338/test/requests > advanced-requests.json || true; \
+		exit $$ec'

advanced/README.md

@@ -0,0 +1,53 @@
+# Advanced Percy + Selenium-Java example
+
+This directory exercises the full applicable Percy SDK feature surface for `io.percy:percy-java-selenium`. See the basic example at the repo root for the minimum integration.
+
+## What this example covers
+
+A JUnit 5 suite (`src/test/java/io/percy/examplepercyjavaselenium/advanced/AdvancedTest.java`) where each `@Test` exercises one row of the [Percy SDK Advanced Feature Matrix](../../../docs/advanced-example-feature-matrix.md) using the SDK's typed overloads (`snapshot(name, widths, minHeight, enableJavaScript, percyCSS, scope)`) and the `Map<String, Object> options` overload for everything else (responsive, readiness, labels, testCase, devicePixelRatio, browsers, regions, sync).
+
+Global SDK config — readiness preset, default widths, percyCSS, discovery — lives in `.percy.yml`.
+
+## Run locally
+
+```bash
+cd advanced
+make install                       # installs @percy/cli into node_modules
+export PERCY_TOKEN="<your token>"  # do NOT commit this
+make test
+```
+
+To run without a real token (CI assertion mode):
+
+```bash
+make test-advanced-ci   # uses --testing + PERCY_TOKEN=fake_token + captures /test/requests
+```
+
+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 — <reason>` / `Planned` / `Deprecated`. Source of truth is [`matrix.yml`](./matrix.yml).
+
+| Feature | State | Test |
+|---|---|---|
+| widths (typed overload) | Covered | `exercisesWidthsOverload` |
+| minHeight (typed overload) | Covered | `exercisesMinHeightOverload` |
+| enableJavaScript (typed overload) | Covered | `exercisesEnableJavaScriptOverload` |
+| percyCSS (typed overload) | Covered | `exercisesPercyCssOverload` |
+| scope (typed overload) | Covered | `exercisesScopeOverload` |
+| responsiveSnapshotCapture (Map options) | Covered | `exercisesMapOptionsResponsiveAndReadiness` |
+| readiness preset (Map options) | Covered | `exercisesMapOptionsResponsiveAndReadiness` |
+| labels (Map options) | Covered | `exercisesMapOptionsLabelsAndTestCase` |
+| testCase (Map options) | Covered | `exercisesMapOptionsLabelsAndTestCase` |
+| devicePixelRatio (Map options) | Covered | `exercisesMapOptionsDevicePixelRatio` |
+| browsers override (Map options) | Covered | `exercisesMapOptionsBrowsers` |
+| regions (Map options) | Covered | `exercisesMapOptionsRegions` |
+| sync mode (Map options) | Covered | `exercisesMapOptionsSync` |
+| Map<String, Object> options overload | Covered | seven `exercisesMapOptions*` tests |
+| `.percy.yml` global config | Covered | `.percy.yml` consumed at build start |
+| environment info reporting | Covered | automatic via SDK client info |
+| PERCY_SERVER_ADDRESS via env | Covered | CI advanced job picks up `PERCY_SERVER_ADDRESS` |
+| `Percy.createRegion` static helper | Planned | — |
+| `domTransformation` (Map options) | Planned | — |
+| `discovery` per-snapshot | N/A | discovery is per-build only |

advanced/matrix.yml

@@ -0,0 +1,76 @@
+# PER-8195 Phase 1 — Java-Selenium matrix-row mapping.
+# Test code: src/test/java/io/percy/examplepercyjavaselenium/advanced/AdvancedTest.java
+
+sdk: java-selenium
+package: io.percy:percy-java-selenium
+language: java
+sdk_min_version: '2.1.2'
+cli_min_version: '1.31.13'
+
+rows:
+  # Typed-overload signatures.
+  - id: widths
+    state: covered
+    test: 'AdvancedTest > exercisesWidthsOverload'
+  - id: min_height
+    state: covered
+    test: 'AdvancedTest > exercisesMinHeightOverload'
+  - id: enable_javascript
+    state: covered
+    test: 'AdvancedTest > exercisesEnableJavaScriptOverload'
+  - id: percy_css
+    state: covered
+    test: 'AdvancedTest > exercisesPercyCssOverload'
+  - id: scope
+    state: covered
+    test: 'AdvancedTest > exercisesScopeOverload'
+
+  # Map-based options overload.
+  - id: responsive_snapshot_capture
+    state: covered
+    test: 'AdvancedTest > exercisesMapOptionsResponsiveAndReadiness'
+  - id: readiness_preset
+    state: covered
+    test: 'AdvancedTest > exercisesMapOptionsResponsiveAndReadiness'
+  - id: labels
+    state: covered
+    test: 'AdvancedTest > exercisesMapOptionsLabelsAndTestCase'
+  - id: test_case
+    state: covered
+    test: 'AdvancedTest > exercisesMapOptionsLabelsAndTestCase'
+  - id: device_pixel_ratio
+    state: covered
+    test: 'AdvancedTest > exercisesMapOptionsDevicePixelRatio'
+  - id: browsers
+    state: covered
+    test: 'AdvancedTest > exercisesMapOptionsBrowsers'
+  - id: regions
+    state: covered
+    test: 'AdvancedTest > exercisesMapOptionsRegions'
+  - id: sync
+    state: covered
+    test: 'AdvancedTest > exercisesMapOptionsSync'
+  - id: map_options_overload
+    state: covered
+    test: 'AdvancedTest > exercisesMapOptions* (7 tests use the Map<String,Object> overload)'
+
+  - id: create_region_helper
+    state: planned
+    test: 'use of Percy.createRegion static helper to build region — TBD'
+  - id: dom_transformation
+    state: planned
+    test: 'AdvancedTest > exercisesDomTransformation (via Map options)'
+
+  - 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 io.percy:percy-java-selenium client info'

advanced/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "example-percy-java-selenium-advanced",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Advanced Percy example — local @percy/cli so the Makefile's node_modules/.bin/percy resolves (PER-8195).",
+  "devDependencies": {
+    "@percy/cli": "^1.31.13"
+  }
+}

advanced/pom.xml

@@ -0,0 +1,57 @@
+<?xml version="1.0"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>io.percy.examplepercyjavaselenium</groupId>
+  <artifactId>example-percy-java-selenium-advanced</artifactId>
+  <packaging>jar</packaging>
+  <version>1.0-SNAPSHOT</version>
+  <name>example-percy-java-selenium-advanced</name>
+  <properties>
+    <junit.jupiter.version>5.9.1</junit.jupiter.version>
+    <maven.compiler.source>17</maven.compiler.source>
+    <maven.compiler.target>17</maven.compiler.target>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+  <dependencies>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <version>${junit.jupiter.version}</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <version>${junit.jupiter.version}</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.seleniumhq.selenium</groupId>
+      <artifactId>selenium-java</artifactId>
+      <version>4.36.0</version>
+    </dependency>
+    <dependency>
+      <groupId>org.seleniumhq.selenium</groupId>
+      <artifactId>selenium-chrome-driver</artifactId>
+      <version>4.36.0</version>
+    </dependency>
+    <dependency>
+      <groupId>io.percy</groupId>
+      <artifactId>percy-java-selenium</artifactId>
+      <version>2.1.2</version>
+    </dependency>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <version>2.22.2</version>
+        <configuration>
+          <useSystemClassLoader>false</useSystemClassLoader>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>