feat(advanced): PER-8195 Phase 2 — advanced example for io.percy:percy-appium-app

.github/workflows/advanced.yml

@@ -0,0 +1,45 @@
+name: Advanced — App Percy
+
+# PER-8195 Phase 2 — advanced example for io.percy:percy-appium-app.
+# Triggers manually only (`workflow_dispatch`). App Percy CI requires a real
+# device session; we don't run it on every PR because forks and Dependabot
+# don't have access to the hub secrets.
+on:
+  workflow_dispatch:
+
+jobs:
+  advanced:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    defaults:
+      run:
+        working-directory: advanced
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: 11
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - name: Sanity-check BrowserStack secrets
+        env:
+          AA_USERNAME: ${{ secrets.AA_USERNAME }}
+          AA_ACCESS_KEY: ${{ secrets.AA_ACCESS_KEY }}
+        run: |
+          if [ -z "$AA_USERNAME" ] || [ -z "$AA_ACCESS_KEY" ]; then
+            echo "::error::AA_USERNAME / AA_ACCESS_KEY repo secrets are required for the advanced App Percy job."
+            exit 1
+          fi
+      - name: Install advanced/ dependencies
+        run: make install
+      - name: Run mvn test advanced against BrowserStack
+        env:
+          AA_USERNAME: ${{ secrets.AA_USERNAME }}
+          AA_ACCESS_KEY: ${{ secrets.AA_ACCESS_KEY }}
+          APP: ${{ secrets.APP_BS_URL }}
+          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
+          PERCY_BRANCH: ${{ github.ref_name }}
+          PERCY_COMMIT: ${{ github.sha }}
+        run: make test

README.md

