@purchasely/cordova-plugin-purchasely 5.7.2 → 6.0.0-rc.1

package/example/e2e/README.md

@@ -0,0 +1,44 @@
+# Purchasely Cordova — End-to-End tests
+
+Device-level E2E tests for the example app, driving the **real** Purchasely 6.0 native
+SDK through the Cordova bridge. Built with **Appium + WebdriverIO**:
+
+- **WEBVIEW context** — calls `window.Purchasely.*` and asserts the results directly
+  (the deterministic `bridge` suite).
+- **NATIVE_APP context** — injects OS-level touches (interceptor / dismiss suites).
+
+These mirror the Flutter `integration_test` suite (`E2E_TEST_INDEX.md`) adapted to the
+Cordova imperative API. They are **not** part of the PR-gating `ci.yml`; they run via the
+`E2E Android` / `E2E iOS` workflows (`workflow_dispatch`, nightly `schedule`, and scoped
+`pull_request`).
+
+## Suites & gating
+
+| Suite | File | Gate | Notes |
+|-------|------|------|-------|
+| bridge | `specs/bridge.e2e.js` | **hard** | anonymous id, allProducts, fetchPresentationForPlacement, synchronize completion, user-attribute round-trip |
+| dismiss | `specs/dismiss.e2e.js` | best-effort | present placement + programmatic close → dismiss outcome + `closeReason` (needs a paywall to render) |
+
+Best-effort suites emit `::warning::` on failure and do not fail the job (native/paywall
+rendering is flaky in CI — same policy as the Flutter suite). Each suite retries up to 3×.
+
+## Requirements to go green
+
+1. The placement `PURCHASELY_E2E_PLACEMENT` (default `ONBOARDING`) must exist on the
+   backend the example API key (`www/js/index.js`) points to, for app id
+   `com.purchasely.demo`. Override with the env var if your integration placement differs.
+2. Android: an emulator with Google APIs (the workflow uses API 34, `pixel_6`).
+3. iOS: an iPhone 16/15 simulator (the workflow discovers one).
+
+## Run locally
+
+```bash
+# Android (emulator already booted, apk already built via `cordova build android`)
+cd purchasely/example/e2e && npm install
+bash ./tools/ci_run_e2e.sh emulator-5554
+
+# iOS (simulator booted, app built via `cordova build ios --emulator`)
+bash ./tools/ci_run_e2e_ios.sh <simulator-udid>
+```
+
+Logs are written to `purchasely/example/e2e/ci-logs/` (uploaded as CI artifacts).

package/example/e2e/helpers/driver.js

@@ -0,0 +1,70 @@
+// Helpers for driving the Purchasely Cordova example app under Appium/WebdriverIO.
+//
+// Two contexts are used:
+//   * WEBVIEW  — run JS against `window.Purchasely` (the cordova.exec bridge) and read
+//                results directly; used for the deterministic "bridge" assertions.
+//   * NATIVE_APP — inject OS-level touches (tap purchase button, press back) for the
+//                interceptor / dismiss suites.
+
+async function switchToWebview() {
+  await browser.waitUntil(async () => {
+    const contexts = await browser.getContexts();
+    return contexts.some((c) => (typeof c === 'string' ? c : c.id).includes('WEBVIEW'));
+  }, { timeout: 60000, timeoutMsg: 'WEBVIEW context never appeared' });
+
+  const contexts = await browser.getContexts();
+  const webview = contexts
+    .map((c) => (typeof c === 'string' ? c : c.id))
+    .find((id) => id.includes('WEBVIEW'));
+  await browser.switchContext(webview);
+}
+
+async function switchToNative() {
+  await browser.switchContext('NATIVE_APP');
+}
+
+// Wait until the Purchasely bridge is available (deviceready fired + plugin clobbered).
+async function waitForPurchaselyReady() {
+  await switchToWebview();
+  await browser.waitUntil(
+    async () => browser.execute(() => typeof window.Purchasely !== 'undefined'),
+    { timeout: 60000, timeoutMsg: 'window.Purchasely never became available' }
+  );
+}
+
+// Invoke a Purchasely method that takes trailing (success, error) callbacks and resolve
+// with { ok, value } on success or { ok:false, error } on error. `args` are the leading
+// positional arguments before the callbacks.
+async function callBridge(method, args = [], timeoutMs = 30000) {
+  return browser.executeAsync(
+    function (method, args, timeoutMs, done) {
+      var settled = false;
+      var finish = function (payload) {
+        if (settled) return;
+        settled = true;
+        done(payload);
+      };
+      setTimeout(function () { finish({ ok: false, error: 'timeout' }); }, timeoutMs);
+      try {
+        var fn = window.Purchasely[method];
+        if (typeof fn !== 'function') {
+          return finish({ ok: false, error: 'no such method: ' + method });
+        }
+        fn.apply(
+          window.Purchasely,
+          args.concat([
+            function (value) { finish({ ok: true, value: value }); },
+            function (error) { finish({ ok: false, error: String(error) }); },
+          ])
+        );
+      } catch (e) {
+        finish({ ok: false, error: String(e) });
+      }
+    },
+    method,
+    args,
+    timeoutMs
+  );
+}
+
+module.exports = { switchToWebview, switchToNative, waitForPurchaselyReady, callBridge };

package/example/e2e/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "purchasely-cordova-e2e",
+  "version": "1.0.0",
+  "private": true,
+  "description": "End-to-end tests for the Purchasely Cordova example app (Appium + WebdriverIO). Drives the real native Purchasely 6.0 SDK inside the WebView (bridge assertions) and injects OS-level touches (interceptor / dismiss).",
+  "scripts": {
+    "test:android": "wdio run ./wdio.android.conf.js",
+    "test:ios": "wdio run ./wdio.ios.conf.js"
+  },
+  "devDependencies": {
+    "@wdio/cli": "^9.0.0",
+    "@wdio/local-runner": "^9.0.0",
+    "@wdio/mocha-framework": "^9.0.0",
+    "@wdio/spec-reporter": "^9.0.0",
+    "appium": "^2.11.0",
+    "appium-uiautomator2-driver": "^3.9.0",
+    "appium-xcuitest-driver": "^7.28.0"
+  }
+}

package/example/e2e/specs/bridge.e2e.js

@@ -0,0 +1,51 @@
+// Deterministic Dart<->native bridge assertions (no native taps). HARD gate — these
+// must pass. Mirrors the Flutter E2E_TEST_INDEX suite T1/T3/T5/T6 adapted to the
+// Cordova imperative API.
+const { waitForPurchaselyReady, callBridge } = require('../helpers/driver');
+
+const PLACEMENT = process.env.PURCHASELY_E2E_PLACEMENT || 'ONBOARDING';
+
+describe('Purchasely bridge (WEBVIEW context)', () => {
+  before(async () => {
+    await waitForPurchaselyReady();
+  });
+
+  // T1 — anonymous user id
+  it('getAnonymousUserId returns a non-empty id', async () => {
+    const res = await callBridge('getAnonymousUserId');
+    expect(res.ok).toBe(true);
+    expect(typeof res.value).toBe('string');
+    expect(res.value.length).toBeGreaterThan(0);
+  });
+
+  // T5 — catalog
+  it('allProducts returns a list', async () => {
+    const res = await callBridge('allProducts');
+    expect(res.ok).toBe(true);
+    expect(Array.isArray(res.value)).toBe(true);
+  });
+
+  // T3 — preload a presentation for a placement
+  it('fetchPresentationForPlacement returns a presentation object', async () => {
+    const res = await callBridge('fetchPresentationForPlacement', [PLACEMENT, null]);
+    expect(res.ok).toBe(true);
+    expect(res.value).toBeDefined();
+    // v6 presentation carries an id/type so it can later be displayed.
+    expect(res.value === null || typeof res.value === 'object').toBe(true);
+  });
+
+  // T6 — synchronize now reports completion (v6 change). On a bare emulator/simulator
+  // with no billing, exactly one of success/error must fire (no fire-and-forget).
+  it('synchronize resolves exactly one callback', async () => {
+    const res = await callBridge('synchronize');
+    expect(typeof res.ok).toBe('boolean');
+  });
+
+  // user-attribute round-trip (set then read back)
+  it('setUserAttributeWithString then userAttribute round-trips', async () => {
+    await callBridge('setUserAttributeWithString', ['e2e_key', 'e2e_value', 'ESSENTIAL']);
+    const res = await callBridge('userAttribute', ['e2e_key']);
+    expect(res.ok).toBe(true);
+    expect(res.value).toBe('e2e_value');
+  });
+});

package/example/e2e/specs/dismiss.e2e.js