@@ -1,6 +1,15 @@
 # example-percy-appium-java
 Example app used by the [Percy Java Appium tutorial](https://docs.percy.io/v2-app/docs/appium-for-java) demonstrating Percy's Java Appium integration.
 
+> **New:** This repo ships an [`advanced/`](./advanced) example covering the full applicable App Percy SDK feature surface for `io.percy:percy-appium-app`. See the [Percy SDK Feature Matrix](https://docs.percy.io/docs/sdk-feature-matrix) for cross-SDK coverage.
+
+## Examples
+
+| Example | What it shows | Run command |
+|---|---|---|
+| `./` (basic, at repo root) | Minimum viable: `percy.screenshot(name)` plus Android / iOS / Espresso typed flows. Start here. | `make test-android` |
+| [`./advanced/`](./advanced) | Full applicable App Percy SDK feature surface: orientation, ignore/consider regions (xpath, appium element, custom bbox), fullscreen + status/nav bar heights, sync mode, test_case + labels. JUnit 5 + Map<String,Object> options overload. See [`advanced/README.md`](./advanced/README.md). | `cd advanced && make test` |
+
 ## Java Appium Tutorial
 
 The tutorial assumes you're already familiar with Java and

advanced/.gitignore

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

advanced/.percy.yml

@@ -0,0 +1,7 @@
+# PER-8195 — global config for the io.percy:percy-appium-app advanced
+# example. Per-screenshot options in AdvancedTest.java override these.
+
+version: 2
+
+percy:
+  defer_uploads: false

advanced/Makefile

@@ -0,0 +1,17 @@
+NPM=node_modules/.bin
+
+.PHONY: install clean test test-advanced
+
+$(NPM):
+	npm install --no-save @percy/cli@^1.31.13
+
+install: $(NPM)
+	mvn dependency:resolve
+
+clean:
+	rm -rf target node_modules
+
+# Run against the BrowserStack App Automate hub. Requires AA_USERNAME,
+# AA_ACCESS_KEY, APP, PERCY_TOKEN env vars.
+test test-advanced: install
+	$(NPM)/percy app:exec -- mvn test

advanced/README.md

@@ -0,0 +1,31 @@
+# Advanced Percy + Appium-Java
+
+This directory exercises the full applicable Percy SDK feature surface for `io.percy:percy-appium-app`. 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/examplepercyappiumjava/advanced/AdvancedTest.java`) where each `@Test` exercises one row of the [App Percy / Appium Native matrix](../../../docs/advanced-example-feature-matrix.md): device_name override, orientation, fullscreen + status_bar_height + nav_bar_height, ignore regions via xpath / appium element / custom bounding box, consider regions via xpath, sync mode, test_case + labels, build metadata via env, PERCY_BRANCH / PERCY_COMMIT override.
+
+Web-only options (widths, percyCSS, minHeight, scope, discovery, domTransformation, responsiveSnapshotCapture, readiness preset, devicePixelRatio, browsers) marked `N/A` in `matrix.yml` — there's no DOM in native App Percy.
+
+## Run locally
+
+Requires BrowserStack App Automate hub credentials and an app uploaded to the BrowserStack cloud:
+
+```bash
+cd advanced
+make install
+export AA_USERNAME="<browserstack username>"
+export AA_ACCESS_KEY="<browserstack access key>"
+export APP="bs://<your hashed app id>"
+export PERCY_TOKEN="<your project token>"      # do NOT commit this
+make test
+```
+
+## CI note
+
+The advanced CI job is `workflow_dispatch`-only — App Percy CI requires a real BrowserStack device session, which forks/Dependabot cannot access. See `.github/workflows/advanced.yml`.
+
+## Coverage matrix
+
+States: `Covered` / `N/A — <reason>` / `Planned` / `Deprecated`. Source of truth is [`matrix.yml`](./matrix.yml).

advanced/matrix.yml

@@ -0,0 +1,98 @@
+# PER-8195 Phase 2 — Appium-Java matrix-row mapping.
+# Test code: src/test/java/io/percy/examplepercyappiumjava/advanced/AdvancedTest.java
+
+sdk: appium-java
+package: io.percy:percy-appium-app
+language: java
+sdk_min_version: '2.2.0'
+cli_min_version: '1.31.13'
+
+rows:
+  - id: device_name_override
+    state: covered
+    test: 'AdvancedTest > exercisesDeviceNameAndOrientation'
+  - id: orientation_handling
+    state: covered
+    test: 'AdvancedTest > exercisesDeviceNameAndOrientation'
+  - id: fullscreen
+    state: covered
+    test: 'AdvancedTest > exercisesFullscreenAndBars'
+  - id: status_bar_height
+    state: covered
+    test: 'AdvancedTest > exercisesFullscreenAndBars'
+  - id: nav_bar_height
+    state: covered
+    test: 'AdvancedTest > exercisesFullscreenAndBars'
+  - id: ignore_regions_xpaths
+    state: covered
+    test: 'AdvancedTest > exercisesIgnoreRegionsViaXpath'
+  - id: ignore_region_appium_elements
+    state: covered
+    test: 'AdvancedTest > exercisesIgnoreRegionsViaAppiumElements'
+  - id: custom_ignore_regions
+    state: covered
+    test: 'AdvancedTest > exercisesCustomIgnoreRegions'
+  - id: consider_regions_xpaths
+    state: covered
+    test: 'AdvancedTest > exercisesConsiderRegionsViaXpath'
+  - id: sync
+    state: covered
+    test: 'AdvancedTest > exercisesSyncMode'
+  - id: test_case
+    state: covered
+    test: 'AdvancedTest > exercisesTestCaseAndLabels'
+  - id: labels
+    state: covered
+    test: 'AdvancedTest > exercisesTestCaseAndLabels'
+
+  - id: build_metadata_via_env
+    state: covered
+    test: 'AdvancedTest @BeforeAll capabilities driven by env (PERCY_PROJECT, PERCY_BUILD, DEVICE, OS_VERSION, APP)'
+  - id: env_percy_branch
+    state: covered
+    test: 'CI advanced job sets PERCY_BRANCH via env'
+  - id: env_percy_commit
+    state: covered
+    test: 'CI advanced job sets PERCY_COMMIT via env'
+
+  # Web-only options — not applicable.
+  - id: widths
+    state: n_a
+    reason: 'No DOM in native App Percy.'
+  - id: percy_css
+    state: n_a
+    reason: 'No DOM in native App Percy.'
+  - id: min_height
+    state: n_a
+    reason: 'No DOM in native App Percy.'
+  - id: enable_javascript
+    state: n_a
+    reason: 'No DOM in native App Percy.'
+  - id: scope
+    state: n_a
+    reason: 'No DOM in native App Percy.'
+  - id: discovery
+    state: n_a
+    reason: 'No DOM in native App Percy.'
+  - id: dom_transformation
+    state: n_a
+    reason: 'No DOM in native App Percy.'
+  - id: responsive_snapshot_capture
+    state: n_a
+    reason: 'No DOM in native App Percy.'
+  - id: readiness_preset
+    state: n_a
+    reason: 'Not applicable; native screenshots after explicit Thread.sleep / WebDriverWait.'
+  - id: device_pixel_ratio
+    state: n_a
+    reason: 'Device DPR captured implicitly.'
+  - id: browsers
+    state: n_a
+    reason: 'App Percy targets devices, not browsers.'
+
+  - 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-appium-app client info'

advanced/pom.xml

@@ -0,0 +1,51 @@
+<?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.examplepercyappiumjava</groupId>
+  <artifactId>example-percy-appium-java-advanced</artifactId>
+  <packaging>jar</packaging>
+  <version>1.0-SNAPSHOT</version>
+  <properties>
+    <junit.jupiter.version>5.9.1</junit.jupiter.version>
+    <maven.compiler.source>11</maven.compiler.source>
+    <maven.compiler.target>11</maven.compiler.target>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+  <dependencies>
+    <dependency>
+      <groupId>io.appium</groupId>
+      <artifactId>java-client</artifactId>
+      <version>7.6.0</version>
+    </dependency>
+    <dependency>
+      <groupId>io.percy</groupId>
+      <artifactId>percy-appium-app</artifactId>
+      <version>2.2.0</version>
+    </dependency>
+    <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>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <version>2.22.2</version>
+        <configuration>
+          <useSystemClassLoader>false</useSystemClassLoader>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>