@@ -0,0 +1,37 @@
+// Presentation display + dismiss outcome. BEST-EFFORT (non-blocking in CI): depends on
+// a paywall actually rendering for the configured placement against the real backend.
+// Mirrors E2E_TEST_INDEX T8/T12 adapted to the Cordova imperative API.
+const { waitForPurchaselyReady, callBridge, switchToNative } = require('../helpers/driver');
+
+const PLACEMENT = process.env.PURCHASELY_E2E_PLACEMENT || 'ONBOARDING';
+
+describe('Presentation dismiss outcome', () => {
+  before(async () => {
+    await waitForPurchaselyReady();
+  });
+
+  // T8/T12 — the present* success callback IS the per-presentation dismiss outcome.
+  // Present a placement, close it programmatically, and assert the outcome fires with a
+  // closeReason.
+  it('presentPresentationForPlacement + closePresentation delivers a dismiss outcome', async () => {
+    // Kick off the presentation; do NOT await (the callback resolves at dismiss).
+    const outcomePromise = callBridge(
+      'presentPresentationForPlacement',
+      [PLACEMENT, null, 'fullScreen'],
+      90000
+    );
+
+    // Give the paywall time to render, then close it programmatically from the bridge.
+    await browser.pause(6000);
+    await callBridge('closePresentation');
+
+    const outcome = await outcomePromise;
+    expect(outcome.ok).toBe(true);
+    expect(outcome.value).toBeDefined();
+    // v6 outcome carries a closeReason; programmatic close => 'programmatic' (Android).
+    if (outcome.value && outcome.value.closeReason) {
+      expect(typeof outcome.value.closeReason).toBe('string');
+    }
+    await switchToNative().catch(() => {});
+  });
+});

package/example/e2e/tools/ci_run_e2e.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Android E2E runner. Assumes:
+#   * an emulator is already booted (serial passed as $1, e.g. emulator-5554)
+#   * the debug apk has been built (cordova build android)
+#   * node deps for purchasely/example/e2e are installed
+#
+# Gating mirrors the Flutter suite: the deterministic `bridge` suite HARD-gates the job;
+# `dismiss` (needs a paywall to render against the real backend) is BEST-EFFORT and only
+# emits ::warning:: on failure.
+set -uo pipefail
+
+SERIAL="${1:-emulator-5554}"
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+LOGDIR="$HERE/ci-logs"
+mkdir -p "$LOGDIR"
+export ANDROID_SERIAL="$SERIAL"
+
+echo "== Starting Appium =="
+npx appium --log "$LOGDIR/appium-android.log" --log-level info &
+APPIUM_PID=$!
+trap 'kill $APPIUM_PID 2>/dev/null || true' EXIT
+# Wait for Appium to accept connections.
+for i in $(seq 1 30); do
+  curl -sf http://127.0.0.1:4723/status >/dev/null 2>&1 && break
+  sleep 1
+done
+
+run_suite() { # $1 = spec glob, $2 = hard|soft
+  local spec="$1" gate="$2" tries=3 n=1
+  while [ $n -le $tries ]; do
+    echo "== [$gate] $spec (attempt $n/$tries) =="
+    if PURCHASELY_E2E_SPEC="$spec" npx wdio run ./wdio.android.conf.js --spec "$spec" 2>&1 | tee "$LOGDIR/wdio-$(basename "$spec").log"; then
+      return 0
+    fi
+    n=$((n+1))
+  done
+  if [ "$gate" = "hard" ]; then
+    echo "::error::E2E suite failed (hard gate): $spec"
+    return 1
+  fi
+  echo "::warning::E2E suite failed (best-effort): $spec"
+  return 0
+}
+
+cd "$HERE"
+rc=0
+run_suite "./specs/bridge.e2e.js"  hard || rc=1
+run_suite "./specs/dismiss.e2e.js" soft || true
+exit $rc

package/example/e2e/tools/ci_run_e2e_ios.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# iOS E2E runner. Assumes:
+#   * a simulator is already booted (udid passed as $1)
+#   * the simulator .app has been built (cordova build ios --emulator)
+#   * node deps for purchasely/example/e2e are installed
+#
+# Same gating as Android: `bridge` HARD-gates; `dismiss` is BEST-EFFORT.
+set -uo pipefail
+
+UDID="${1:-booted}"
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+LOGDIR="$HERE/ci-logs"
+mkdir -p "$LOGDIR"
+export PURCHASELY_E2E_UDID="$UDID"
+
+echo "== Starting Appium =="
+npx appium --log "$LOGDIR/appium-ios.log" --log-level info &
+APPIUM_PID=$!
+trap 'kill $APPIUM_PID 2>/dev/null || true' EXIT
+for i in $(seq 1 30); do
+  curl -sf http://127.0.0.1:4723/status >/dev/null 2>&1 && break
+  sleep 1
+done
+
+run_suite() { # $1 = spec, $2 = hard|soft
+  local spec="$1" gate="$2" tries=3 n=1
+  while [ $n -le $tries ]; do
+    echo "== [$gate] $spec (attempt $n/$tries) =="
+    if npx wdio run ./wdio.ios.conf.js --spec "$spec" 2>&1 | tee "$LOGDIR/wdio-$(basename "$spec").log"; then
+      return 0
+    fi
+    n=$((n+1))
+  done
+  if [ "$gate" = "hard" ]; then
+    echo "::error::E2E suite failed (hard gate): $spec"
+    return 1
+  fi
+  echo "::warning::E2E suite failed (best-effort): $spec"
+  return 0
+}
+
+cd "$HERE"
+rc=0
+run_suite "./specs/bridge.e2e.js"  hard || rc=1
+run_suite "./specs/dismiss.e2e.js" soft || true
+exit $rc

package/example/e2e/wdio.android.conf.js

@@ -0,0 +1,21 @@
+const path = require('path');
+const { config } = require('./wdio.shared.conf');
+
+// Path to the debug apk built by `cordova build android`.
+const APK = process.env.PURCHASELY_E2E_APK ||
+  path.resolve(__dirname, '../platforms/android/app/build/outputs/apk/debug/app-debug.apk');
+
+exports.config = Object.assign({}, config, {
+  capabilities: [{
+    platformName: 'Android',
+    'appium:automationName': 'UiAutomator2',
+    'appium:app': APK,
+    'appium:appPackage': 'com.purchasely.demo',
+    'appium:newCommandTimeout': 240,
+    'appium:autoGrantPermissions': true,
+    // The Cordova WebView is debuggable in the debug build, so Appium can attach
+    // chromedriver and expose the WEBVIEW context.
+    'appium:ensureWebviewsHavePages': true,
+    'appium:nativeWebScreenshot': true,
+  }],
+});

package/example/e2e/wdio.ios.conf.js

@@ -0,0 +1,19 @@
+const path = require('path');
+const { config } = require('./wdio.shared.conf');
+
+// Path to the .app built by `cordova build ios --emulator` (simulator build).
+const APP = process.env.PURCHASELY_E2E_APP ||
+  path.resolve(__dirname, '../platforms/ios/build/emulator/HelloCordova.app');
+
+exports.config = Object.assign({}, config, {
+  capabilities: [{
+    platformName: 'iOS',
+    'appium:automationName': 'XCUITest',
+    'appium:app': APP,
+    'appium:bundleId': 'com.purchasely.demo',
+    'appium:deviceName': process.env.PURCHASELY_E2E_SIM || 'iPhone 16',
+    'appium:platformVersion': process.env.PURCHASELY_E2E_IOS_VERSION || undefined,
+    'appium:newCommandTimeout': 240,
+    'appium:autoAcceptAlerts': true,
+  }],
+});

package/example/e2e/wdio.shared.conf.js

@@ -0,0 +1,28 @@
+// Shared WebdriverIO config for the Purchasely Cordova E2E suite.
+// Platform-specific configs (wdio.android.conf.js / wdio.ios.conf.js) extend this
+// and set `capabilities`.
+//
+// The example app boots the Purchasely SDK on `deviceready` (see www/js/index.js).
+// Tests switch to the WEBVIEW context and call `window.Purchasely.*` directly, and
+// switch to NATIVE_APP to inject OS-level touches for the interceptor / dismiss suites.
+exports.config = {
+  runner: 'local',
+  specs: ['./specs/**/*.e2e.js'],
+  maxInstances: 1,
+  logLevel: 'info',
+  bail: 0,
+  waitforTimeout: 20000,
+  connectionRetryTimeout: 120000,
+  connectionRetryCount: 2,
+  framework: 'mocha',
+  reporters: ['spec'],
+  mochaOpts: {
+    ui: 'bdd',
+    timeout: 120000,
+  },
+  // Appium is started as a service by the CI runner scripts (tools/ci_run_e2e*.sh),
+  // so we point WDIO at the already-running server rather than the @wdio/appium-service.
+  hostname: '127.0.0.1',
+  port: 4723,
+  path: '/',
+};