commit 59f1a7af3ae3a8c1673c3f256cfda0280fd96ad1
parent 58b2417dfaaa03cda3f0d85282aaeb413566f2f8
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 29 Oct 2026 12:13:40 +0100
[pos] simulator: drive the terminal in an emulator and record what breaks
A harness for merchant-terminal.
Assisted by LLM
Also migrate CI container to trixie.
Diffstat:
85 files changed, 17594 insertions(+), 13 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -37,3 +37,8 @@ publish.sh
.classpath
.project
.settings
+
+# Scratch directories contrib/ci/ci.sh creates for a container run
+/artifacts
+/inputs
+/cache
diff --git a/contrib/ci/Containerfile b/contrib/ci/Containerfile
@@ -1,18 +1,161 @@
-FROM docker.io/briar/ci-image-android:latest
+FROM docker.io/library/debian:trixie
-# Install fdroidserver and other tools
-RUN apt update && apt-get -qy install --no-install-recommends \
+ENV DEBIAN_FRONTEND=noninteractive
+ENV LANG=C.UTF-8
+ENV ANDROID_HOME=/opt/android-sdk
+# The JDK is trixie's own OpenJDK 21 (the distribution packages 21 and 25, not
+# 17). That is only the JVM that *runs* Gradle: every Kotlin module pins
+# `jvmTarget = "17"` and `compileOptions` to `VERSION_17`, and
+# donau-verificator is plain Java with the same `compileOptions`, so the
+# bytecode the apps ship does not depend on this choice. Verified by running
+# `./gradlew check` over all six modules on JDK 17 and on JDK 21 with the
+# repository's own Gradle 9.4.1 / AGP 9.2.1 / Kotlin 2.3.21: 435 unit tests,
+# no failures, byte-for-byte the same task outcomes. 21 over 25 because
+# Robolectric documents 21 and 25 is not yet exercised here.
+ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
+ENV PATH="${PATH}:${ANDROID_HOME}/cmdline-tools/latest/bin:${ANDROID_HOME}/platform-tools:/root/.local/bin"
+
+# Base tools: what the jobs themselves shell out to, plus fdroidserver's and
+# the coverage job's Python.
+RUN apt-get update && apt-get -qy install --no-install-recommends \
+ bash \
+ ca-certificates \
+ curl \
+ git \
+ openssh-client \
pipx \
+ python3 \
python3-pip \
- python3-wheel \
python3-setuptools \
- openssh-client \
- rsync
+ python3-wheel \
+ rsync \
+ unzip \
+ && rm -rf /var/lib/apt/lists/*
+
+# The JDK, from Debian itself rather than a third-party archive. The
+# -headless package is enough: Gradle, the Kotlin compiler, Android lint and
+# apksigner all run without AWT, which the verification runs confirmed.
+# JAVA_HOME is asserted rather than assumed, so a package that ever lands
+# somewhere else stops the build here instead of handing every later Gradle
+# invocation a JAVA_HOME that does not exist.
+RUN apt-get update \
+ && apt-get -qy install --no-install-recommends openjdk-21-jdk-headless \
+ && rm -rf /var/lib/apt/lists/* \
+ && test -x "${JAVA_HOME}/bin/javac" \
+ && "${JAVA_HOME}/bin/java" -version
-ENV PATH="${PATH}:/root/.local/bin"
-RUN pipx install git+https://gitlab.com/fdroid/fdroidserver.git
+# GNU Taler's own binaries, for the jobs that drive the apps rather than
+# compile them: taler-wallet-cli is the headless wallet the integration suites
+# pay and withdraw with, taler-twister the proxy they damage protocol replies
+# with to reach the error paths. `trixie-testing` rather than `trixie`
+# because it tracks the protocol version the apps in this repository are
+# written against.
+#
+# The signing key is pinned by digest -- it is fetched over HTTPS at build
+# time, and the hash is the one shipped in bfh-infra's taler_apt role, so a
+# substituted key fails the build rather than silently signing a different
+# archive.
+RUN curl -fsSL -o /etc/apt/keyrings/taler-systems.gpg \
+ https://www.taler.net/taler-systems.gpg \
+ && echo "173823431a6bdaf06d315cd86b2c50937eafac986eb8f127b2953210fba6b79c /etc/apt/keyrings/taler-systems.gpg" \
+ | sha256sum -c - \
+ && echo "deb [signed-by=/etc/apt/keyrings/taler-systems.gpg arch=amd64] https://deb.taler.net/apt/debian trixie-testing main" \
+ > /etc/apt/sources.list.d/taler.list \
+ && apt-get update \
+ && apt-get -qy install --no-install-recommends \
+ taler-twister \
+ taler-wallet-cli \
+ && rm -rf /var/lib/apt/lists/* \
+ && command -v taler-twister \
+ && command -v taler-wallet-cli
-ENV JAVA_HOME /usr/lib/jvm/java-17-openjdk-amd64
+# The Android command-line tools, pinned and checksummed. Google serves only
+# a `_latest` URL per revision, so the digest is what actually fixes the
+# version; bump both together.
+RUN set -eu; \
+ zip=commandlinetools-linux-13114758_latest.zip; \
+ cd /tmp; \
+ curl -fsSLO "https://dl.google.com/android/repository/${zip}"; \
+ echo "7ec965280a073311c339e571cd5de778b9975026cfcbe79f2b1cdcb1e15317ee ${zip}" | sha256sum -c -; \
+ unzip -q "${zip}"; \
+ mkdir -p "${ANDROID_HOME}/cmdline-tools"; \
+ mv cmdline-tools "${ANDROID_HOME}/cmdline-tools/latest"; \
+ rm -f "${zip}"; \
+ sdkmanager --version
+
+# Licences first, so every later sdkmanager call is non-interactive, then the
+# platforms the briar image used to carry. compileSdk 37 is deliberately not
+# installed: Google publishes it only as minor versions (android-37.0, .1,
+# .2), and AGP already downloads the exact platform a module asks for, which
+# is how the previous base -- which stopped at android-36 -- built this
+# repository.
+RUN yes | sdkmanager --licenses > /dev/null
+RUN sdkmanager \
+ "platform-tools" \
+ "platforms;android-34" \
+ "platforms;android-35" \
+ "platforms;android-36" \
+ "build-tools;35.0.0" \
+ && ln -s "${ANDROID_HOME}/build-tools/35.0.0/apksigner" /usr/bin/ \
+ && ln -s "${ANDROID_HOME}/build-tools/35.0.0/aapt2" /usr/bin/
+
+# The Android emulator, for the jobs that drive an app rather than compile it.
+#
+# It costs roughly 1.5 GB in an image every job pulls; one big image was the
+# deliberate choice over a second one, because a per-job Containerfile is not
+# something the buildbot supports (its generic stage step passes only jobCmd,
+# never containerFile).
+#
+# The emulator binary is dynamically linked against X and friends even when it
+# is run with -no-window. Without them it dies with
+#
+# libX11.so.6: cannot open shared object file: No such file or directory
+#
+# which reads like a broken SDK rather than a missing dependency, so the list
+# is spelled out. libasound2 was renamed libasound2t64 in trixie; the
+# fallback keeps the build working whenever the base image moves again.
+RUN apt-get update && apt-get -qy install --no-install-recommends \
+ fontconfig \
+ libdrm2 \
+ libgbm1 \
+ libgl1 \
+ libglu1-mesa \
+ libnspr4 \
+ libnss3 \
+ libpulse0 \
+ libx11-6 \
+ libxcb1 \
+ libxcomposite1 \
+ libxcursor1 \
+ libxdamage1 \
+ libxext6 \
+ libxfixes3 \
+ libxi6 \
+ libxrandr2 \
+ libxrender1 \
+ libxtst6 \
+ && ( apt-get -qy install --no-install-recommends libasound2t64 \
+ || apt-get -qy install --no-install-recommends libasound2 ) \
+ && rm -rf /var/lib/apt/lists/*
+
+# google_apis rather than the bare image: the terminal needs Play-services-free
+# Google APIs for its camera and NFC stubs, and x86_64 because every CI worker
+# is amd64 and an arm64 image would be translated instruction by instruction.
+#
+# The system image pulls the emulator in with it, so asking for "emulator" as
+# well installs a *second* copy at $ANDROID_HOME/emulator-2 and every
+# sdkmanager call afterwards warns about the duplicate ("Observed package id
+# 'emulator' in inconsistent location"). It is therefore requested only if the
+# image did not already provide it.
+RUN yes | sdkmanager "system-images;android-36;google_apis;x86_64" \
+ && if [ ! -x "${ANDROID_HOME}/emulator/emulator" ]; then \
+ yes | sdkmanager "emulator"; \
+ fi \
+ && test -x "${ANDROID_HOME}/emulator/emulator" \
+ && test ! -e "${ANDROID_HOME}/emulator-2"
+
+RUN pipx install git+https://gitlab.com/fdroid/fdroidserver.git \
+ && fdroid --version
# Deployment to F-droid nightly
ENV FDROID_REPO_KEY /inputs/fdroid-repo-key.txt
@@ -28,8 +171,4 @@ ENV SCP_SSH_KEY /inputs/wallet.taler.net
ENV SCP_SSH_HOST files@gnunet.org
ENV SCP_SSH_PATH ~
-RUN echo y | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "build-tools;35.0.0"
-RUN ln -s $ANDROID_HOME/build-tools/35.0.0/apksigner /usr/bin/
-RUN ln -s $ANDROID_HOME/build-tools/35.0.0/aapt2 /usr/bin/
-
WORKDIR /workdir
diff --git a/contrib/ci/ci.sh b/contrib/ci/ci.sh
@@ -18,6 +18,19 @@ if [ "${CONTAINER_BUILD}" = "True" ] ; then
-f contrib/ci/Containerfile .
fi
+# An Android emulator needs /dev/kvm, and a container only gets it if the host
+# passes the device *and* the user this maps to may open it. Passed only when
+# both hold, so a worker without KVM keeps running every other job: podman
+# fails the run outright if asked for a device that is not there.
+#
+# `--group-add keep-groups` is what carries the host user's `kvm` membership
+# into a rootless container; without it the device shows up as nobody:nogroup
+# and is unusable even though the host user has access.
+KVM_ARGS=()
+if [ -r /dev/kvm ] && [ -w /dev/kvm ]; then
+ KVM_ARGS=(--device /dev/kvm --group-add keep-groups)
+fi
+
mkdir -p "${PWD}/inputs"
mkdir -p "${PWD}/artifacts"
mkdir -p "${PWD}/cache/.gradle"
@@ -26,7 +39,9 @@ mkdir -p "${PWD}/cache/.gradle"
--rm \
-ti \
--arch "${JOB_ARCH}" \
+ ${KVM_ARGS[@]+"${KVM_ARGS[@]}"} \
--env CI_COMMIT_REF="$(git rev-parse HEAD)" \
+ --env PUBLISH="${PUBLISH:-1}" \
--volume "${PWD}":/workdir \
--volume "${PWD}/cache/.gradle":/root/.gradle \
--volume "${PWD}/inputs:/inputs:ro" \
diff --git a/contrib/ci/jobs/5-coverage/README.md b/contrib/ci/jobs/5-coverage/README.md
@@ -0,0 +1,113 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# `5-coverage` — the report on lcov.taler.net
+
+```bash
+contrib/ci/ci.sh 5-coverage # as the buildbot runs it
+PUBLISH=0 contrib/ci/jobs/5-coverage/job.sh # locally, leaves the report on disk
+```
+
+The site serves a directory of HTML per repository. For the C codebases that
+directory comes from lcov's `genhtml`; nothing on the receiving end needs
+lcov's own format, so this ships **JaCoCo's** report, which is the same thing
+for the JVM — a source-annotated page per class, green and red down the
+gutter — plus a landing page over the top. It lands in
+`/artifacts/taler-android/lcov/$CI_COMMIT_REF/taler-android` and goes to
+`rsync://taler.host.internal:424243/incoming_taler/`, the same way
+`exchange/contrib/ci/jobs/002-test/5-coverage.sh` does it.
+
+No registration is needed: the buildbot lists `contrib/ci/jobs` to find its
+stages (`GenerateStagesCommand` in `taler-deployment/buildbot/master.cfg`),
+so a directory here is a job.
+
+## What it covers, and what it does not
+
+It runs **every JVM unit test in the repository** — `taler-kotlin-android`,
+`merchant-lib`, `merchant-terminal` and `wallet`, the four modules that have
+any. `cashier` and `donau-verificator` have none.
+
+It does **not** run the integration suites — `pos-simulator/` drives the
+merchant terminal in an Android emulator, which takes about two and a half
+hours for the whole suite even with hardware acceleration. That is a nightly
+on its own worker, not something to put on every push.
+
+### The emulator does work in this container
+
+Tested, so that the next person does not have to wonder:
+
+```
+$ emulator -accel-check
+KVM (version 12) is installed and usable.
+$ emulator -avd citest -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect
+BOOTED after 40s
+API 36
+Physical size: 2560x1600
+```
+
+Three things have to line up, and each fails in a way that looks like
+something else:
+
+* **The host account must be able to open `/dev/kvm`.** Not root, not the
+ group's existence — the account the worker runs as. `ls -l /dev/kvm` can
+ look perfectly healthy while `open()` returns `EACCES`, because access was
+ granted by ACL to somebody else. Test it with
+ `python3 -c "import os;os.close(os.open('/dev/kvm',os.O_RDWR))"`.
+* **Rootless podman needs `--group-add keep-groups`.** Without it the device
+ appears inside the container as `nobody:nogroup` and is unusable even
+ though the host user has access. `ci.sh` passes this, and `--device
+ /dev/kvm`, only when the host account can actually open the device, so a
+ worker without KVM still runs every other job.
+* **The emulator binary needs X libraries this image does not carry.**
+ Without them it dies with `libX11.so.6: cannot open shared object file`,
+ which reads like a broken SDK rather than a missing dependency:
+
+ ```
+ libx11-6 libxcb1 libxdamage1 libxext6 libxfixes3 libxcomposite1 libxcursor1
+ libxi6 libxrandr2 libxrender1 libxtst6 libnss3 libnspr4 libpulse0 libgl1
+ libglu1-mesa libdrm2 libgbm1 fontconfig
+ ```
+
+ plus `libasound2t64` (trixie) or `libasound2` (older), which is why the
+ install needs a fallback.
+
+The proof above mounted the host's SDK rather than baking one in. Packaging
+it is the remaining work and is routine — `sdkmanager "emulator"
+"system-images;android-36;google_apis;x86_64"` — but it adds roughly 1.5 GB
+to an image every other job also pulls, so it probably wants its own
+Containerfile rather than the shared one.
+
+## Feeding an emulator run in
+
+The job already takes the other half. A `pos-simulator` run writes JaCoCo
+`.ec` files to `$POS_SIM_ROOT/run/coverage`; drop those into
+`/inputs/emulator-coverage` (or point `EMULATOR_EC_DIR` elsewhere) and they
+are merged into the same report rather than needing a second one. The landing
+page then also lists which scenarios produced them.
+
+That is the whole integration, so when a worker with KVM exists the remaining
+work is to run the suite there and hand the directory over:
+
+```bash
+ssh <worker> 'cd /tmp/taler-pos-sim/driver && . ../env.sh && \
+ python3 campaign.py suite --workers 3 --label nightly'
+rsync -a <worker>:/tmp/taler-pos-sim/run/coverage/ inputs/emulator-coverage/
+contrib/ci/ci.sh 5-coverage
+```
+
+Fuzzing stays out either way: `pos-simulator/driver/explore.py` is a random
+walk, so its coverage is not reproducible between runs and would make the
+trend line meaningless.
diff --git a/contrib/ci/jobs/5-coverage/coverage.sh b/contrib/ci/jobs/5-coverage/coverage.sh
@@ -0,0 +1,113 @@
+#!/bin/bash
+# Coverage for lcov.taler.net.
+#
+# The site serves a directory of HTML per repository; for the C codebases that
+# directory comes from lcov's `genhtml`. Nothing on the receiving end needs
+# lcov's own format, so this ships JaCoCo's report, which is the same thing for
+# the JVM: a source-annotated page per class, green and red down the gutter.
+#
+# What runs here is every JVM unit test in the repository. The *integration*
+# suites -- pos-simulator/, which drives the merchant terminal in an emulator
+# -- are not run by this job, and the reason is a hard one: an Android
+# emulator needs /dev/kvm, a container only gets it if the host passes the
+# device *and* the CI user may open it, and even accelerated the pos-simulator
+# suite is about two and a half hours. That is a nightly on a KVM-capable
+# worker, not a job that runs on every push.
+#
+# When such a worker exists, this script already takes its output: drop the
+# `.ec` files a simulator run produced into /inputs/emulator-coverage (or
+# point EMULATOR_EC_DIR at them) and they are merged in, raising the same
+# report rather than needing a second one.
+set -exuo pipefail
+
+REPO_NAME=taler-android
+ARTIFACT_PATH="/artifacts/${REPO_NAME}/lcov/${CI_COMMIT_REF}/${REPO_NAME}"
+WORK="${PWD}/build/coverage"
+JACOCO_VERSION="${JACOCO_VERSION:-0.8.14}"
+CLI="${WORK}/org.jacoco.cli-${JACOCO_VERSION}-nodeps.jar"
+EMULATOR_EC_DIR="${EMULATOR_EC_DIR:-/inputs/emulator-coverage}"
+
+mkdir -p "${WORK}" "${ARTIFACT_PATH}"
+
+# Every module that has unit tests and switches `enableUnitTestCoverage` on.
+# `cashier` and `donau-verificator` carry none, so asking for them would only
+# fail the job for an empty result.
+./gradlew --no-daemon \
+ :taler-kotlin-android:testDebugUnitTest \
+ :merchant-lib:testDebugUnitTest \
+ :merchant-terminal:testSimUnitTest \
+ :wallet:testFdroidDebugUnitTest
+
+if [ ! -s "${CLI}" ]; then
+ curl -sSfL -o "${CLI}" \
+ "https://repo1.maven.org/maven2/org/jacoco/org.jacoco.cli/${JACOCO_VERSION}/org.jacoco.cli-${JACOCO_VERSION}-nodeps.jar"
+fi
+
+# Unit-test execution data, plus anything an emulator run left for us.
+EXEC_FILES=()
+while IFS= read -r f; do EXEC_FILES+=("${f}"); done < <(
+ find . -path '*/outputs/unit_test_code_coverage/*' -name '*.exec' | sort)
+if [ -d "${EMULATOR_EC_DIR}" ]; then
+ while IFS= read -r f; do EXEC_FILES+=("${f}"); done < <(
+ find "${EMULATOR_EC_DIR}" -name '*.ec' | sort)
+fi
+if [ "${#EXEC_FILES[@]}" -eq 0 ]; then
+ echo "no execution data; did the tests run?" >&2
+ exit 1
+fi
+
+MERGED="${WORK}/merged.exec"
+rm -f "${MERGED}"
+java -jar "${CLI}" merge "${EXEC_FILES[@]}" --destfile "${MERGED}"
+
+# Kotlin and Java classes live in separate trees per module and variant, and
+# both have to be the *uninstrumented* ones.
+CLASS_ARGS=()
+SOURCE_ARGS=()
+add_module() { # add_module <module> <variant>
+ local m="${1}" v="${2}"
+ for d in "${m}/build/tmp/kotlin-classes/${v}" \
+ "${m}/build/intermediates/javac/${v}/classes"; do
+ [ -d "${d}" ] && CLASS_ARGS+=(--classfiles "${d}")
+ done
+ [ -d "${m}/src/main/java" ] && SOURCE_ARGS+=(--sourcefiles "${m}/src/main/java")
+}
+add_module taler-kotlin-android debug
+add_module merchant-lib debug
+add_module merchant-terminal sim
+add_module wallet fdroidDebug
+
+[ "${#CLASS_ARGS[@]}" -gt 0 ] || { echo "no class files to report on" >&2; exit 1; }
+
+java -jar "${CLI}" report "${MERGED}" \
+ "${CLASS_ARGS[@]}" "${SOURCE_ARGS[@]}" \
+ --html "${ARTIFACT_PATH}/html" \
+ --xml "${WORK}/coverage.xml" \
+ --name "GNU Taler ${REPO_NAME} coverage report"
+
+# A landing page over the top, saying which lines no build of this type could
+# ever reach and what produced the figures. Never fatal: the report above is
+# the deliverable.
+cp "${WORK}/coverage.xml" "${ARTIFACT_PATH}/coverage.xml" || true
+# JaCoCo's own report goes under html/, the landing page sits at the top of
+# the artifact and links into it -- otherwise the two would both want to be
+# index.html and the summary would clobber the report.
+python3 pos-simulator/coverage/summary_html.py "${ARTIFACT_PATH}" \
+ "${EMULATOR_EC_DIR}" --title "GNU Taler ${REPO_NAME}" \
+ || echo "summary page not written" >&2
+
+chmod -R a+rX "${ARTIFACT_PATH}"
+
+# A local run has no route to the artifact host; PUBLISH=0 stops there with
+# the report on disk, which is what you want when testing the job itself.
+if [ "${PUBLISH:-1}" = "0" ]; then
+ echo "PUBLISH=0: report left at ${ARTIFACT_PATH}, not uploaded" >&2
+ exit 0
+fi
+
+RSYNC_HOST="taler.host.internal"
+RSYNC_PORT=424243
+RSYNC_PATH="incoming_taler/"
+RSYNC_DEST="rsync://${RSYNC_HOST}/${RSYNC_PATH}"
+
+rsync -rvP --port "${RSYNC_PORT}" "${ARTIFACT_PATH}" "${RSYNC_DEST}"
diff --git a/contrib/ci/jobs/5-coverage/job.sh b/contrib/ci/jobs/5-coverage/job.sh
@@ -0,0 +1,6 @@
+#!/bin/bash
+set -exuo pipefail
+
+job_dir=$(dirname "${BASH_SOURCE[0]}")
+
+"${job_dir}"/coverage.sh
diff --git a/merchant-lib/build.gradle b/merchant-lib/build.gradle
@@ -41,6 +41,10 @@ android {
debug {
minifyEnabled minify_debug
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+ // Unit-test coverage, so that contrib/ci/jobs/5-coverage can
+ // report this module on lcov.taler.net. Costs nothing when the
+ // tests are not run.
+ enableUnitTestCoverage true
}
}
compileOptions {
diff --git a/merchant-terminal/build.gradle b/merchant-terminal/build.gradle
@@ -58,6 +58,13 @@ android {
buildConfigField('String', 'SUMUP_AFFILIATE_KEY', JsonOutput.toJson(sumupAffiliateKey))
}
+ // The androidTest variant is only created for the testBuildType, and
+ // enableAndroidTestCoverage only instruments the app's classes when such a
+ // variant exists -- so the simulator's build type has to be the one.
+ // Nothing else in this module has instrumented tests, so this costs
+ // nothing but moves which unit-test task :merchant-terminal:check runs.
+ testBuildType "sim"
+
buildTypes {
release {
minifyEnabled true
@@ -67,6 +74,23 @@ android {
minifyEnabled minify_debug
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
+ // Build type for pos-simulator/, the emulator-driven exploration
+ // harness. Same application id as debug -- the simulator drives the
+ // same package a developer would install -- plus JaCoCo
+ // instrumentation and the hooks in src/sim. Never published.
+ sim {
+ initWith debug
+ signingConfig signingConfigs.debug
+ minifyEnabled false
+ enableAndroidTestCoverage true
+ // The emulator is not the only thing that covers this app: the
+ // module has ~290 JVM unit tests, and without this their coverage
+ // is invisible to pos-simulator's report -- so the report invites
+ // us to spend emulator time re-covering what a unit test already
+ // reaches. coverage/report.sh merges both.
+ enableUnitTestCoverage true
+ matchingFallbacks = ['debug']
+ }
}
compileOptions {
@@ -136,4 +160,13 @@ dependencies {
testImplementation 'org.robolectric:robolectric:4.16.1'
debugImplementation 'androidx.compose.ui:ui-tooling'
+ simImplementation 'androidx.compose.ui:ui-tooling'
+
+ // Only the "sim" build type has instrumented tests; see
+ // src/androidTestSim and pos-simulator/README.md. They exist so that AGP
+ // creates an androidTest variant, which is what makes
+ // enableAndroidTestCoverage instrument the app's classes.
+ androidTestSimImplementation 'junit:junit:4.13.2'
+ androidTestSimImplementation 'androidx.test:runner:1.7.0'
+ androidTestSimImplementation 'androidx.test.ext:junit:1.3.0'
}
diff --git a/merchant-terminal/src/androidTestSim/java/net/taler/merchantpos/sim/SimCoverageAnchorTest.kt b/merchant-terminal/src/androidTestSim/java/net/taler/merchantpos/sim/SimCoverageAnchorTest.kt
@@ -0,0 +1,54 @@
+/*
+ * This file is part of GNU Taler
+ * (C) 2026 Taler Systems S.A.
+ *
+ * GNU Taler is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU General Public License as published by the Free Software
+ * Foundation; either version 3, or (at your option) any later version.
+ *
+ * GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+ */
+
+package net.taler.merchantpos.sim
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * Not a test of the app: an anchor that makes AGP instrument it.
+ *
+ * "enableAndroidTestCoverage" only rewrites the application's classes when the
+ * module has an androidTest variant for the build type under test, and AGP
+ * only creates that variant for "testBuildType". Both are set for "sim" in
+ * build.gradle; this class exists so the variant has something in it.
+ *
+ * The simulator never runs this -- it drives the app from outside, over adb --
+ * so it deliberately asserts nothing about the terminal. What it does assert
+ * is that the instrumentation is actually present, which is the one thing that
+ * silently stops working and takes the whole coverage report with it.
+ */
+@RunWith(AndroidJUnit4::class)
+class SimCoverageAnchorTest {
+ @Test
+ fun jacocoAgentIsOnTheClasspath() {
+ val found =
+ try {
+ Class.forName("org.jacoco.agent.rt.RT")
+ true
+ } catch (e: ClassNotFoundException) {
+ false
+ }
+ assertTrue(
+ "no JaCoCo runtime in the sim variant: pos-simulator/coverage would be empty",
+ found,
+ )
+ }
+}
diff --git a/merchant-terminal/src/sim/AndroidManifest.xml b/merchant-terminal/src/sim/AndroidManifest.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="utf-8"?><!--
+ ~ This file is part of GNU Taler
+ ~ (C) 2026 Taler Systems S.A.
+ ~
+ ~ GNU Taler is free software; you can redistribute it and/or modify it under the
+ ~ terms of the GNU General Public License as published by the Free Software
+ ~ Foundation; either version 3, or (at your option) any later version.
+ ~
+ ~ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ ~ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ ~ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU General Public License along with
+ ~ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+ -->
+
+<!-- Hooks for the "sim" build type only: this manifest is not part of any
+ published variant. -->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+ <application android:networkSecurityConfig="@xml/network_security_config">
+ <receiver
+ android:name="net.taler.merchantpos.sim.PosSimHooks"
+ android:exported="true">
+ <intent-filter>
+ <action android:name="net.taler.merchantpos.sim.DUMP_COVERAGE" />
+ <action android:name="net.taler.merchantpos.sim.SET_CLIPBOARD" />
+ <action android:name="net.taler.merchantpos.sim.REPORT_NFC_PAYLOAD" />
+ <action android:name="net.taler.merchantpos.sim.REPORT_CLIPBOARD" />
+ </intent-filter>
+ </receiver>
+ </application>
+
+</manifest>
diff --git a/merchant-terminal/src/sim/java/net/taler/merchantpos/sim/PosSimHooks.kt b/merchant-terminal/src/sim/java/net/taler/merchantpos/sim/PosSimHooks.kt
@@ -0,0 +1,212 @@
+/*
+ * This file is part of GNU Taler
+ * (C) 2026 Taler Systems S.A.
+ *
+ * GNU Taler is free software; you can redistribute it and/or modify it under the
+ * terms of the GNU General Public License as published by the Free Software
+ * Foundation; either version 3, or (at your option) any later version.
+ *
+ * GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+ */
+
+package net.taler.merchantpos.sim
+
+import android.content.BroadcastReceiver
+import android.content.ClipData
+import android.content.ClipboardManager
+import android.content.Context
+import android.content.Intent
+import android.nfc.NdefMessage
+import android.util.Log
+
+import java.io.File
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * The three things the POS simulator cannot do from outside the app.
+ *
+ * Everything else it needs -- wiping data, delivering a taler-pos:// setup
+ * URI, reading the view hierarchy, reading the log -- is already reachable
+ * over adb, so it stays out of here. This receiver exists only in the "sim"
+ * build type.
+ *
+ * Coverage:
+ *
+ * adb shell am broadcast -a net.taler.merchantpos.sim.DUMP_COVERAGE \
+ * -n net.taler.merchantpos/net.taler.merchantpos.sim.PosSimHooks
+ * adb exec-out run-as net.taler.merchantpos cat files/coverage.ec > ep.ec
+ *
+ * Clipboard, for text "input text" cannot type at all (it maps characters
+ * through a KeyCharacterMap and throws on anything non-ASCII):
+ *
+ * adb shell am broadcast -a net.taler.merchantpos.sim.SET_CLIPBOARD \
+ * -n net.taler.merchantpos/net.taler.merchantpos.sim.PosSimHooks \
+ * --es text 'Kaffee à l’italienne'
+ * adb shell input keyevent KEYCODE_PASTE
+ *
+ * The clipboard, read back. The payment and refund screens show their URI
+ * only as a QR code, which a view-hierarchy dump cannot read -- but both
+ * screens also offer a copy button, and the clipboard may only be read by the
+ * foreground app, which this receiver runs in. So: tap Copy, then
+ *
+ * adb shell am broadcast -a net.taler.merchantpos.sim.REPORT_CLIPBOARD \
+ * -n net.taler.merchantpos/net.taler.merchantpos.sim.PosSimHooks
+ *
+ * and the URI the customer would scan appears in the log.
+ *
+ * The NFC payload, which is the POS's half of tap-to-pay. The terminal is
+ * the card here, not the reader: it hands the wallet a pay URI over host card
+ * emulation, and nothing outside the process can see what it published. This
+ * reports it to the log the same way:
+ *
+ * adb shell am broadcast -a net.taler.merchantpos.sim.REPORT_NFC_PAYLOAD \
+ * -n net.taler.merchantpos/net.taler.merchantpos.sim.PosSimHooks
+ *
+ * On an emulator it always answers "none": `TalerNfcService.setUri` returns
+ * early when the device has no NFC adapter, and no emulator image provides
+ * one. That is the terminal behaving correctly, so an oracle must not read
+ * it as a missing payment code -- it is why the clipboard hook exists.
+ */
+class PosSimHooks : BroadcastReceiver() {
+ override fun onReceive(context: Context, intent: Intent) {
+ when (intent.action) {
+ ACTION_DUMP_COVERAGE -> dumpCoverage(context, intent.getStringExtra("file"))
+ ACTION_SET_CLIPBOARD -> setClipboard(context, intent.getStringExtra("text"))
+ ACTION_REPORT_NFC_PAYLOAD -> reportNfcPayload()
+ ACTION_REPORT_CLIPBOARD -> reportClipboard(context)
+ else -> Log.w(TAG, "ignoring ${intent.action}")
+ }
+ }
+
+ /**
+ * Ask the JaCoCo runtime for the data collected so far and write it next to
+ * the app's files, where "run-as <pkg> cat" can reach it. Reflection keeps
+ * this compiling in build types without the agent on the classpath.
+ */
+ private fun dumpCoverage(context: Context, name: String?) {
+ val out = File(context.filesDir, name ?: "coverage.ec")
+ try {
+ val rt = Class.forName("org.jacoco.agent.rt.RT")
+ val agent = rt.getMethod("getAgent").invoke(null)
+ val data =
+ agent.javaClass
+ .getMethod("getExecutionData", Boolean::class.javaPrimitiveType)
+ .invoke(agent, false) as ByteArray
+ out.writeBytes(data)
+ Log.i(TAG, "coverage: ${data.size} bytes to ${out.absolutePath}")
+ } catch (e: Throwable) {
+ // A missing agent is a build configuration problem, so say so
+ // loudly rather than silently producing no coverage.
+ Log.e(TAG, "no JaCoCo agent: is enableAndroidTestCoverage set?", e)
+ }
+ }
+
+ /**
+ * Put text on the clipboard so the driver can paste it into a field.
+ *
+ * Only the foreground app may write the clipboard on Android 10 and later,
+ * which is fine here: the simulator pastes into the screen it is looking
+ * at.
+ */
+ private fun setClipboard(context: Context, text: String?) {
+ if (text == null) {
+ Log.w(TAG, "SET_CLIPBOARD without text")
+ return
+ }
+ val manager = context.getSystemService(ClipboardManager::class.java)
+ manager.setPrimaryClip(ClipData.newPlainText("taler-pos-sim", text))
+ Log.i(TAG, "clipboard set to ${text.length} chars")
+ }
+
+ /**
+ * Print what is on the clipboard.
+ *
+ * This is how the harness reads a URI the terminal only renders as a QR
+ * code: the screen's copy button puts it on the clipboard, and a
+ * background process cannot read the clipboard but the app itself can.
+ */
+ private fun reportClipboard(context: Context) {
+ val manager = context.getSystemService(ClipboardManager::class.java)
+ val clip = manager.primaryClip
+ if (clip == null || clip.itemCount == 0) {
+ Log.i(TAG, "$CLIP_PREFIX none")
+ return
+ }
+ val text = clip.getItemAt(0).coerceToText(context).toString()
+ Log.i(TAG, "$CLIP_PREFIX $text")
+ }
+
+ /**
+ * Print the URI the terminal is currently offering over host card
+ * emulation, if any.
+ *
+ * TalerNfcService keeps it in a private static AtomicReference and exposes
+ * no getter, so this reads the field reflectively rather than widening the
+ * library's API for a test harness. A null payload is reported as such:
+ * "the terminal published nothing" is exactly what one oracle is looking
+ * for.
+ */
+ private fun reportNfcPayload() {
+ val payload =
+ try {
+ val cls = Class.forName("net.taler.lib.android.TalerNfcService")
+ val field = cls.getDeclaredField("ndefMessage").apply { isAccessible = true }
+
+ @Suppress("UNCHECKED_CAST")
+ val ref = field.get(null) as AtomicReference<NdefMessage?>
+ ref.get()
+ } catch (e: Throwable) {
+ Log.e(TAG, "could not read the NFC payload", e)
+ return
+ }
+ if (payload == null) {
+ Log.i(TAG, "$NFC_PREFIX none")
+ return
+ }
+ // An NDEF URI record stores the scheme as a one-byte prefix code
+ // followed by the rest of the URI; code 0 means "no abbreviation", and
+ // taler:// is not in the abbreviation table, so that is what the POS
+ // writes. Decoding it generically keeps this honest if that changes.
+ val record = payload.records.firstOrNull()
+ if (record == null) {
+ Log.i(TAG, "$NFC_PREFIX empty-message")
+ return
+ }
+ val bytes = record.payload
+ val prefix = URI_PREFIXES.getOrElse(bytes.firstOrNull()?.toInt() ?: 0) { "" }
+ val rest = String(bytes, 1, bytes.size - 1, Charsets.UTF_8)
+ Log.i(TAG, "$NFC_PREFIX $prefix$rest")
+ }
+
+ companion object {
+ private const val TAG = "PosSimHooks"
+ const val ACTION_DUMP_COVERAGE = "net.taler.merchantpos.sim.DUMP_COVERAGE"
+ const val ACTION_SET_CLIPBOARD = "net.taler.merchantpos.sim.SET_CLIPBOARD"
+ const val ACTION_REPORT_NFC_PAYLOAD = "net.taler.merchantpos.sim.REPORT_NFC_PAYLOAD"
+ const val ACTION_REPORT_CLIPBOARD = "net.taler.merchantpos.sim.REPORT_CLIPBOARD"
+
+ /** The markers the driver greps for. */
+ private const val NFC_PREFIX = "nfc-payload:"
+ private const val CLIP_PREFIX = "clipboard:"
+
+ /** NFC Forum URI record prefix codes, enough of them to be correct. */
+ private val URI_PREFIXES =
+ listOf(
+ "",
+ "http://www.",
+ "https://www.",
+ "http://",
+ "https://",
+ "tel:",
+ "mailto:",
+ "ftp://anonymous:anonymous@",
+ "ftp://ftp.",
+ "ftps://",
+ )
+ }
+}
diff --git a/merchant-terminal/src/sim/res/raw/sim_ca.crt b/merchant-terminal/src/sim/res/raw/sim_ca.crt
@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDizCCAnOgAwIBAgIUBcwRvFUuVsajhrVa7ULaBCH41Y4wDQYJKoZIhvcNAQEL
+BQAwTTEfMB0GA1UEAwwWVGFsZXIgUE9TIHNpbXVsYXRvciBDQTESMBAGA1UECgwJ
+R05VIFRhbGVyMRYwFAYDVQQLDA1wb3Mtc2ltdWxhdG9yMB4XDTI2MTAyOTA4NTAw
+NloXDTM2MTAyNjA4NTAwNlowTTEfMB0GA1UEAwwWVGFsZXIgUE9TIHNpbXVsYXRv
+ciBDQTESMBAGA1UECgwJR05VIFRhbGVyMRYwFAYDVQQLDA1wb3Mtc2ltdWxhdG9y
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy1836CaICQy2ZPD7mXxz
+tSsYIcCK9J5AxOEEZ7+wJUOHXmTO95YGyBUm1UjClQD8K1l8q6EF8QA+wRN7tcEJ
+WfpLXM2yNBGM+K+pgi4Q+dRQ2VzgdrPwg7VNe5IDW1mfUb/in7J8KpujfS1xTHlO
+pTZhWYhjgDZZ0s2kiIRq9nRvmHxowxqCtKYarS5p4N6wOX+Fdl1GkkU8+LwUve89
+mz/E5AD5YpS+DDu20IAu7wpJLJjW99JwtAIwYyaWmWqnKCZjiq46kNSTZ9aYC9z0
+c3SGVKjmOq3y1yHj+1jQassPEhmh5C38xPGG2xGM6lv8CuCsj1GZl/5Ii87M93I1
+hwIDAQABo2MwYTAdBgNVHQ4EFgQUwyWynf2xYyHKwo+cwyW4rW+TWsAwHwYDVR0j
+BBgwFoAUwyWynf2xYyHKwo+cwyW4rW+TWsAwDwYDVR0TAQH/BAUwAwEB/zAOBgNV
+HQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQELBQADggEBAH/TGHkLCk1srBN9MJZIC+jM
+7kSeluyAS8jOTTHD7KfTyskCzIbGh7I2YLxOvMAHY5+a3V1rKyEZaxmTxK66tMPZ
+g9cCzHssWI5ZHopaPc57D1CqIcCJuoFIxxNwv9YzIsft9Jwk0LHj+vplCiyhfZrP
+zsXeFH0YWkfGm1Q5GZIAN6SB99rVvDPV0OE/WmpLO4i5gc55KPqaRFFOGi3ZgSOr
+lmB375sk9K2Z3q+AqZgf3qIecChQLOD25PjX6TVS17r7gGXl/WC3YG/WkN+WM/hA
+QinLnOWBMwCm/gXbLpcKMQqWYF52yxOuanh+fX2LEqP0ZDGYg1MlmSOj0GrfdDM=
+-----END CERTIFICATE-----
diff --git a/merchant-terminal/src/sim/res/xml/network_security_config.xml b/merchant-terminal/src/sim/res/xml/network_security_config.xml
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Network policy for the "sim" build type only (pos-simulator/, never
+ published).
+
+ The terminal hard-codes https:// for the merchant portal URL. Both the login
+ form and the taler-pos:// setup URI build the base URL with that scheme and
+ nothing else, so a merchant backend the harness controls has to answer TLS.
+ The extra trust anchor is the simulator's own CA, which fronts the mock
+ backend on https://localhost:[port]. See pos-simulator/tls/; the matching
+ private key is generated per installation and is not in the tree, so this
+ certificate on its own authorises nobody.
+-->
+<network-security-config>
+ <base-config>
+ <trust-anchors>
+ <certificates src="system" />
+ <certificates src="user" />
+ <certificates src="@raw/sim_ca" />
+ </trust-anchors>
+ </base-config>
+ <domain-config cleartextTrafficPermitted="true">
+ <domain includeSubdomains="true">localhost</domain>
+ </domain-config>
+</network-security-config>
diff --git a/pos-simulator/.gitignore b/pos-simulator/.gitignore
@@ -0,0 +1,7 @@
+# Generated on the host that runs the simulator, not in the tree.
+out/
+run/
+avd/
+apk/
+__pycache__/
+*.pyc
diff --git a/pos-simulator/README.md b/pos-simulator/README.md
@@ -0,0 +1,724 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# POS simulator
+
+Drives the Android merchant terminal (`merchant-terminal`, "Taler POS") in an
+emulator against a real merchant backend and a real customer wallet, to measure
+how much of the app gets exercised and to find sequences that end in a crash, a
+dialog that explains nothing, or a screen the cashier cannot get out of.
+
+It is the sibling of `simulator/`, which does the same for the wallet, and
+borrows that harness's shape -- `device.py`, `episode.py`, `oracles.py`,
+scenarios, coverage -- but almost none of its content. Three things are
+genuinely different, and they shape everything here:
+
+* **The terminal does almost nothing by itself.** Every interesting screen is
+ waiting for a customer to scan a code, confirm a contract or take a refund --
+ or to fail to. So the harness has to *be* that customer, which it does with
+ `taler-wallet-cli` and an account at the demo bank.
+* **It has no wallet-core.** There is no error-code registry to lean on; every
+ judgement comes from the screen, the log and the backend. The backend is
+ itself an oracle: what an order really is, as against what the terminal says
+ it is.
+* **It needs a merchant who is set up.** Half of what can go wrong is the
+ *merchant's* configuration, not the terminal's state -- no bank account, no
+ products, the wrong currency, a token that expires. Arranging those is a
+ first-class part of the harness rather than an afterthought.
+
+## Where it runs
+
+On `tripwire.taler.net`, with everything volatile in its tmpfs:
+
+```
+tripwire:/tmp/taler-pos-sim/
+ env.sh sets POS_SIM_ROOT, the SDK paths, the wallet CLI
+ emu/emu.sh AVD lifecycle, one AVD per worker
+ driver/ the harness
+ backend/mockd.py a merchant backend that answers however a scenario needs
+ tls/ the CA the "sim" build trusts, and its server cert
+ apk/pos.apk pushed from a build host
+ avd/ run/ out/ AVDs, logs and coverage, episode artifacts
+```
+
+The root filesystem on that box is shared with several other projects and is
+full, so **nothing here is written to disk**: `POS_SIM_ROOT` is `/tmp`, which is
+a 126 GB tmpfs on a machine with 251 GB of RAM, and an AVD's data partition is
+sparse. A worker costs a few GB of RAM and nothing on disk. Nothing needs to
+survive a reboot -- the code is in git and findings are copied out as they are
+made.
+
+Push the harness and the APK with
+
+```bash
+rsync -a --exclude __pycache__ pos-simulator/ root@tripwire.taler.net:/tmp/taler-pos-sim/
+rsync -a merchant-terminal/build/outputs/apk/sim/merchant-terminal-sim.apk \
+ root@tripwire.taler.net:/tmp/taler-pos-sim/apk/pos.apk
+```
+
+## Running it
+
+```bash
+ssh root@tripwire.taler.net
+cd /tmp/taler-pos-sim && . ./env.sh
+
+emu/emu.sh create 0 # once per worker
+emu/emu.sh boot 0 # ~35 s
+emu/emu.sh prepare 0 # install the APK, kill animations, grant the camera
+
+cd driver
+python3 smoke.py # six checks, in the order in which a failure stops
+ # being the harness's fault
+```
+
+`smoke.py` is the thing to run after every deploy. It provisions a terminal
+from the demo backend, bills an order on the keypad, reads the pay URI off the
+screen, pays it with a real wallet funded from the demo bank, and waits for
+"Payment received". A scenario failing on a harness that never passed its smoke
+test says nothing.
+
+Then the scenarios:
+
+```bash
+python3 suite.py --list
+python3 suite.py login_demo_credentials order_amount_pay
+python3 suite.py --all --skip-tag mock # everything on the demo backend
+python3 suite.py --tag mock # everything on a backend of our own
+python3 suite.py --tag fault # everything through twister
+python3 campaign.py suite --workers 2 # both of those, side by side
+python3 explore.py --steps 200 --seed 7 --faults
+python3 report.py --notes
+python3 report.py --kinds
+```
+
+Coverage reports are built where the APK was built, because they need the
+uninstrumented classes and the sources. `report.sh` writes three things: a
+landing page, JaCoCo's own report, and the same again with the JVM unit tests
+merged in.
+
+```bash
+rsync -a root@tripwire.taler.net:/tmp/taler-pos-sim/run/coverage/ /tmp/pos-ec/
+JAVA_HOME=/home/claude/jdk-17 pos-simulator/coverage/report.sh /tmp/pos-ec
+python3 pos-simulator/coverage/gaps.py pos-simulator/out/coverage/coverage.xml
+```
+
+`out/coverage/index.html` is the one to open. JaCoCo already writes the
+lcov-`genhtml` equivalent -- a source-annotated page per class, green and red
+down the gutter -- and the landing page sits over it to say the two things
+JaCoCo cannot know:
+
+* **which of the red lines are worth anyone's time.** JaCoCo paints a
+ screenshot-only composable the same red as a real gap, so its totals and
+ `gaps.py`'s disagree by a couple of points. The ranking on the landing page
+ is by *reachable* misses, and it names what it left out.
+* **what produced the figures** -- how many execution-data files, from which
+ scenarios, against which commit. A coverage number with no provenance is a
+ number somebody quotes six weeks later without knowing it came from a
+ half-finished run.
+
+It is a single self-contained file with no external assets, so it survives
+`rsync` and opens from a `file://` path.
+
+## The app under test
+
+The simulator drives the **`sim` build type** of `merchant-terminal`
+(`./gradlew :merchant-terminal:assembleSim`), which is `debug` plus three
+things:
+
+* `enableAndroidTestCoverage`, so the APK carries the JaCoCo agent and
+ `driver/coverage.py` can ask it for execution data mid-session;
+* `merchant-terminal/src/sim/`, a receiver (`PosSimHooks`) for the three things
+ adb cannot do -- dumping that coverage, putting non-ASCII text on the
+ clipboard, and reading the clipboard *back*;
+* a `network_security_config` with one extra trust anchor, the simulator's own
+ CA, so the terminal can be pointed at a backend the harness controls.
+
+It keeps the `net.taler.merchantpos` application id, so the package driven is
+the same one a developer would install, and it is never published.
+
+`testBuildType "sim"` is what makes AGP create an androidTest variant for this
+build type (and therefore instrument the app's classes at all). It also moves
+which unit-test task `:merchant-terminal:check` resolves to --
+`testSimUnitTest` rather than `testDebugUnitTest`. `sim` is `initWith debug`,
+so the same tests run against the same code, and CI asks for
+`:merchant-terminal:check` rather than a task name.
+
+### Reading the QR code off the screen
+
+The payment and refund screens show their URI only as a QR code, which a
+view-hierarchy dump cannot read. Both screens also offer a copy button, and the
+clipboard may only be read by the foreground app -- which is where
+`PosSimHooks` runs. So `Pos.copy_displayed_uri()` taps Copy and asks the hook,
+and the harness sees exactly the string a customer's wallet would get. The copy
+button gets exercised on the way, which is a small bonus.
+
+The terminal also publishes the same URI over host card emulation, and the
+hooks can read that too (`REPORT_NFC_PAYLOAD`). On an emulator it is always
+absent: `TalerNfcService.setUri` returns early when the device has no NFC
+adapter, and no emulator system image provides one. So that hook is a check
+that the terminal is *not* claiming an NFC payment is possible, not a way to
+read the pay URI.
+
+### The terminal is *no longer* landscape-locked
+
+It declared `screenOrientation="landscape"` through round three and declares
+**`fullUser`** on master, so portrait stopped being dead code and nothing
+noticed: `PortraitOrderScreen`, `PortraitPaymentScreen` and
+`PortraitRefundUriScreen` had never been composed, and neither had any of the
+`maxWidth > maxHeight` branches beside them.
+
+```python
+dev.rotate(portrait=True) # and back with portrait=False
+dev.is_portrait()
+```
+
+Three things this harness got wrong while the lock was real and had to unlearn:
+
+* **`wm size` does not move when the device turns.** It reports the panel. The
+ app's window is the authority, which is why `Device.size()` prefers the view
+ hierarchy's root bounds -- that part was right all along. What was wrong was
+ `size()` and `display_size()` *forcing* landscape by swapping the axes.
+* **Which `user_rotation` value means portrait depends on the panel.** Every
+ AVD `emu.sh` creates is landscape-natural, so 0 is landscape and 1 is
+ portrait; a stock phone AVD is the other way round. `rotate()` therefore
+ tries a value, measures the window, and tries the other if that was not it,
+ with a budget for each -- giving up on a value after one dump turned a
+ correct value into a wrong one, because the first dump after the write is
+ usually taken before the window manager has resized anything.
+* **A scenario that turns the device must not leak that.** `fresh_start`
+ puts every scenario back to landscape (or to `POS_PORTRAIT`), so a scenario
+ that fails mid-rotation cannot leave twenty others quietly testing the other
+ half of five layouts under their own names.
+
+Rotating *during* a flow is the more interesting half: a configuration change
+destroys and recreates every composition, so anything held in a `remember`
+rather than a `rememberSaveable` or a ViewModel is lost -- and for a
+landscape-locked app that could never happen, so none of it had ever been
+checked. `rotate_mid_payment` and `rotate_mid_checkout` are that test.
+
+## The two backends
+
+### The demo backend, for everything that has to be real
+
+`https://backend.demo.taler.net`, instance `sandbox`, password `sandbox` --
+which is also what the terminal's own "Fill demo credentials" button types.
+That instance is shared and already carries a large inventory and a long order
+history, which is exactly what makes it worth testing against: the terminal's
+pagination, its stock badges and its history list never see that much data on a
+stack the harness builds itself. Nothing the harness does to it goes beyond
+adding orders and refunds of its own.
+
+`driver/merchant.py` is the back office: it mints access tokens (including ones
+that expire, which the terminal cannot ask for itself -- the login form
+hard-codes `TokenDuration.Forever`), revokes them, creates orders with a pay or
+refund deadline the harness chooses, claims an order without paying it, and
+reads back what an order really is.
+
+`driver/counterparty.py` is the customer: a registered account at
+`https://bank.demo.taler.net` and a `taler-wallet-cli` database. It can pay,
+claim-and-hesitate, walk away, and accept a refund.
+
+### A fresh instance needs an emailed TAN
+
+Self-provisioning is enabled on the demo backend
+(`have_self_provisioning: true`), but `mandatory_tan_channels` is `["email"]`,
+so `POST /instances` answers `202` with an email challenge that the harness
+cannot solve on its own:
+
+```json
+{"combi_and": true,
+ "challenges": [{"tan_channel": "email", "challenge_id": "249-XGVEK..."}]}
+```
+
+`Merchant.provision_instance` raises with that challenge attached rather than
+swallowing it. If a real fresh instance on the demo backend is wanted, somebody
+has to forward the TAN; everything the harness needs a fresh or broken instance
+*for* is covered by the mock instead.
+
+### The mock backend, for a merchant who is not set up
+
+`backend/mockd.py` is a few hundred lines of HTTP that speaks just enough of the
+merchant API for the terminal to configure itself and create an order, with a
+profile per way a merchant can be wrong:
+
+| Profile | What it is |
+| --- | --- |
+| `healthy` | a small, correct instance: two categories, three products |
+| `fresh` | provisioned and never stocked: no categories, no products |
+| `no-bank-account` | order creation fails the way it does with no wire account |
+| `wrong-currency` | products priced in a currency the instance does not use |
+| `bad-category` | a product referencing a category id that does not exist |
+| `version-old` / `version-new` | a backend outside the terminal's version range |
+| `malformed` | `/private/pos` that is not the JSON the terminal expects |
+| `empty-reply` | `/private/pos` that answers 200 with nothing at all |
+| `slow` | every reply delayed past the terminal's patience |
+| `expire-after-3` | the token stops working on the fourth request |
+| `huge-inventory` | four hundred products, to see what the grid does |
+| `unicode` | product names in scripts the layout was not designed around |
+| `inventory-gone` | the product sold out between the tap and the order |
+| `insecure-pay-uri` | pay URIs with the `taler+http://` scheme |
+| `mfa-two-channels` | logging in needs a code, by email or by SMS |
+| `mfa-both-required` | logging in needs a code from each of two channels |
+
+```bash
+python3 backend/mockd.py --list
+python3 backend/mockd.py --profile fresh --port 19443
+```
+
+`healthy` speaks protocol **42**, so the mixed-payment checkout is available
+against it, and `mockd.py` answers `POST /private/orders/<id>/collect` and
+`POST /private/orders/<id>/refund-external` -- the two calls a cash sale ends
+on. Both can be made to fail (`collect-fails`, `external-refund-fails`), which
+is the point: they happen *after* the cashier has taken real money, and until
+the mock could refuse them nothing had ever seen the terminal handle that.
+The mock's own memory is the oracle -- `c.mock.state.orders[id].collected` is
+what the backend was actually asked to do, as against what the screen says.
+
+**It has to answer TLS.** The terminal builds its merchant URL by hard-coding
+`https://` -- in `ConfigFragment.sanitizeMerchantUrlAndUpdateFields` and in
+`MainActivity.handleSetupIntent` both -- so a plain-http mock is unreachable
+without patching the app, which would mean testing something other than the
+app. `tls/` holds a CA, generated per installation, and a certificate for
+`localhost`; the CA's certificate is in the `sim` build's trust anchors and the
+private key is not in the tree, so that certificate on its own authorises
+nobody.
+
+Regenerate them with:
+
+```bash
+cd pos-simulator/tls
+openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt -days 3650 \
+ -subj '/CN=Taler POS simulator CA/O=GNU Taler/OU=pos-simulator' \
+ -addext 'basicConstraints=critical,CA:TRUE' \
+ -addext 'keyUsage=critical,keyCertSign,cRLSign'
+openssl req -newkey rsa:2048 -nodes -keyout srv.key -out srv.csr -subj '/CN=localhost'
+openssl x509 -req -in srv.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
+ -out srv.crt -days 3650 -extfile srv.ext
+cp ca.crt ../../merchant-terminal/src/sim/res/raw/sim_ca.crt
+```
+
+and rebuild the APK, because the trust anchor is compiled into it.
+
+The mock listens on `127.0.0.1` and the driver maps its port into the emulator
+with `adb reverse`, so `https://localhost:<port>` means the same thing on both
+sides. Port 8443 on tripwire belongs to something else; the default here is
+`19443 + worker`.
+
+A mock scenario provisions through the **login form** rather than a setup URI,
+because a setup URI loses the port -- see
+`findings/setup-uri-drops-the-port.md`.
+
+The `mfa-*` profiles are worth singling out. `backend.demo.taler.net` has
+`mandatory_tan_channels: ["email"]`, so a login there is answered 202 with a
+challenge and the code is **mailed** -- which is why round one could not reach
+the two-factor path and said so. The mock is that backend with a code the
+harness already knows, and the terminal cannot tell the difference: the whole
+dance is four requests and one header. Only two statuses on the confirm are
+recoverable -- 409 is "wrong code, ask again" and 429 is "too many attempts, a
+new code is on its way" -- so the mock answers 409 twice and then 429, and one
+scenario walks both arms of `MfaUtils.handleChallengeConfirmError`.
+
+### Twister, for a real backend having a bad day
+
+The mock answers like a merchant who is *configured* wrong. What it cannot do
+is be the real backend and then go wrong, because every word it says is a word
+the harness wrote. `taler-twister` -- the fault-injecting proxy GNU Taler's C
+test suites use -- sits in front of the demo backend and mutates the next
+request or response on command: a status code, a deleted field, a replaced
+value, a flipped character inside a string, a truncated body, a changed header.
+Everything else in the exchange stays real.
+
+That is where the terminal's error handling actually lives.
+`Response.getFailureString` picks one of five arms by exception type and
+`fallbackStatusMessage` one of seven by status code, and a correctly behaving
+backend reaches none of them.
+
+`driver/faults.py` is the wrapper. Two things had to be bridged:
+
+* **TLS.** Twister is a plain HTTP proxy and the terminal hard-codes `https://`.
+ `faults.TlsFront` terminates TLS with the same certificate the mock uses and
+ relays bytes to twister. A byte relay is enough -- nothing in the middle
+ needs to understand the HTTP it carries, so keep-alive, chunked bodies and
+ uploads pass through untouched.
+* **One mutation, one request.** A twister mutation is consumed when it fires,
+ which suits a test script making one call at a time and does not suit a
+ screen that polls. `Twister.sustain()` re-arms in a loop for the duration of
+ a block; without it the insecure-pay-URI dialog opens on one poll and the
+ next poll closes it again.
+
+`TlsFront` also injects what twister has no notion of, because it happens below
+HTTP: a connection that closes in the middle of a response body, or one that is
+reset while the request is still going up. That is the only route to the
+`IOException` arm of `getFailureString` -- no status code produces it, and an
+unreachable host fails earlier and differently.
+
+Twister is **not built in this workspace's shared prefix**; it is built on the
+emulator host against that host's system GNUnet, because that is where the
+driver runs:
+
+```bash
+ssh root@tripwire.taler.net
+mkdir -p /tmp/twister-build && cd /tmp/twister-build
+# ... unpack a twister checkout into src/ ...
+cd src && ./bootstrap && ./configure --with-gnunet=/usr \
+ --prefix=/tmp/twister-build/inst && make -j8 && make install
+```
+
+`POS_TWISTER_PREFIX` points the driver at it and `faults.available()` is what
+the `fault` scenarios check before claiming to have tested anything. The ports
+are `18880 + worker` for twister itself, which the device never sees, and
+`19473 + worker` for the TLS front, which is the one `adb reverse` maps in.
+
+### The mixed-payment checkout, which has to be turned on first
+
+Master's `24f7b249` put a checkout between the order and the payment screen:
+cash and card are collected first, each recorded as it is taken, and Taler
+pays whatever is still open. None of that code runs while Taler is the only
+payment option, which is the terminal's own default -- so a scenario has to
+turn one on before it can test any of it:
+
+```python
+c.provision_demo()
+c.app.set_payment_option("Cash", True) # Settings -> Manage payment options
+c.app.goto("amount"); c.app.enter_amount("7.00")
+c.app.charge_to_checkout() # not charge(): the QR comes later
+c.app.record_cash("10.00") # returns the "Give change" dialog
+c.app.checkout_finish_with_taler() # or checkout_tile("^Complete payment$")
+```
+
+It also needs a backend of **protocol 42 or newer** (`MIXED_PAYMENTS_PROTOCOL`
+in `CheckoutManager`). `backend.demo.taler.net` reports `42:0:30`, so the demo
+instance is enough; `mockd.py` does not speak it yet, which is why the
+checkout scenarios cannot be parallelised across workers.
+
+### A catalogue the terminal cannot answer for itself
+
+`driver/inventory.py` puts six deliberately awkward products on the *demo*
+instance and leaves them there, named `possim-*` so a passer-by can see where
+they came from: a real PNG, a description no column fits, a fraction of a
+kilogram, four scripts and an emoji, one cent, and nothing at all. They live
+in a category of their own ("POS simulator"), which exercises the category
+tabs on the way.
+
+The mock can answer anything, which is exactly why it cannot settle what the
+order grid, the order-details page and the receipt do with a product that a
+real merchant really sold: the mock's products are never bought, never
+recorded in a contract and never read back out of an order.
+
+```bash
+python3 driver/inventory.py ensure # idempotent; run before a round
+python3 driver/inventory.py show
+python3 driver/inventory.py remove
+```
+
+### A phone, for the other half of five screens
+
+Five of the terminal's screens choose their layout at runtime on
+`smallestScreenWidthDp >= 720` -- the order grid, the payment screen, the refund
+URI screen, the QR config tab and the amount keypad, the last on `>= 600` and
+with a third arm for a short screen. On a tablet-sized emulator the phone half
+of each is simply never executed, and it is the larger half of several of those
+files.
+
+The device profile does not settle this: `emu.sh` writes the LCD geometry into
+the AVD and that is what the app sees. So a phone worker is
+
+```bash
+POS_AVD_DEVICE=medium_phone POS_LCD_WIDTH=1920 POS_LCD_HEIGHT=1080 \
+ POS_LCD_DENSITY=420 emu/emu.sh create 3
+```
+
+which is 731x411dp -- a phone on the short edge, and short enough on the other
+for the keypad's compact arm as well.
+
+## The three ways it drives the app
+
+**Scenarios** (`driver/suite.py`, 45 of them) walk one feature each,
+deliberately: provisioning by form, by setup URI in both of its shapes, and by
+QR tab; sessions that expire or are revoked, mid-payment and mid-idle; orders by
+amount and by inventory; the keypad's edges; payment, cancellation, claim
+without payment and force delete; the history list and its pagination against a
+long history; refunds in full and every amount that must be refused; every
+settings row and every language; a merchant with no products, the wrong
+currency, a dangling category, a malformed reply, a version mismatch, four
+hundred products and names in eight scripts; and the environment turning
+against it -- airplane mode, process death, back from everywhere.
+
+Tags say what a scenario needs: `demo` the shared demo instance, `mock` a
+backend of its own, `pay` a funded customer wallet, `fault` twister in front
+of a real backend, `slow` minutes rather than seconds.
+
+Three tags say what *kind of worker* a scenario needs, because running it
+anywhere else makes it pass without proving anything:
+
+| tag | why |
+| --- | --- |
+| `form` | it is about the login form, which is unusable on a phone (11971), so it must have a tablet |
+| `phone` | it is about the phone half of a layout; on a tablet `login_form_fits_a_phone` is green because the form fits |
+| `portrait` | it turns the device, and `fresh_start` puts every other scenario back |
+
+`campaign.py` routes the first two: `form` scenarios join worker 0 (a tablet
+by convention) and `phone` ones go to the first worker named in
+`POS_PHONE_WORKERS` (default `1,2`), with worker 0 skipping them. Get this
+wrong and the result is not a failure but a false pass, which is worse --
+both portrait scenarios shipped testing landscape, and one of them reported
+green.
+
+A scenario that cannot reach its feature fails loudly (`Ctx.require`) instead of
+reporting a green row for having done nothing. `Ctx.expect` is the other half:
+`require` guards the harness ("I could not get to the payment screen, so I have
+tested nothing"), `expect` judges the app ("I got there and it was wrong") and
+turns a failure into a finding.
+
+**Exploration** (`driver/explore.py`) takes over where the scenarios end: from a
+configured, already-used terminal it picks a control at random, biased towards
+what it has not pressed, types a price or something that is not a price into
+whatever field it lands on, and optionally mixes in faults.
+
+**The counterparty** is in both: a scenario that does not involve a customer is
+testing a terminal nobody is buying anything from.
+
+## What counts as a finding
+
+`driver/oracles.py` is the contract. An ordinary error is not a finding -- a
+terminal pointed at a backend that is down is supposed to say so, and a refund
+larger than the order is supposed to be refused. A finding is the terminal
+breaking its own contract:
+
+* a crash, an ANR, a native abort, a `NetworkOnMainThreadException`, or the
+ `KotlinNullPointerException` that `configManager.merchantConfig!!` becomes
+ when a session ends mid-request;
+* a dialog that names no cause the cashier can act on -- the catch-all
+ "Error: Invalid configuration", a dialog whose message never arrived, or one
+ quoting a Ktor exception;
+* an unsubstituted format string, a stray `null`, a resource name or an
+ exception class name shown as a label, or a currency word glued to a number;
+* a screen with nothing to read and nothing to tap, or one still saying "please
+ wait" after 75 seconds;
+* a control a screen reader cannot announce;
+* a primary action that changed nothing on screen while the log reported a
+ backend error;
+* a payment code the customer cannot use -- absent, insecure, or for a
+ different order than the backend created;
+* a history row that contradicts what the order is at the backend;
+* an unpaid order the terminal created and left behind.
+
+Each one is written to the episode directory with a screenshot, the logcat tail,
+the screen's labels, the notes the scenario recorded about what it had arranged,
+and the full action list -- and fingerprinted, so repeats collapse.
+
+## Tools
+
+| Tool | What it is for |
+| --- | --- |
+| `driver/smoke.py` | does any of this work at all |
+| `driver/probe.py` | one action, then a dump -- how labels get discovered |
+| `driver/report.py` | summarise episode directories and their findings |
+| `driver/campaign.py` | the suite or an exploration across several emulators |
+| `coverage/report.sh` | merge `.ec` files into an HTML/XML report |
+| `coverage/gaps.py` | rank what is still uncovered, and diff two reports |
+
+## Findings
+
+`findings/` holds a write-up and a standalone reproducer per confirmed defect,
+and a patch where the fix needs no design decision. `findings/ROUND1.md` is the
+first round's report; what it found:
+
+* `qr-config-tab-crashes-the-terminal.md` -- selecting the QR tab kills the
+ app on the first camera frame, on any device whose sensor is a quarter turn
+ from the display. Patched and verified.
+* `refund-amount-swallows-extra-decimal-points.md` -- a refund typed as
+ `1.000.50` is accepted without comment and settles at 1.00, because
+ `Amount.fromString` discards everything after a second decimal point.
+ Patched.
+* `fresh-instance-cannot-be-used.md` -- an instance with no products is
+ refused outright, so a merchant who has just created one cannot even charge
+ an amount.
+* `expired-session-shows-a-protocol-error.md` -- the session-expiry handling
+ exists, is translated, and never fires; what the cashier sees is the
+ backend's 401 hint about an `Authorization` header.
+* `login-hangs-forever-on-a-silent-backend.md` -- every HTTP timeout is
+ infinite, so a peer that accepts and goes quiet leaves the login form under
+ an unlabelled, undismissable spinner.
+* `pos-config-url-percent-encodes-the-separator.md` -- the configuration
+ request goes to `/private%2Fpos`. Patched.
+* `setup-uri-drops-the-port.md` -- a `taler-pos://` setup URI loses the
+ backend's port, so QR provisioning cannot reach a backend that is not on 443.
+* `controls-without-accessible-names.md` -- the drawer button, the
+ password-visibility toggle and the remember-password checkbox announce
+ nothing.
+
+## Gotchas the harness learned the hard way
+
+* **The soft keyboard covers the Connect button, and the hierarchy does not say
+ so.** The login screen does not resize under the IME, so the dump reports
+ Connect at its layout position while the keyboard is drawn on top of it; a tap
+ aimed there lands on a key. Nothing is logged and nothing changes on screen,
+ so it reads exactly like a button that does nothing -- it cost an hour of
+ looking for a bug in `submitManualConfig` that was not there.
+ `Pos.tap_button` now checks `dumpsys input_method` and presses BACK first.
+ BACK is what dismisses a soft keyboard; `KEYCODE_ESCAPE` does nothing at all.
+* **A label's field is the one that *contains* it, not the first one below it.**
+ A Material text field draws its label inside its own box while empty, and the
+ Username label starts one pixel below its own field -- so "the first editable
+ at or below the label's top edge" selected the *password* box, and the
+ instance name was typed into it. The form then refuses to log in, and the
+ scenario reports that the terminal rejected a valid credential.
+ `Pos.fill_field` verifies afterwards what the field holds, by content where it
+ shows text and by length where it shows dots.
+* **The keypad has no decimal key.** It fills from the right, like a till: "100"
+ is one unit and "1" is one cent. `Pos.enter_amount("1.00")` translates and
+ then checks what the screen ended up showing.
+* **The withdrawal has to be approved after the wallet has chosen an exchange.**
+ `taler-wallet-cli withdraw` returns as soon as the transaction exists, leaving
+ it in `pending:bank-register-reserve`, and the wallet only makes progress
+ while one of its processes is running -- so nothing advances it after that
+ command exits, and the bank answers "cannot confirm an unselected withdrawal"
+ forever. `Wallet.withdraw` waits for `pending:bank-confirm-transfer` first.
+* **A `.json` wallet database silently selects a memory backend** that refuses
+ every command with "memory backend not supported". The `.sqlite3` suffix is
+ load-bearing, so it is asserted rather than hoped for.
+* **The bank's confirm endpoint is under the account.** A POST to
+ `/withdrawals/<id>/confirm` answers 404 with "no endpoint defined for the
+ URL", which reads like the withdrawal is gone rather than like a wrong path;
+ it is `/accounts/<user>/withdrawals/<id>/confirm`.
+* **A re-registered bank account keeps its old password.** The demo bank answers
+ 409 and the mismatch only surfaces as a 401 several steps later, so
+ `register_account` checks the credential where it can still be explained.
+* **The view hierarchy is stale while a camera preview is on screen.** With
+ the QR tab open, `uiautomator dump` keeps returning the *login form* --
+ every node, unchanged -- while a screenshot shows the live preview and the
+ "Scan the QR code" hint. So nothing that involves the camera can be judged
+ from a dump; `provision_by_qr` waits for the terminal's *effect* (it
+ provisions itself, or it does not) and development used screenshots. This
+ cost an hour of believing the QR tab did not open, on a build where it did.
+* **The emulator ignores a 1-bit palette PNG poster** and silently keeps its
+ default checkerboard, which looks exactly like a poster that loaded and does
+ not decode. `qrencode` writes 1-bit PNGs, so `qrposter.py` converts to
+ 24-bit RGB before hanging it on the wall.
+* **`uiautomator dump` comes back empty often enough to matter**, during a
+ navigation animation or while a dialog is being laid out -- and an empty dump
+ reads as "this screen has no such control", which is the same thing a locked
+ drawer or a missing button looks like. `Pos._stable_dump` retries.
+* **This harness owns console ports 5584 and up, not 5554.** The wallet
+ simulator numbers its workers from 5554, and a second harness starting on an
+ occupied port does not boot anything and does not complain: it attaches to
+ the *other* one's emulators. Observed once -- `/opt/taler-sim`'s
+ `forever.sh` started a four-worker exploration, two of its workers found a
+ device on 5554 and 5558, and those devices were running the point-of-sale
+ app. Neither side noticed, because adb reports a device either way. `POS_PORT_BASE` is why, `Device.serial_for()` is the single place that
+ knows it, and `POS_SERIAL` still overrides for attaching to an emulator
+ somebody else started.
+
+ It is still worth a glance at `pgrep -af "explore.py|campaign.py"` before a
+ long round, and the wallet's loop stops with
+ `touch /opt/taler-sim/run/STOP` -- which only takes effect after the round
+ in flight, so a campaign already running has to be killed by pid.
+* **`taler-twister` cannot proxy DELETE.** `taler-twister-service.c` crafts a
+ curl request for PUT, POST and GET, and for anything else logs
+
+ ```
+ WARNING Unsupported HTTP method `DELETE'
+ ```
+
+ and closes the connection without a reply. So every `DELETE
+ /private/orders/<id>` through twister fails, whether or not a mutation is
+ armed -- which means no `fault_*` scenario can watch a *successful* cancel
+ or delete, and one that expects one is testing the proxy rather than the
+ app. It is also how finding 5 was reached: the terminal reports any failed
+ delete as "This order has been claimed by a wallet".
+* **A coverage report has to be built from a *clean* build.** JaCoCo matches
+ execution data to classes by checksum, and an incremental Kotlin/Compose
+ rebuild does not produce the same bytecode as a build from scratch, even
+ from byte-identical sources:
+
+ ```
+ incremental rebuild 93bc05b1... MainActivity.class
+ ./gradlew clean … 780409bb... MainActivity.class <- what the APK has
+ ```
+
+ A class that does not match is reported as **zero covered**, silently, with
+ one `[WARN] Execution data for class … does not match` line among the noise.
+ Two such classes took the root package from 88% to 26% and the overall
+ figure from 65.6% to 61.5%. So: `./gradlew :merchant-terminal:clean
+ :merchant-terminal:assembleSim` before `coverage/report.sh`, and read the
+ warnings -- there should be none.
+* **An unanchored marker can match the error that denies it.**
+ `Screen.find` matches case-insensitively, and the terminal's failure string
+ is **"Error: No payment received"** -- which contains `MARK_SUCCESS`'s old
+ pattern, `Payment received`. A scenario asking "the backend refused, so the
+ terminal must *not* claim success" was answered "it does" by the very error
+ that says it does not. Every success check is anchored now
+ (`^Payment received$`). Before adding a marker, grep `strings.xml` for the
+ phrase: in this app the failure strings are built out of the success ones.
+* **A scenario that changes the device must do it after `fresh_start`.**
+ `fresh_start` restores the run's orientation, so turning the device before
+ provisioning turns it straight back -- and the scenario then tests
+ landscape under a portrait name, which is the exact failure that reset
+ exists to prevent. Both portrait scenarios shipped with that bug and one of
+ them *passed*. They now turn afterwards and `require` the orientation again
+ at the point where the judging happens, because a guard that is only
+ checked at the start of a scenario is not a guard.
+* **A label inside a *disabled* button resolves to the wrong control.**
+ `Screen.tap_target` used to consider only enabled clickables, so the label
+ of a disabled Compose Button fell through to a neighbour search and landed
+ on the nearest enabled thing -- for the amount keypad's Charge button, a
+ digit key three rows up. The caller then read *that* key's `enabled` and
+ reported that charging nothing was allowed. It is not, and never was. The
+ containment search now includes disabled clickables, so "the control is
+ there and disabled" is a thing the driver can say.
+* **A control a lazy list has not composed is not merely off screen.** It is
+ absent from the hierarchy, so waiting for it times out with a message that
+ reads like the screen has no such button. `tap_button` scrolls first and
+ complains afterwards -- which is what the login form needs once the
+ keyboard is up, because Connect is then below the fold.
+* **`pkill -f mockd.py` kills the ssh session that typed it**, because the
+ pattern matches that command line too. Bracket the pattern (`moc[k]d`) or
+ match on a pid file.
+
+ The same trap in its quieter form: `ssh host 'pgrep -c -f "suite.py"'`
+ always answers at least 1, because the remote shell running that command has
+ "suite.py" on *its* command line. A wait loop built on it never finishes --
+ it waits for itself. Bracketing the pattern is not enough either when the
+ surrounding command mentions the plain name again later. Both the monitor
+ and a by-hand check were fooled by this after the run they were waiting for
+ had already finished; the artifact directory, or the run's own log, is the
+ honest signal.
+
+ It happened again in round three, in a wait loop written in full knowledge
+ of this paragraph: `until ! ssh host 'pgrep -f "driver/suite.py"'` spun for
+ half an hour after the run had ended. So, concretely -- bracket the pattern
+ *and* keep the plain name off the rest of the line:
+
+ ```bash
+ ssh host 'pgrep -cf "[d]river/suite.py"' # 0 when nothing is running
+ ```
+
+ or, better, wait on what the run itself produces:
+
+ ```bash
+ until ssh host 'grep -q "^artifacts:" run/round-N.log'; do sleep 20; done
+ ```
+* **A worker's log stays empty without `python3 -u`.** Progress sits in a pipe
+ buffer for the whole run, which looks exactly like a hang.
+* **Port 8443 on tripwire is somebody else's**, and it answers TLS, so a mock
+ bound there fails with "address already in use" while a client gets a
+ certificate error from a service that has nothing to do with this. Check
+ `ss -ltn` before picking a port.
+* **The emulator has no NFC and no `hw.nfc` property**, so the terminal's
+ tap-to-pay half is unreachable: `TalerNfcService.setUri` returns early
+ without an adapter. That is the app behaving correctly, so the oracle must
+ not read it as a missing payment code.
diff --git a/pos-simulator/backend/mockd.py b/pos-simulator/backend/mockd.py
@@ -0,0 +1,801 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""A merchant backend that answers however the scenario needs it to.
+
+The public demo backend is the right thing to test against for anything that
+has to be real -- a payment that settles, an inventory with history behind it.
+It is the wrong thing for testing how the terminal copes with a merchant who
+is *not* set up: nobody's shared demo instance should be broken on purpose,
+self-provisioning a fresh one needs an emailed TAN, and "what does the
+terminal do when `/private/pos` answers with a product in the wrong currency"
+is not a question a correct backend can be asked.
+
+So: a few hundred lines of HTTP that speaks just enough of the merchant API
+for the terminal to configure itself and create an order, with a profile
+switch for each way a merchant can be wrong.
+
+It answers TLS, because it has to. The terminal builds its merchant URL by
+hard-coding `https://` -- in the login form and in the `taler-pos://` parser
+both -- so a plain-http mock is unreachable without patching the app, which
+would mean testing something other than the app. The certificate is signed by
+the simulator's own CA, which the "sim" build type trusts and nothing else
+does (see pos-simulator/tls/).
+
+ python3 mockd.py --profile fresh --port 19443
+ python3 mockd.py --list
+
+Profiles:
+
+ healthy a small, correct instance: two categories, three products
+ fresh provisioned and never stocked: no categories, no products
+ no-bank-account stocked, but order creation fails the way it does when the
+ instance has no bank account configured
+ wrong-currency products priced in a currency the instance does not use
+ bad-category a product referencing a category id that does not exist
+ version-old a backend too old for the terminal to talk to
+ version-new a backend too new for it
+ malformed `/private/pos` that is not the JSON the terminal expects
+ empty-reply `/private/pos` that answers 200 with nothing at all
+ slow every reply delayed past the terminal's patience
+ hang accepts the connection and never answers
+ expire-after-3 the token stops working on the fourth request
+ huge-inventory four hundred products, to see what the grid does
+ unicode product names in scripts the terminal has to lay out
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import ssl
+import sys
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+HERE = Path(__file__).resolve().parent
+TLS_DIR = HERE.parent / "tls"
+
+# What the terminal checks itself against: BACKEND_API_VERSION is "20:0:8", so
+# it accepts a backend whose current:revision:age covers 20.
+# Taler protocol versions are current:revision:age, and two peers agree when
+# their supported ranges overlap: the terminal is 20:0:8, so it speaks
+# anything from 12 to 20.
+VERSION_OK = "42:0:30" # 12 .. 42 -- overlaps
+VERSION_TOO_OLD = "11:0:0" # 11 .. 11 -- one short of the terminal's floor
+VERSION_TOO_NEW = "60:0:2" # 58 .. 60 -- above its ceiling
+
+CURRENCY = "KUDOS"
+CURRENCY_SPEC = {
+ "name": "Kudos",
+ "currency": CURRENCY,
+ "num_fractional_input_digits": 2,
+ "num_fractional_normal_digits": 2,
+ "num_fractional_trailing_zero_digits": 2,
+ "alt_unit_names": {"0": "ク"},
+}
+
+
+def _product(pid: str, description: str, price: str, categories: list[int],
+ **extra: Any) -> dict:
+ out = {
+ "product_id": pid,
+ "product_name": description,
+ "description": description,
+ "price": price,
+ "categories": categories,
+ "total_stock": -1,
+ "unit": "item",
+ }
+ out.update(extra)
+ return out
+
+
+HEALTHY_CATEGORIES = [{"id": 1, "name": "Drinks"}, {"id": 2, "name": "Snacks"}]
+HEALTHY_PRODUCTS = [
+ _product("coffee", "Coffee", f"{CURRENCY}:2.50", [1]),
+ _product("tea", "Tea", f"{CURRENCY}:2.00", [1]),
+ _product("pretzel", "Pretzel", f"{CURRENCY}:1.25", [2], total_stock=4,
+ total_sold=1, total_lost=0),
+]
+
+
+@dataclass
+class Profile:
+ """One way a merchant backend can behave."""
+
+ name: str
+ description: str
+ categories: list[dict] = field(default_factory=lambda: list(HEALTHY_CATEGORIES))
+ products: list[dict] = field(default_factory=lambda: list(HEALTHY_PRODUCTS))
+ version: str = VERSION_OK
+ currency: str = CURRENCY
+ # Raw body to send for /private/pos instead of the generated one.
+ pos_body: Optional[str] = None
+ delay: float = 0.0
+ # Requests with a valid token before it starts answering 401; None = never.
+ token_uses: Optional[int] = None
+ # How `/collect` and `/refund-external` fail, as (status, code, hint), or
+ # None for "they work". These are the two calls a mixed-payment sale
+ # ends on, and both of them happen *after* the cashier has taken real
+ # money, which is what makes their failure modes worth having.
+ collect_status: Optional[tuple] = None
+ external_refund_status: Optional[tuple] = None
+ # Error to answer order creation with: (status, code, hint).
+ order_error: Optional[tuple[int, int, str]] = None
+ # Body to answer order creation with instead of the generic error shape.
+ # The merchant backend's inventory refusal is not a `{code, hint}` error:
+ # it is a 410 carrying which product ran out and by how much, which
+ # `Response.parseInventoryAvailabilityError` turns into a sentence of its
+ # own. Nothing else in the protocol looks like that, so it needs a body
+ # rather than a code and a hint.
+ order_error_body: Optional[tuple[int, dict]] = None
+ # Hand out `taler+http://` pay URIs, as a backend behind a plain-HTTP
+ # reverse proxy does. The terminal is supposed to offer to upgrade it.
+ insecure_pay_uri: bool = False
+ # Challenges `POST /private/token` answers 202 with until they are solved,
+ # as a backend with `mandatory_tan_channels` does. The real demo backend
+ # mails the code, which is why nothing driving only the UI has ever reached
+ # this path: here the code is a constant the harness knows.
+ token_challenges: Optional[list[dict]] = None
+ combi_and: bool = False
+ tan: str = "12345678"
+ # Wrong codes answered 409 ("wrong, try again") before the backend starts
+ # answering 429 ("too many, here is a new one"). Those are the two arms of
+ # `MfaUtils.handleChallengeConfirmError` that are not simply "give up".
+ tan_attempts_before_rate_limit: int = 2
+ # Refuse a bare token and accept only "secret-token:<it>". The terminal
+ # tries the bare one first and retries with the prefix on a 401 -- see
+ # `ConfigManager.fetchPosConfig` -- and nothing else makes it do that.
+ token_needs_prefix: bool = False
+
+
+def _unicode_products() -> list[dict]:
+ names = [
+ ("espresso-ar", "قهوة إسبريسو"),
+ ("tea-ja", "緑茶とても長い名前のついた商品"),
+ ("cake-he", "עוגת גבינה"),
+ ("kvass-ru", "Квас домашний"),
+ ("combining", "Café crème"),
+ ("rtl-mixed", "Pita RTL 3x"),
+ ("emoji", "Birthday \U0001F382 slice"),
+ ("zalgo", "C͑oͫf̰f̘e͉e"),
+ ]
+ return [_product(pid, name, f"{CURRENCY}:1.{i:02d}", [1])
+ for i, (pid, name) in enumerate(names)]
+
+
+# A 2x2 PNG, so the terminal has a real bitmap to decode rather than a string
+# it will reject. `ConfigProduct.image` is a data URL and the order grid runs
+# it through `base64Bitmap` in two places and lays the row out differently when
+# any product in it has one.
+_PIXEL_PNG = (
+ "data:image/png;base64,"
+ "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAFElEQVR4nGP8z4AATAxQxhAX"
+ "AAAA//8DcgEqBrfkPQAAAABJRU5ErkJggg=="
+)
+
+
+def _rich_products() -> list[dict]:
+ """One product per thing the terminal does with product metadata.
+
+ Everything here is optional in the protocol and absent from the healthy
+ profile, so each field is a branch the terminal takes only when a merchant
+ has filled it in: a picture, a name that differs from the description, a
+ translation, a tax, a stock count written as a decimal string rather than
+ an integer, and a product that has sold out.
+ """
+ return [
+ # Picture, and a name that is not the description: `displayName` takes
+ # the name and `displayDescription` the description, which is the only
+ # case where the card shows two lines of text.
+ _product("espresso", "Single shot, 25 s extraction", f"{CURRENCY}:2.50",
+ [1], product_name="Espresso", image=_PIXEL_PNG,
+ description_i18n={"de": "Einfacher Espresso", "fr": "Expresso"},
+ name_i18n={"de": "Espresso", "fr": "Expresso"},
+ total_stock=20, total_sold=3, total_lost=1),
+ # Stock as decimal strings: `stockLimit` has a BigDecimal arm for each
+ # of total, sold and lost, and integers never reach any of them.
+ _product("flour", "Flour, by the kilo", f"{CURRENCY}:1.80", [2],
+ product_name="Flour", image=_PIXEL_PNG,
+ total_stock=None, unit_total_stock="12.750",
+ unit_total_sold="4.250", unit_total_lost="0.500"),
+ # Sold out: the card says so rather than offering the product.
+ _product("pastry", "Yesterday's pastry", f"{CURRENCY}:1.00", [2],
+ product_name="Pastry", total_stock=6, total_sold=6,
+ total_lost=0),
+ # Unlimited stock written the other way round, as a string.
+ _product("water", "Tap water", f"{CURRENCY}:0.50", [1],
+ total_stock=None, unit_total_stock="-1"),
+ # Taxes and a net price, which only `toContractProduct` looks at, plus
+ # a delivery location.
+ _product("hamper", "Gift hamper", f"{CURRENCY}:30.00", [2],
+ product_name="Hamper", prices_are_net=True,
+ delivery_location="counter",
+ taxes=[{"name": "VAT", "tax": f"{CURRENCY}:5.00"}]),
+ # No picture at all, so a row mixes products with and without one.
+ _product("newspaper", "Daily paper", f"{CURRENCY}:3.20", [2]),
+ ]
+
+
+PROFILES: dict[str, Profile] = {
+ "healthy": Profile("healthy", "a small, correct instance"),
+ "fresh": Profile(
+ "fresh", "provisioned and never stocked",
+ categories=[], products=[]),
+ "no-bank-account": Profile(
+ "no-bank-account", "order creation fails for want of a bank account",
+ order_error=(409, 2010,
+ "No wire account is configured for this instance")),
+ "wrong-currency": Profile(
+ "wrong-currency", "products priced in another currency",
+ products=[_product("coffee", "Coffee", "EUR:2.50", [1]),
+ _product("tea", "Tea", "CHF:2.00", [1])]),
+ "bad-category": Profile(
+ "bad-category", "a product in a category that does not exist",
+ products=[_product("ghost", "Ghost product", f"{CURRENCY}:1.00", [99])]),
+ "collect-fails": Profile(
+ "collect-fails",
+ "settling a fully-cash sale is refused by the backend",
+ collect_status=(502, 2017, "The backend could not settle the order")),
+ "external-refund-fails": Profile(
+ "external-refund-fails",
+ "recording cash handed back is refused by the backend",
+ external_refund_status=(409, 2537,
+ "The order was already refunded externally")),
+ "version-old": Profile("version-old", "a backend too old to talk to",
+ version=VERSION_TOO_OLD),
+ "version-new": Profile("version-new", "a backend too new to talk to",
+ version=VERSION_TOO_NEW),
+ "malformed": Profile(
+ "malformed", "/private/pos that is not what the terminal expects",
+ pos_body=json.dumps({"categories": "not a list", "products": 42})),
+ "empty-reply": Profile(
+ "empty-reply", "/private/pos that answers 200 with nothing",
+ pos_body=""),
+ "slow": Profile("slow", "every reply delayed past the terminal's patience",
+ delay=65.0),
+ "hang": Profile("hang", "accepts the connection and never answers",
+ delay=86_400.0),
+ "expire-after-3": Profile(
+ "expire-after-3", "the token stops working on the fourth request",
+ token_uses=3),
+ "huge-inventory": Profile(
+ "huge-inventory", "four hundred products",
+ products=[_product(f"p{i:03d}", f"Product {i:03d}",
+ f"{CURRENCY}:{1 + i % 50}.{i % 100:02d}", [1 + i % 2])
+ for i in range(400)]),
+ "unicode": Profile("unicode", "product names in several scripts",
+ products=_unicode_products()),
+ "inventory-gone": Profile(
+ "inventory-gone", "the product sold out between the tap and the order",
+ order_error_body=(410, {"product_id": "pretzel",
+ "requested_quantity": 2,
+ "available_quantity": 0})),
+ "insecure-pay-uri": Profile(
+ "insecure-pay-uri", "pay URIs that are not https",
+ insecure_pay_uri=True),
+ "mfa-two-channels": Profile(
+ "mfa-two-channels", "logging in needs a code, by email or by SMS",
+ token_challenges=[
+ {"challenge_id": "mock-chal-email",
+ "tan_channel": "email", "tan_info": "o...r@example.com"},
+ {"challenge_id": "mock-chal-sms",
+ "tan_channel": "sms", "tan_info": "+49 *** *** 42"},
+ ]),
+ "rich-catalogue": Profile(
+ "rich-catalogue", "products carrying every optional field there is",
+ products=_rich_products()),
+ "token-needs-prefix": Profile(
+ "token-needs-prefix", "a backend that only accepts secret-token:<tok>",
+ token_needs_prefix=True),
+ "mfa-both-required": Profile(
+ "mfa-both-required", "logging in needs a code from each of two channels",
+ combi_and=True,
+ token_challenges=[
+ {"challenge_id": "mock-chal-email",
+ "tan_channel": "email", "tan_info": "o...r@example.com"},
+ {"challenge_id": "mock-chal-sms",
+ "tan_channel": "sms", "tan_info": "+49 *** *** 42"},
+ ]),
+}
+
+
+@dataclass
+class Order:
+ order_id: str
+ amount: str
+ summary: str
+ claim_token: str
+ created: float
+ pay_deadline: float
+ claimed: bool = False
+ paid: bool = False
+ refunded: bool = False
+ # Refunds settled outside Taler -- cash handed back, a card refunded in
+ # the provider's own app. The backend keeps these apart from Taler
+ # refunds and so does this: a cash refund must never show up in
+ # `refund_amount`, and a scenario that cannot tell them apart would not
+ # notice if it did.
+ refunds_external: list = field(default_factory=list)
+ collected: bool = False
+
+
+class MockState:
+ """Everything the server remembers, so a scenario can inspect it."""
+
+ def __init__(self, profile: Profile, host: str, instance: str):
+ self.profile = profile
+ self.host = host
+ self.instance = instance
+ self.orders: dict[str, Order] = {}
+ self.requests: list[tuple[float, str, str]] = []
+ self.authorised_requests = 0
+ # The two-factor dance, so a scenario can check that the terminal
+ # asked for a code before it typed one and did not skip a channel.
+ self.challenges_sent: list[str] = []
+ self.challenges_solved: list[str] = []
+ self.bad_tans: list[str] = []
+ # Requests refused for carrying the token without its prefix, so a
+ # scenario can tell a retry from a first attempt that happened to work.
+ self.bare_token_requests = 0
+ self.lock = threading.Lock()
+
+ def note(self, method: str, path: str) -> None:
+ with self.lock:
+ self.requests.append((time.time(), method, path))
+
+ def paths(self) -> list[str]:
+ with self.lock:
+ return [p for _, _, p in self.requests]
+
+ def encoded_slash_requests(self) -> list[str]:
+ """Requests that arrived with a percent-encoded path separator."""
+ with self.lock:
+ return [p for _, method, p in self.requests if method == "ENCODED-SLASH"]
+
+ def token_still_good(self) -> bool:
+ limit = self.profile.token_uses
+ with self.lock:
+ self.authorised_requests += 1
+ return limit is None or self.authorised_requests <= limit
+
+
+class Handler(BaseHTTPRequestHandler):
+ state: MockState # set on the server class
+
+ protocol_version = "HTTP/1.1"
+ server_version = "pos-simulator-mockd/1"
+
+ def log_message(self, fmt: str, *args: Any) -> None:
+ sys.stderr.write(f"mockd {self.address_string()} {fmt % args}\n")
+
+ def handle_one_request(self) -> None:
+ """Serve one request, without a traceback when the client walks away.
+
+ The terminal closes idle connections and is itself killed mid-request
+ by several scenarios, so a broken pipe or a reset TLS session is
+ normal here. http.server's default is to print a full traceback for
+ each one, which buries the request log the oracles read.
+ """
+ try:
+ super().handle_one_request()
+ except (BrokenPipeError, ConnectionResetError, ssl.SSLError) as e:
+ self.close_connection = True
+ sys.stderr.write(f"mockd {self.address_string()} client went away: "
+ f"{type(e).__name__}\n")
+
+ # -- plumbing ---------------------------------------------------------
+
+ def _send(self, status: int, payload: Any, raw: Optional[str] = None) -> None:
+ if self.state.profile.delay:
+ time.sleep(self.state.profile.delay)
+ body = (raw if raw is not None else json.dumps(payload)).encode()
+ self.send_response(status)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ if body:
+ self.wfile.write(body)
+
+ def _error(self, status: int, code: int, hint: str) -> None:
+ self._send(status, {"code": code, "hint": hint, "detail": ""})
+
+ def _normalised_path(self) -> str:
+ """The request path with encoded slashes turned back into separators.
+
+ The terminal asks for `/instances/<id>/private%2Fpos`: it builds that
+ URL with `Uri.Builder.appendPath("private/pos")`, which percent-encodes
+ the separator because a path *segment* may legitimately contain one.
+ The GNU Taler backend decodes the path before routing and so answers
+ it anyway, which is why this has never been noticed -- but a reverse
+ proxy in front of the backend need not, and Apache with its default
+ `AllowEncodedSlashes Off` refuses such a request outright.
+
+ So the mock accepts it, like the real backend, and records that it had
+ to: `MockState.encoded_slash_requests` is what the finding is written
+ from.
+ """
+ path = self.path.split("?")[0]
+ if "%2F" in path or "%2f" in path:
+ self.state.note("ENCODED-SLASH", path)
+ return path.replace("%2F", "/").replace("%2f", "/")
+
+ def _body(self) -> dict:
+ length = int(self.headers.get("Content-Length") or 0)
+ if not length:
+ return {}
+ try:
+ return json.loads(self.rfile.read(length))
+ except json.JSONDecodeError:
+ return {}
+
+ def _authorised(self) -> bool:
+ header = self.headers.get("Authorization", "")
+ if not header.startswith("Bearer "):
+ return False
+ if (self.state.profile.token_needs_prefix
+ and not header.startswith("Bearer secret-token:")):
+ self.state.bare_token_requests += 1
+ return False
+ return self.state.token_still_good()
+
+ # -- routes -----------------------------------------------------------
+
+ def do_GET(self) -> None: # noqa: N802 (http.server's naming)
+ self.state.note("GET", self.path)
+ path = self._normalised_path()
+ prefix = f"/instances/{self.state.instance}"
+
+ if path in ("/config", f"{prefix}/config"):
+ return self._send(200, {
+ "currency": self.state.profile.currency,
+ "currencies": {self.state.profile.currency: CURRENCY_SPEC},
+ "version": self.state.profile.version,
+ "name": "taler-merchant",
+ "implementation": "urn:net:taler:specs:taler-merchant:pos-simulator-mock",
+ "have_self_provisioning": True,
+ "exchanges": [],
+ })
+
+ if path == f"{prefix}/private/pos":
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ profile = self.state.profile
+ if profile.pos_body is not None:
+ return self._send(200, None, raw=profile.pos_body)
+ return self._send(200, {
+ "categories": profile.categories,
+ "products": profile.products,
+ })
+
+ if path.startswith(f"{prefix}/private/products/"):
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ pid = path.rsplit("/", 1)[-1]
+ product = next((p for p in self.state.profile.products
+ if p["product_id"] == pid), None)
+ if product is None:
+ return self._error(404, 2549, "Product unknown")
+ return self._send(200, {
+ "description": product["description"],
+ "price": product["price"],
+ "total_stock": product.get("total_stock", -1),
+ "total_sold": product.get("total_sold", 0),
+ "total_lost": product.get("total_lost", 0),
+ })
+
+ if path == f"{prefix}/private/orders":
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ orders = sorted(self.state.orders.values(),
+ key=lambda o: o.created, reverse=True)
+ return self._send(200, {"orders": [
+ {
+ "order_id": o.order_id,
+ "row_id": i + 1,
+ "timestamp": {"t_s": int(o.created)},
+ "amount": o.amount,
+ "summary": o.summary,
+ "paid": o.paid,
+ "refunded": o.refunded,
+ "refund_pending": False,
+ }
+ for i, o in enumerate(orders)
+ ]})
+
+ if path.startswith(f"{prefix}/private/orders/"):
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ order = self.state.orders.get(path.rsplit("/", 1)[-1])
+ if order is None:
+ return self._error(404, 2005, "The proposal is not known")
+ if order.paid:
+ return self._send(200, {
+ "order_status": "paid", "refunded": order.refunded,
+ "refund_pending": False, "wired": False,
+ "deposit_total": order.amount,
+ "exchange_code": 0, "exchange_http_status": 0,
+ "refunds_external": order.refunds_external,
+ "refund_amount": f"{self.state.profile.currency}:0",
+ "contract_terms": {"summary": order.summary,
+ "amount": order.amount},
+ "last_payment": {"t_s": int(time.time())},
+ })
+ if order.claimed:
+ return self._send(200, {"order_status": "claimed",
+ "contract_terms": {
+ "summary": order.summary,
+ "amount": order.amount}})
+ scheme = ("taler+http" if self.state.profile.insecure_pay_uri
+ else "taler")
+ return self._send(200, {
+ "order_status": "unpaid",
+ "taler_pay_uri": (f"{scheme}://pay/{self.state.host}/instances/"
+ f"{self.state.instance}/{order.order_id}/"
+ f"?c={order.claim_token}"),
+ "creation_time": {"t_s": int(order.created)},
+ "summary": order.summary,
+ "order_status_url": "https://example.invalid/",
+ })
+
+ if path == f"{prefix}/private/accounts":
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ if self.state.profile.name == "no-bank-account":
+ return self._send(200, {"accounts": []})
+ return self._send(200, {"accounts": [{
+ "payto_uri": "payto://x-taler-bank/bank.example.invalid/mock",
+ "h_wire": "0" * 64, "active": True}]})
+
+ self.state.note("GET-404", path)
+ return self._error(404, 21, "No endpoint for this URL in the mock")
+
+ def do_POST(self) -> None: # noqa: N802
+ self.state.note("POST", self.path)
+ path = self._normalised_path()
+ prefix = f"/instances/{self.state.instance}"
+ body = self._body()
+
+ # The two-factor dance, which only `mfa-*` profiles ask for. Order is
+ # POST /private/token -> 202 with the challenges, then one
+ # POST .../challenge/<id> to have the code sent and one
+ # POST .../challenge/<id>/confirm to answer it, then /private/token
+ # again carrying `Taler-Challenge-Ids` for what was solved.
+ challenges = self.state.profile.token_challenges
+ if challenges and path.startswith(f"{prefix}/challenge/"):
+ rest = path[len(f"{prefix}/challenge/"):]
+ challenge_id = rest.removesuffix("/confirm")
+ if challenge_id not in {c["challenge_id"] for c in challenges}:
+ return self._error(404, 2900, f"No such challenge {challenge_id}")
+ if not rest.endswith("/confirm"):
+ self.state.challenges_sent.append(challenge_id)
+ return self._send(204, None, raw="")
+ # The terminal sends the code hyphenated -- `MfaUtils.formatMfaCode`
+ # turns 12345678 into "1234-5678" -- so the comparison is on the
+ # digits and the profile's `tan` can be written either way.
+ given = str(body.get("tan", ""))
+ digits = "".join(ch for ch in given if ch.isdigit())
+ if digits != "".join(ch for ch in self.state.profile.tan
+ if ch.isdigit()):
+ self.state.bad_tans.append(given)
+ # 409 is the only status the terminal reads as "wrong code, ask
+ # for another"; 429 is "too many attempts, a new code is on its
+ # way"; anything else makes it give up. See
+ # `MfaUtils.handleChallengeConfirmError`.
+ if len(self.state.bad_tans) > self.state.profile.tan_attempts_before_rate_limit:
+ return self._error(429, 2903, "Too many attempts")
+ return self._error(409, 2901, "Invalid TAN")
+ self.state.challenges_solved.append(challenge_id)
+ return self._send(204, None, raw="")
+
+ if path == f"{prefix}/private/token":
+ if challenges:
+ solved = [i for i in (self.headers.get("Taler-Challenge-Ids") or "")
+ .split(",") if i]
+ needed = ({c["challenge_id"] for c in challenges}
+ if self.state.profile.combi_and else None)
+ enough = (set(solved) >= needed) if needed else bool(solved)
+ if not enough:
+ return self._send(202, {
+ "challenges": challenges,
+ "combi_and": self.state.profile.combi_and,
+ })
+ # The login form asks for this one. A mock token is accepted from
+ # anybody: what is under test is the terminal, not an access
+ # control decision.
+ duration = (body.get("duration") or {}).get("d_us")
+ expiration: dict[str, Any] = {"t_s": "never"}
+ if isinstance(duration, int):
+ expiration = {"t_s": int(time.time() + duration / 1_000_000)}
+ # A backend that insists on the prefix hands the token out
+ # *without* it, which is the whole point: the terminal stores what
+ # it was given, sends it bare, is refused, and retries prefixed.
+ # Handing out a prefixed token means it never has to.
+ token = f"mock-{uuid.uuid4().hex[:24]}"
+ if not self.state.profile.token_needs_prefix:
+ token = f"secret-token:{token}"
+ return self._send(200, {
+ "token": token, "access_token": token,
+ "scope": body.get("scope", "write"), "refreshable": False,
+ "expiration": expiration,
+ })
+
+ if path == f"{prefix}/private/orders":
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ error = self.state.profile.order_error
+ if error:
+ return self._error(*error)
+ raw = self.state.profile.order_error_body
+ if raw:
+ return self._send(raw[0], raw[1])
+ order_spec = (body.get("order") or {})
+ order_id = f"mock-{uuid.uuid4().hex[:12]}"
+ order = Order(
+ order_id=order_id,
+ amount=order_spec.get("amount", f"{self.state.profile.currency}:0"),
+ summary=order_spec.get("summary", ""),
+ claim_token=uuid.uuid4().hex[:26].upper(),
+ created=time.time(),
+ pay_deadline=time.time() + 3600,
+ )
+ self.state.orders[order_id] = order
+ return self._send(200, {"order_id": order_id,
+ "token": order.claim_token})
+
+ if path.endswith("/refund") and path.startswith(f"{prefix}/private/orders/"):
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ order_id = path.split("/")[-2]
+ order = self.state.orders.get(order_id)
+ if order is None:
+ return self._error(404, 2005, "The proposal is not known")
+ order.refunded = True
+ return self._send(200, {
+ "taler_refund_uri": (f"taler://refund/{self.state.host}/instances/"
+ f"{self.state.instance}/{order_id}"),
+ "h_contract": "0" * 64,
+ })
+
+ # Settling an order that was paid entirely outside Taler. Without
+ # this the checkout can be driven right up to "Complete payment" on a
+ # mock and no further, which is where the interesting half starts.
+ if (path.endswith("/collect")
+ and path.startswith(f"{prefix}/private/orders/")):
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ order_id = path.split("/")[-2]
+ order = self.state.orders.get(order_id)
+ if order is None:
+ return self._error(404, 2005, "The proposal is not known")
+ if self.state.profile.collect_status:
+ code, num, hint = self.state.profile.collect_status
+ return self._error(code, num, hint)
+ order.paid = True
+ order.collected = True
+ return self._send(200, {})
+
+ # Recording money handed back outside Taler.
+ if (path.endswith("/refund-external")
+ and path.startswith(f"{prefix}/private/orders/")):
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ order_id = path.split("/")[-2]
+ order = self.state.orders.get(order_id)
+ if order is None:
+ return self._error(404, 2005, "The proposal is not known")
+ if self.state.profile.external_refund_status:
+ code, num, hint = self.state.profile.external_refund_status
+ return self._error(code, num, hint)
+ body = self._body() or {}
+ order.refunds_external.append({
+ "id": body.get("id", "mock-refund"),
+ "method": body.get("method", "cash"),
+ "payment_id": body.get("payment_id"),
+ "amount": body.get("amount", f"{self.state.profile.currency}:0"),
+ "reason": body.get("reason", ""),
+ "timestamp": {"t_s": int(time.time())},
+ })
+ return self._send(200, {})
+
+ self.state.note("POST-404", path)
+ return self._error(404, 21, "No endpoint for this URL in the mock")
+
+ def do_DELETE(self) -> None: # noqa: N802
+ self.state.note("DELETE", self.path)
+ path = self._normalised_path()
+ prefix = f"/instances/{self.state.instance}"
+ if path.startswith(f"{prefix}/private/orders/"):
+ if not self._authorised():
+ return self._error(401, 40, "Invalid access token")
+ order_id = path.rsplit("/", 1)[-1]
+ order = self.state.orders.get(order_id)
+ if order is None:
+ return self._error(404, 2005, "The proposal is not known")
+ if order.claimed and "force=yes" not in self.path:
+ return self._error(409, 2026,
+ "The order has been claimed and cannot be "
+ "deleted without force")
+ del self.state.orders[order_id]
+ return self._send(204, None, raw="")
+ return self._error(404, 21, "No endpoint for this URL in the mock")
+
+
+def build_server(profile_name: str, port: int, instance: str = "mockshop",
+ host: Optional[str] = None
+ ) -> tuple[ThreadingHTTPServer, MockState]:
+ """A configured, not-yet-serving mock backend and the state it will fill.
+
+ Separated from `serve` so that a caller inside the driver can run it in a
+ thread and shut it down again -- a suite process runs several mock
+ scenarios one after another, and a server left listening takes the port
+ with it.
+ """
+ profile = PROFILES[profile_name]
+ host = host or f"localhost:{port}"
+ state = MockState(profile, host=host, instance=instance)
+ handler = type("BoundHandler", (Handler,), {"state": state})
+ server = ThreadingHTTPServer(("127.0.0.1", port), handler)
+ context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+ context.load_cert_chain(certfile=str(TLS_DIR / "srv.crt"),
+ keyfile=str(TLS_DIR / "srv.key"))
+ server.socket = context.wrap_socket(server.socket, server_side=True)
+ return server, state
+
+
+def serve(profile_name: str, port: int, instance: str = "mockshop",
+ host: Optional[str] = None,
+ ready: Optional[Callable[[MockState], None]] = None) -> None:
+ server, state = build_server(profile_name, port, instance, host)
+ print(f"mockd: profile {profile_name!r} ({PROFILES[profile_name].description}) "
+ f"on https://{state.host}/instances/{instance}", flush=True)
+ if ready:
+ ready(state)
+ try:
+ server.serve_forever()
+ except KeyboardInterrupt:
+ pass
+ finally:
+ server.server_close()
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--profile", default="healthy")
+ ap.add_argument("--port", type=int, default=19443)
+ ap.add_argument("--instance", default="mockshop")
+ ap.add_argument("--host", default=None,
+ help="the authority the terminal will use, if not localhost:<port>")
+ ap.add_argument("--list", action="store_true")
+ args = ap.parse_args()
+ if args.list:
+ width = max(len(n) for n in PROFILES)
+ for name, profile in PROFILES.items():
+ print(f" {name:<{width}} {profile.description}")
+ return 0
+ if args.profile not in PROFILES:
+ print(f"unknown profile {args.profile!r}; --list shows them all")
+ return 2
+ serve(args.profile, args.port, args.instance, args.host)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/pos-simulator/coverage/gaps.py b/pos-simulator/coverage/gaps.py
@@ -0,0 +1,387 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Where the simulator has not been yet.
+
+Reads the JaCoCo XML report and ranks what is still untouched, so the next
+iteration can aim at a feature rather than at random. Compose generates a lot
+of synthetic classes, so lambdas and `*ComposableSingletons` are folded into
+their owner and the ranking is by missed *lines* per package and per class.
+
+ python3 gaps.py out/coverage/coverage.xml # ranking
+ python3 gaps.py out/coverage/coverage.xml --since old.xml # what moved
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+SYNTHETIC = re.compile(r"\$\$|ComposableSingletons|\$lambda|\$WhenMappings|Kt\$\d")
+
+
+# Lines inside an @Preview body cannot be covered by an instrumented app run:
+# the function exists for Android Studio's preview pane and nothing calls it.
+# They are 27 % of everything this report calls "missed", so counting them
+# makes every ranking point at work that cannot be done.
+# The terminal has no @Preview annotations. What it has instead is eight
+# `internal fun *ScreenContent` composables that render a screen from a fixture
+# -- and the only thing that calls them is `ScreenshotActivity`, which lives in
+# the `debug` source set. `sim` is its own build type and does not include
+# that source set, so in the APK under test those functions have no caller at
+# all and no run can reach them. Counting them as missed points the ranking at
+# work nobody can do: OrderScreenContent alone is 73 lines.
+def _body_lines(lines: list[str], decl_index: int) -> set[int]:
+ """The 1-based line numbers of a declaration and its body."""
+ start = decl_index
+ # Back up over the annotations that belong to the declaration.
+ while start and lines[start - 1].lstrip().startswith("@"):
+ start -= 1
+ marked: set[int] = set()
+ depth, started, j = 0, False, start
+ while j < len(lines):
+ marked.add(j + 1)
+ depth += lines[j].count("{") - lines[j].count("}")
+ if "{" in lines[j]:
+ started = True
+ if started and depth <= 0:
+ break
+ j += 1
+ return marked
+
+
+# Functions that exist in `src/main` and that *nothing* calls -- not the app,
+# not the debug source set, not a unit test. Reported upstream as
+# bugs.gnunet.org 11981 rather than quietly skipped here, because a tool
+# special-casing code nobody else can see is how a gap stays hidden.
+#
+# `refundExternalPayment` is deliberately *not* in this list: six cases in
+# CheckoutManagerTest call it, so it is covered by the unit-test half of the
+# report even though no UI reaches it. Excluding it would hide a real
+# difference between "tested" and "reachable".
+DEAD_FUNCTIONS = {
+ "OrderManager.kt": ("deleteCurrentOrder",),
+ "CheckoutManager.kt": ("newPaymentId",),
+}
+
+
+def dead_lines(repo: Path) -> dict[str, set[int]]:
+ """Lines of functions with no caller anywhere. See bugs.gnunet.org 11981."""
+ import re
+ out: dict[str, set[int]] = {}
+ base = repo / "merchant-terminal/src/main/java"
+ if not base.is_dir():
+ return out
+ for path in base.rglob("*.kt"):
+ names = DEAD_FUNCTIONS.get(path.name)
+ if not names:
+ continue
+ lines = path.read_text(errors="replace").splitlines()
+ marked: set[int] = set()
+ for i, line in enumerate(lines):
+ for name in names:
+ if re.search(rf"\bfun\s+{re.escape(name)}\s*\(", line):
+ marked |= _body_lines(lines, i)
+ if marked:
+ out[path.name] = out.get(path.name, set()) | marked
+ return out
+
+
+# Compose composables whose only caller is `ScreenshotActivity` and friends in
+# the `debug` source set. `sim` is its own build type and does not include
+# that source set, so in the APK under test they have no caller at all and no
+# run can reach them. Counting them as missed points the ranking at work
+# nobody can do: `OrderScreenContent` and its lambdas alone are 76 lines.
+def debug_only_lines(repo: Path) -> dict[str, set[int]]:
+ """Lines of functions in `src/main` that only the debug source set calls.
+
+ Matched on the declaration rather than on a naming convention, and on
+ *any* modifiers rather than `internal` alone: the previous version keyed
+ on `^internal fun`, required the name to appear exactly once in main, and
+ so discounted 205 lines where the twelve `*ScreenContent` composables and
+ their lambdas come to nearly three hundred. A method reference
+ (`::name`) counts as a call, which the old version also missed.
+ """
+ import re
+ out: dict[str, set[int]] = {}
+ for module in ("merchant-terminal",):
+ main = repo / module / "src/main/java"
+ debug = repo / module / "src/debug/java"
+ if not main.is_dir() or not debug.is_dir():
+ continue
+ main_text = {q: q.read_text(errors="replace") for q in main.rglob("*.kt")}
+ debug_text = "\n".join(q.read_text(errors="replace")
+ for q in debug.rglob("*.kt"))
+ decl = re.compile(r"^\s*(?:(?:internal|private|public|inline|suspend)\s+)*"
+ r"fun\s+(\w+)\s*\(", re.M)
+ for path, text in main_text.items():
+ lines = text.splitlines()
+ marked: set[int] = set()
+ for m in decl.finditer(text):
+ name = m.group(1)
+ # Any mention at all, not `name(`: a Compose call with a
+ # trailing lambda has no parentheses (`PosTheme { ... }`), and
+ # keying on the parenthesis marked the app's own theme wrapper
+ # as debug-only -- twelve lines of live code that would have
+ # been quietly dropped from the denominator. Erring towards
+ # counting a comment as a use is the right way to be wrong
+ # here: under-discounting leaves work on the list, while
+ # over-discounting hides it.
+ used = re.compile(rf"\b{re.escape(name)}\b")
+ # Every mention in main, minus the declarations themselves.
+ mentions = sum(len(used.findall(t)) for t in main_text.values())
+ decls = sum(len(re.findall(rf"\bfun\s+{re.escape(name)}\s*\(", t))
+ for t in main_text.values())
+ if mentions > decls or not used.search(debug_text):
+ continue
+ marked |= _body_lines(lines, text[:m.start()].count("\n"))
+ if marked:
+ out[path.name] = out.get(path.name, set()) | marked
+ return out
+
+
+def preview_lines(repo: Path) -> dict[str, set[int]]:
+ """Line numbers no instrumented run can reach, per source file name.
+
+ Two sources: an @Preview body, which exists for Android Studio's preview
+ pane and which nothing calls; and a fixture composable that only the debug
+ source set calls (see `debug_only_lines`). The name is historical -- the
+ terminal has none of the former and eight of the latter.
+ """
+ out: dict[str, set[int]] = {}
+ # `merchant-terminal`, not `terminal` -- the name was wrong and nothing
+ # matched. It makes no difference to the figures: the terminal carries no
+ # @Preview annotations at all, so none of its missed lines were ever being
+ # excluded. What looks like a preview block at the end of five of its
+ # files is the phone half of a screen that picks its layout at runtime,
+ # which an instrumented run reaches on a phone-sized device and not
+ # otherwise.
+ for tree in ("merchant-terminal/src/main/java",
+ "merchant-lib/src/main/java",
+ "taler-kotlin-android/src/main/java"):
+ base = repo / tree
+ if not base.is_dir():
+ continue
+ for path in base.rglob("*.kt"):
+ lines = path.read_text(errors="replace").splitlines()
+ marked: set[int] = set()
+ i = 0
+ while i < len(lines):
+ if "@Preview" in lines[i]:
+ depth, started, j = 0, False, i
+ while j < len(lines):
+ marked.add(j + 1)
+ depth += lines[j].count("{") - lines[j].count("}")
+ if "{" in lines[j]:
+ started = True
+ if started and depth <= 0:
+ break
+ j += 1
+ i = j
+ i += 1
+ if marked:
+ out[path.name] = marked
+ for name, marked in debug_only_lines(repo).items():
+ out[name] = out.get(name, set()) | marked
+ for name, marked in dead_lines(repo).items():
+ out[name] = out.get(name, set()) | marked
+ return out
+
+
+def source_misses(path: str, skip: dict[str, set[int]]) -> tuple[int, int, int]:
+ """(missed, covered, missed-inside-previews) counted line by line."""
+ root = ET.parse(path).getroot()
+ missed = covered = in_preview = 0
+ for pkg in root.findall("package"):
+ for sf in pkg.findall("sourcefile"):
+ skipped = skip.get(sf.get("name") or "", ())
+ for line in sf.findall("line"):
+ nr = int(line.get("nr", 0))
+ mi, ci = int(line.get("mi", 0)), int(line.get("ci", 0))
+ if ci:
+ covered += 1
+ elif mi:
+ missed += 1
+ if nr in skipped:
+ in_preview += 1
+ return missed, covered, in_preview
+
+
+def reachable_misses_by_package(path: str, skip: dict[str, set[int]]) -> dict[str, int]:
+ """Missed lines per package, not counting the ones inside @Preview bodies.
+
+ Ranking packages by raw misses points at work that cannot be done: the
+ peer package looked like the third-biggest gap in the report and is mostly
+ four preview functions in one file.
+ """
+ root = ET.parse(path).getroot()
+ out: dict[str, int] = defaultdict(int)
+ for pkg in root.findall("package"):
+ pname = (pkg.get("name") or "").replace("/", ".")
+ for sf in pkg.findall("sourcefile"):
+ skipped = skip.get(sf.get("name") or "", ())
+ for line in sf.findall("line"):
+ if int(line.get("ci", 0)):
+ continue
+ if not int(line.get("mi", 0)):
+ continue
+ if int(line.get("nr", 0)) not in skipped:
+ out[pname] += 1
+ return dict(out)
+
+
+@dataclass
+class Unit:
+ missed: int = 0
+ covered: int = 0
+
+ @property
+ def total(self) -> int:
+ return self.missed + self.covered
+
+ @property
+ def pct(self) -> float:
+ return 100.0 * self.covered / self.total if self.total else 100.0
+
+
+def counter(el: ET.Element, kind: str = "LINE") -> tuple[int, int]:
+ for c in el.findall("counter"):
+ if c.get("type") == kind:
+ return int(c.get("missed", 0)), int(c.get("covered", 0))
+ return 0, 0
+
+
+def read(path: str) -> tuple[dict[str, Unit], dict[str, Unit], Unit]:
+ root = ET.parse(path).getroot()
+ packages: dict[str, Unit] = defaultdict(Unit)
+ classes: dict[str, Unit] = defaultdict(Unit)
+ overall = Unit()
+ m, c = counter(root)
+ overall.missed, overall.covered = m, c
+ for pkg in root.findall("package"):
+ pname = (pkg.get("name") or "").replace("/", ".")
+ pm, pc = counter(pkg)
+ packages[pname].missed += pm
+ packages[pname].covered += pc
+ for cls in pkg.findall("class"):
+ cname = (cls.get("name") or "").replace("/", ".")
+ # Fold Compose's synthetic classes into the file they came from.
+ owner = re.split(SYNTHETIC, cname)[0] or cname
+ cm, cc = counter(cls)
+ classes[owner].missed += cm
+ classes[owner].covered += cc
+ return dict(packages), dict(classes), overall
+
+
+def main() -> int:
+ if len(sys.argv) < 2:
+ print(__doc__)
+ return 2
+ packages, classes, overall = read(sys.argv[1])
+ print(f"overall lines: {overall.covered}/{overall.total} ({overall.pct:.1f}%)")
+ # What of the shortfall is even reachable.
+ repo = Path(__file__).resolve().parent.parent.parent
+ try:
+ missed, covered, in_preview = source_misses(sys.argv[1], preview_lines(repo))
+ except Exception: # noqa: BLE001
+ in_preview = 0
+ in_dead = 0
+ if "--dead" in sys.argv:
+ # Opt-in: the dead-code search takes a few minutes, which is too slow
+ # for a report meant to be read while a round runs.
+ try:
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
+ import deadcode
+ found, _ = deadcode.dead(repo, deadcode.MODULES["terminal"])
+ dead_by_file: dict[str, set[int]] = defaultdict(set)
+ for d in found:
+ dead_by_file[d.path.name].update(range(d.start, d.end + 1))
+ root = ET.parse(sys.argv[1]).getroot()
+ previews = preview_lines(repo)
+ for pkg in root.findall("package"):
+ for sf in pkg.findall("sourcefile"):
+ name = sf.get("name") or ""
+ pv = previews.get(name, set())
+ dd = dead_by_file.get(name, set())
+ for line in sf.findall("line"):
+ nr = int(line.get("nr", 0))
+ if int(line.get("ci", 0)) or not int(line.get("mi", 0)):
+ continue
+ if nr in dd and nr not in pv:
+ in_dead += 1
+ except Exception as e: # noqa: BLE001
+ print(f" (dead-code pass failed: {e})")
+ if in_preview:
+ reachable = covered + missed - in_preview - in_dead
+ print(f" of the {missed} missed lines, {in_preview} are in bodies "
+ f"this build type cannot reach at all")
+ if in_dead:
+ print(f" of the rest, {in_dead} are in declarations nothing "
+ f"refers to (deadcode.py)")
+ print(f" reachable lines covered: {covered}/{reachable} "
+ f"({100.0 * covered / reachable:.1f}%); the highest this report "
+ f"can ever read is {100.0 * reachable / (covered + missed):.1f}%")
+ if not in_dead:
+ print(" (pass --dead to discount unreachable declarations too)")
+ print()
+
+ if "--since" in sys.argv:
+ before_path = sys.argv[sys.argv.index("--since") + 1]
+ bp, bc, bo = read(before_path)
+ print(f"since {before_path}: {bo.covered} -> {overall.covered} lines "
+ f"({bo.pct:.1f}% -> {overall.pct:.1f}%)\n")
+ moved = sorted(
+ ((name, u.covered - bc.get(name, Unit()).covered, u)
+ for name, u in classes.items()),
+ key=lambda row: -row[1],
+ )
+ print("newly covered (top 15):")
+ for name, delta, u in moved[:15]:
+ if delta <= 0:
+ break
+ print(f" +{delta:5} {u.pct:5.1f}% {name.split('.')[-1]}")
+ print()
+
+ try:
+ reachable_by_pkg = reachable_misses_by_package(sys.argv[1], preview_lines(repo))
+ except Exception: # noqa: BLE001
+ reachable_by_pkg = {}
+
+ print("packages by missed lines that can actually be reached:")
+ ranked = sorted(packages.items(),
+ key=lambda kv: -reachable_by_pkg.get(kv[0], kv[1].missed))
+ for name, u in ranked[:18]:
+ short = name.replace("net.taler.merchantpos", "~").replace("net.taler.common", "common")
+ reach = reachable_by_pkg.get(name)
+ extra = "" if reach is None else f" ({u.missed} counting unreachable)"
+ print(f" {reach if reach is not None else u.missed:6} missed "
+ f"{u.pct:5.1f}% {short}{extra}")
+
+ print("\nuntouched classes with the most lines (0% covered):")
+ untouched = [(n, u) for n, u in classes.items() if u.covered == 0 and u.total >= 12]
+ for name, u in sorted(untouched, key=lambda kv: -kv[1].missed)[:25]:
+ print(f" {u.missed:6} lines {name}")
+
+ print("\npartly covered, biggest remainder:")
+ partial = [(n, u) for n, u in classes.items() if u.covered > 0 and u.missed >= 25]
+ for name, u in sorted(partial, key=lambda kv: -kv[1].missed)[:20]:
+ print(f" {u.missed:6} missed {u.pct:5.1f}% {name.split('.')[-1]}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/pos-simulator/coverage/report.sh b/pos-simulator/coverage/report.sh
@@ -0,0 +1,150 @@
+#!/bin/bash
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+#
+# Turn collected .ec files into a coverage report.
+#
+# Runs on the *build* host, not on the emulator host: the report needs the
+# uninstrumented class files and the sources, which only exist where the APK
+# was built. Collect the .ec files first (driver/coverage.py writes them on
+# the emulator host; rsync them here).
+#
+# Usage: report.sh <dir-with-.ec-files> [out-dir]
+#
+# One warning about the input: jacoco matches execution data to classes by a
+# checksum of the class file, so data recorded by one APK is dropped (with
+# "Execution data for class ... does not match") when reported against a
+# different build. Resources are enough to do it -- an added res/ file shifts
+# the inlined R constants -- so rebuilding the APK starts a new coverage
+# baseline, and .ec files from before it have to be reported separately or not
+# at all.
+
+set -eu
+
+EC_DIR=${1:?usage: report.sh <dir-with-.ec-files> [out-dir]}
+OUT_DIR=${2:-$(cd "$(dirname "$0")/.." && pwd)/out/coverage}
+REPO=$(cd "$(dirname "$0")/../.." && pwd)
+VARIANT=${POS_VARIANT:-sim}
+JACOCO_VERSION=${JACOCO_VERSION:-0.8.14}
+CACHE=${POS_TOOLS:-$HOME/.cache/taler-pos-sim}
+CLI="$CACHE/org.jacoco.cli-$JACOCO_VERSION-nodeps.jar"
+
+mkdir -p "$CACHE" "$OUT_DIR"
+if [ ! -s "$CLI" ]; then
+ echo "fetching jacoco cli $JACOCO_VERSION" >&2
+ curl -sSfL -o "$CLI" \
+ "https://repo1.maven.org/maven2/org/jacoco/org.jacoco.cli/$JACOCO_VERSION/org.jacoco.cli-$JACOCO_VERSION-nodeps.jar"
+fi
+
+# One truncated .ec -- a dump whose app was killed mid-write -- makes jacoco's
+# `merge` abort over every other file, so the files are checked first and only
+# the complete ones go in.
+mapfile -t EC_FILES < <(python3 "$(dirname "$0")/validate_ec.py" "$EC_DIR")
+[ "${#EC_FILES[@]}" -gt 0 ] || { echo "no usable .ec files under $EC_DIR" >&2; exit 1; }
+echo "merging ${#EC_FILES[@]} execution data file(s)" >&2
+
+if [ -n "${JAVA_HOME:-}" ] && [ -x "$JAVA_HOME/bin/java" ]; then
+ JAVA="$JAVA_HOME/bin/java"
+else
+ JAVA=$(command -v java) ||
+ { echo "no java on PATH and no usable JAVA_HOME" >&2; exit 1; }
+fi
+MERGED="$OUT_DIR/merged.exec"
+# `merge` appends to an existing --destfile, which silently doubles everything
+# on a second run.
+rm -f "$MERGED"
+"$JAVA" -jar "$CLI" merge "${EC_FILES[@]}" --destfile "$MERGED"
+
+# The emulator is not the only thing that covers this app: merchant-terminal
+# carries ~290 JVM unit tests, and a report that cannot see them invites us to
+# spend emulator time re-covering what a unit test already reaches. So both
+# are reported: the simulator alone, which is what a round of scenarios
+# achieved, and the union, which is what is actually tested.
+#
+# `enableUnitTestCoverage` in merchant-terminal/build.gradle is what produces
+# the second file; POS_UNIT_EXEC=0 leaves it out, or names one explicitly.
+UNIT_EXEC=${POS_UNIT_EXEC:-auto}
+if [ "$UNIT_EXEC" = "auto" ]; then
+ UNIT_EXEC=$(ls -1 "$REPO/merchant-terminal/build/outputs/unit_test_code_coverage/"*/*.exec 2>/dev/null | head -1 || true)
+fi
+UNION=""
+if [ -n "$UNIT_EXEC" ] && [ "$UNIT_EXEC" != "0" ] && [ -s "$UNIT_EXEC" ]; then
+ UNION="$OUT_DIR/merged-with-units.exec"
+ rm -f "$UNION"
+ "$JAVA" -jar "$CLI" merge "${EC_FILES[@]}" "$UNIT_EXEC" --destfile "$UNION"
+ echo "including unit-test coverage from $UNIT_EXEC" >&2
+else
+ echo "no unit-test coverage merged (run :merchant-terminal:testSimUnitTest)" >&2
+fi
+
+# Kotlin and Java classes land in separate trees; both belong in the report,
+# and both must be the uninstrumented ones.
+CLASS_ARGS=()
+for d in "$REPO/merchant-terminal/build/tmp/kotlin-classes/$VARIANT" \
+ "$REPO/merchant-terminal/build/intermediates/javac/$VARIANT/classes"; do
+ [ -d "$d" ] && CLASS_ARGS+=(--classfiles "$d")
+done
+[ "${#CLASS_ARGS[@]}" -gt 0 ] || { echo "no class files for variant $VARIANT" >&2; exit 1; }
+
+# The terminal's own sources plus the two libraries it is a thin layer over:
+# merchant-lib is where every backend call lives and taler-kotlin-android
+# holds Amount and the NFC service, so leaving them out would overstate how
+# much of what runs is covered.
+"$JAVA" -jar "$CLI" report "$MERGED" \
+ "${CLASS_ARGS[@]}" \
+ --sourcefiles "$REPO/merchant-terminal/src/main/java" \
+ --sourcefiles "$REPO/merchant-lib/src/main/java" \
+ --sourcefiles "$REPO/taler-kotlin-android/src/main/java" \
+ --html "$OUT_DIR/html" \
+ --xml "$OUT_DIR/coverage.xml" \
+ --name "Taler POS simulator ($VARIANT)"
+
+python3 - "$OUT_DIR/coverage.xml" <<'PY'
+import sys, xml.etree.ElementTree as ET
+root = ET.parse(sys.argv[1]).getroot()
+print()
+for counter in root.findall("counter"):
+ t = counter.get("type")
+ covered, missed = int(counter.get("covered")), int(counter.get("missed"))
+ total = covered + missed
+ if total:
+ print(f"{t.lower():12} {covered:7}/{total:<7} {100 * covered / total:5.1f}%")
+PY
+if [ -n "$UNION" ]; then
+ "$JAVA" -jar "$CLI" report "$UNION" \
+ "${CLASS_ARGS[@]}" \
+ --sourcefiles "$REPO/merchant-terminal/src/main/java" \
+ --sourcefiles "$REPO/merchant-lib/src/main/java" \
+ --sourcefiles "$REPO/taler-kotlin-android/src/main/java" \
+ --html "$OUT_DIR/html-with-units" \
+ --xml "$OUT_DIR/coverage-with-units.xml" \
+ --name "Taler POS simulator + unit tests ($VARIANT)" >/dev/null
+ echo
+ echo "simulator and unit tests together:"
+ python3 "$(dirname "$0")/union_summary.py" \
+ "$OUT_DIR/coverage-with-units.xml" "$OUT_DIR/coverage.xml"
+fi
+
+# A landing page over the top of JaCoCo's own, because JaCoCo cannot know
+# which of the red lines this build type could never enter, nor what produced
+# the figures. Failure here must not fail the run: the numbers above are the
+# deliverable and this is a convenience.
+python3 "$(dirname "$0")/summary_html.py" "$OUT_DIR" "$EC_DIR" \
+ || echo "summary page not written" >&2
+
+echo
+echo "summary: $OUT_DIR/index.html" >&2
+echo "report: $OUT_DIR/html/index.html" >&2
+[ -n "$UNION" ] && echo "union: $OUT_DIR/html-with-units/index.html" >&2
+
diff --git a/pos-simulator/coverage/summary_html.py b/pos-simulator/coverage/summary_html.py
@@ -0,0 +1,373 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""A landing page for a coverage run, over the top of JaCoCo's own report.
+
+JaCoCo already writes the lcov-genhtml equivalent -- a source-annotated page
+per class, green and red down the gutter. What it cannot write is the part
+that needs this harness's own knowledge:
+
+* **what is actually reachable.** JaCoCo paints the screenshot-only
+ composables and the dead functions of bugs.gnunet.org 11981 the same red as
+ everything else, so its totals and `gaps.py`'s disagree by a couple of
+ points and a reader cannot tell which lines are worth anyone's time;
+* **what produced the figures** -- how many execution-data files, from which
+ scenarios, against which commit. A coverage number with no provenance is a
+ number somebody will quote six weeks later without knowing it came from a
+ half-finished run.
+
+So this writes `index.html` beside JaCoCo's, links into it, and says both.
+
+ summary_html.py <out-dir> [ec-dir] [--title NAME]
+"""
+
+from __future__ import annotations
+
+import html
+import subprocess
+import sys
+import time
+import xml.etree.ElementTree as ET
+from collections import defaultdict
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import gaps
+
+REPO = Path(__file__).resolve().parent.parent.parent
+KINDS = ("instruction", "branch", "line", "complexity", "method", "class")
+
+
+def counters(path: Path) -> dict[str, tuple[int, int]]:
+ root = ET.parse(path).getroot()
+ return {c.get("type", "").lower(): (int(c.get("covered", 0)),
+ int(c.get("missed", 0)))
+ for c in root.findall("counter")}
+
+
+def scenarios_from(ec_dir: Path | None) -> list[str]:
+ """Which scenarios contributed execution data, from the file names."""
+ if ec_dir is None or not ec_dir.is_dir():
+ return []
+ import re
+ names = set()
+ for f in ec_dir.glob("*.ec"):
+ # "<scenario>-NN-<label>.ec": the sequence number and whatever the
+ # dump was called. Stripping only the two labels this harness
+ # happened to use listed `login_url_shapes-02` beside
+ # `login_url_shapes`, and every exploration step as its own scenario.
+ names.add(re.sub(r"-\d{2}(-[\w-]+)?$", "", f.stem))
+ return sorted(names)
+
+
+def commit() -> str:
+ try:
+ out = subprocess.run(["git", "-C", str(REPO), "log", "-1",
+ "--format=%h %s"], capture_output=True,
+ text=True, timeout=10)
+ return out.stdout.strip() or "unknown"
+ except Exception:
+ return "unknown"
+
+
+def top_uncovered(path: Path, skip: dict[str, set[int]], limit: int = 25):
+ """The biggest wholly-uncovered methods that are not known-unreachable."""
+ root = ET.parse(path).getroot()
+ rows = []
+ for pkg in root.findall("package"):
+ for cls in pkg.findall("class"):
+ source = cls.get("sourcefilename") or ""
+ skipped = skip.get(source, set())
+ for m in cls.findall("method"):
+ c = m.find("counter[@type='LINE']")
+ if c is None:
+ continue
+ missed, covered = int(c.get("missed", 0)), int(c.get("covered", 0))
+ if covered or missed < 4:
+ continue
+ first = int(m.get("line", 0) or 0)
+ if first and first in skipped:
+ continue # a body this build type cannot enter
+ rows.append((missed,
+ cls.get("name", "").rsplit("/", 1)[-1],
+ m.get("name", ""), source))
+ rows.sort(reverse=True)
+ return rows[:limit]
+
+
+def bar(pct: float) -> str:
+ good = "var(--ok)" if pct >= 80 else ("var(--mid)" if pct >= 55 else "var(--bad)")
+ return (f'<span class="bar"><span style="width:{pct:.1f}%;'
+ f'background:{good}"></span></span>')
+
+
+def main(argv: list[str]) -> int:
+ title = "POS simulator"
+ if "--title" in argv:
+ i = argv.index("--title")
+ title = argv[i + 1]
+ del argv[i:i + 2]
+ out_dir = Path(argv[0]) if argv else Path("out/coverage")
+ ec_dir = Path(argv[1]) if len(argv) > 1 else None
+ sim_xml = out_dir / "coverage.xml"
+ if not sim_xml.exists():
+ print(f"no coverage.xml in {out_dir}", file=sys.stderr)
+ return 1
+ union_xml = out_dir / "coverage-with-units.xml"
+ has_union = union_xml.exists()
+
+ skip = gaps.preview_lines(REPO)
+ missed, covered, unreachable = gaps.source_misses(str(sim_xml), skip)
+ reachable_total = covered + missed - unreachable
+ reachable_pct = 100 * covered / reachable_total if reachable_total else 0.0
+
+ sim = counters(sim_xml)
+ union = counters(union_xml) if has_union else {}
+ by_pkg = gaps.reachable_misses_by_package(str(sim_xml), skip)
+ raw_pkg: dict[str, int] = defaultdict(int)
+ root = ET.parse(sim_xml).getroot()
+ pkg_cov: dict[str, tuple[int, int]] = {}
+ for pkg in root.findall("package"):
+ name = (pkg.get("name") or "").replace("/", ".")
+ c = pkg.find("counter[@type='LINE']")
+ if c is not None:
+ pkg_cov[name] = (int(c.get("covered", 0)), int(c.get("missed", 0)))
+ raw_pkg[name] = int(c.get("missed", 0))
+
+ dead = sum(len(v) for v in gaps.dead_lines(REPO).values())
+ debug_only = sum(len(v) for v in gaps.debug_only_lines(REPO).values())
+ scenarios = scenarios_from(ec_dir)
+ ec_count = len(list(ec_dir.glob("*.ec"))) if ec_dir and ec_dir.is_dir() else 0
+
+ def pct(pair: tuple[int, int]) -> float:
+ cov, mis = pair
+ return 100 * cov / (cov + mis) if cov + mis else 0.0
+
+ rows_counters = []
+ for kind in KINDS:
+ if kind not in sim:
+ continue
+ cov, mis = sim[kind]
+ cell_union = ""
+ if has_union and kind in union:
+ ucov, umis = union[kind]
+ cell_union = (f"<td class='num'>{ucov:,}/{ucov + umis:,}</td>"
+ f"<td class='num'>{pct(union[kind]):.1f}%</td>"
+ f"<td class='num delta'>+{ucov - cov:,}</td>")
+ rows_counters.append(
+ f"<tr><th scope='row'>{kind}</th>"
+ f"<td class='num'>{cov:,}/{cov + mis:,}</td>"
+ f"<td class='num'>{pct(sim[kind]):.1f}%</td>"
+ f"<td>{bar(pct(sim[kind]))}</td>{cell_union}</tr>")
+
+ rows_pkg = []
+ for name in sorted(by_pkg, key=lambda k: -by_pkg[k]):
+ short = name.replace("net.taler.merchantpos", "~")
+ cov, mis = pkg_cov.get(name, (0, 0))
+ p = pct((cov, mis))
+ hidden = raw_pkg[name] - by_pkg[name]
+ note = f"<span class='muted'>({hidden} unreachable)</span>" if hidden else ""
+ rows_pkg.append(
+ f"<tr><th scope='row'><a href='html/{html.escape(name)}/index.html'>"
+ f"{html.escape(short)}</a></th>"
+ f"<td class='num'>{by_pkg[name]:,}</td>"
+ f"<td class='num'>{p:.1f}%</td><td>{bar(p)}</td><td>{note}</td></tr>")
+
+ rows_methods = []
+ for miss, cls, meth, source in top_uncovered(sim_xml, skip):
+ rows_methods.append(
+ f"<tr><td class='num'>{miss}</td>"
+ f"<td><code>{html.escape(cls)}.{html.escape(meth)}</code></td>"
+ f"<td class='muted'>{html.escape(source)}</td></tr>")
+
+ scen_list = ("".join(f"<li>{html.escape(s)}</li>" for s in scenarios)
+ or "<li class='muted'>no scenario names in the execution data</li>")
+ union_head = ("<th scope='col' colspan='3'>with unit tests</th>"
+ if has_union else "")
+ union_sub = ("<th scope='col' class='num'>covered</th>"
+ "<th scope='col' class='num'>%</th>"
+ "<th scope='col' class='num'>gain</th>" if has_union else "")
+ union_link = ("<a class='btn' href='html-with-units/index.html'>"
+ "JaCoCo report, with unit tests</a>" if has_union else "")
+
+ # Cards only where they mean something. Run repo-wide from CI there is no
+ # union file and no execution data from an emulator, and a "--%" card
+ # beside a "0 scenarios" one reads as a broken report rather than as a
+ # report of something narrower.
+ reach_card = ""
+ if unreachable:
+ reach_card = (f'<div class="card"><div class="big">{reachable_pct:.1f}%</div>'
+ f'<div class="lbl">of the {reachable_total:,} lines this '
+ f'build type can reach</div></div>')
+ union_card = ""
+ if has_union:
+ union_card = (f'<div class="card"><div class="big">'
+ f'{pct(union.get("line", (0, 0))):.1f}%</div>'
+ f'<div class="lbl">lines, with the JVM unit tests '
+ f'merged</div></div>')
+ scen_card = ""
+ if ec_count:
+ scen_card = (f'<div class="card"><div class="big">{ec_count}</div>'
+ f'<div class="lbl">execution-data files, '
+ f'{len(scenarios)} scenarios</div></div>')
+
+ page = TEMPLATE.format(
+ generated=time.strftime("%Y-%m-%d %H:%M:%S %Z"),
+ commit=html.escape(commit()),
+ line_pct=f"{pct(sim.get('line', (0, 0))):.1f}",
+ line_cov=f"{sim.get('line', (0, 0))[0]:,}",
+ line_tot=f"{sum(sim.get('line', (0, 0))):,}",
+ unreachable=f"{unreachable:,}",
+ debug_only=f"{debug_only:,}",
+ dead=f"{dead:,}",
+ marked=f"{debug_only + dead:,}",
+ rows_counters="".join(rows_counters),
+ rows_pkg="".join(rows_pkg),
+ rows_methods="".join(rows_methods) or
+ "<tr><td colspan='3' class='muted'>nothing reachable above the threshold</td></tr>",
+ provenance=("<h2>What produced this</h2>"
+ f"<ul class='cols'>{scen_list}</ul>" if scenarios else ""),
+ union_head=union_head,
+ union_sub=union_sub,
+ union_link=union_link,
+ title=html.escape(title),
+ reach_card=reach_card,
+ union_card=union_card,
+ scen_card=scen_card,
+ )
+ target = out_dir / "index.html"
+ target.write_text(page, encoding="utf-8")
+ return 0
+
+
+TEMPLATE = """<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{title} coverage</title>
+<style>
+:root {{
+ --bg: #fbfbfd; --fg: #15171c; --muted: #5d6470; --line: #dfe3ea;
+ --card: #ffffff; --accent: #0042b3;
+ --ok: #1f8a4c; --mid: #b4830e; --bad: #b3261e;
+ color-scheme: light dark;
+}}
+@media (prefers-color-scheme: dark) {{
+ :root:not([data-theme="light"]) {{
+ --bg: #11131a; --fg: #e8eaf0; --muted: #9aa3b2; --line: #272c38;
+ --card: #171a22; --accent: #7aa2ff;
+ --ok: #4cc47f; --mid: #e0ad3a; --bad: #ef6a60;
+ }}
+}}
+:root[data-theme="dark"] {{
+ --bg: #11131a; --fg: #e8eaf0; --muted: #9aa3b2; --line: #272c38;
+ --card: #171a22; --accent: #7aa2ff;
+ --ok: #4cc47f; --mid: #e0ad3a; --bad: #ef6a60;
+}}
+* {{ box-sizing: border-box; }}
+body {{
+ margin: 0; background: var(--bg); color: var(--fg);
+ font: 15px/1.55 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}}
+.wrap {{ max-width: 1040px; margin: 0 auto; padding: 32px 16px 72px; }}
+h1 {{ font-size: 1.6rem; margin: 0 0 4px; letter-spacing: -0.01em; }}
+h2 {{ font-size: 1.05rem; margin: 36px 0 10px; letter-spacing: -0.005em; }}
+p.sub {{ color: var(--muted); margin: 0 0 28px; }}
+.cards {{ display: grid; gap: 12px; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); }}
+.card {{ background: var(--card); border: 1px solid var(--line); border-radius: 12px; padding: 14px 16px; }}
+.card .big {{ font-size: 2rem; font-weight: 650; letter-spacing: -0.02em; }}
+.card .lbl {{ color: var(--muted); font-size: 0.82rem; }}
+table {{ width: 100%; border-collapse: collapse; background: var(--card);
+ border: 1px solid var(--line); border-radius: 12px; overflow: hidden; }}
+th, td {{ text-align: left; padding: 8px 12px; border-bottom: 1px solid var(--line); }}
+thead th {{ font-size: 0.78rem; text-transform: uppercase; letter-spacing: 0.04em;
+ color: var(--muted); font-weight: 600; }}
+tbody tr:last-child td, tbody tr:last-child th {{ border-bottom: 0; }}
+td.num, th.num {{ text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; }}
+td.delta {{ color: var(--muted); }}
+.muted {{ color: var(--muted); }}
+code {{ font: 0.86em ui-monospace, SFMono-Regular, Menlo, monospace; }}
+a {{ color: var(--accent); }}
+.bar {{ display: block; width: 100%; min-width: 80px; height: 7px; border-radius: 4px;
+ background: color-mix(in srgb, var(--line) 80%, transparent); overflow: hidden; }}
+.bar > span {{ display: block; height: 100%; }}
+.btn {{ display: inline-block; padding: 9px 14px; border-radius: 9px;
+ border: 1px solid var(--line); background: var(--card);
+ text-decoration: none; margin: 0 8px 8px 0; font-weight: 550; }}
+ul.cols {{ columns: 3 200px; margin: 0; padding-left: 1.1rem; color: var(--muted); font-size: .9rem; }}
+@media (max-width: 560px) {{ .wrap {{ padding: 20px 16px 56px; }} }}
+</style>
+<div class="wrap">
+<h1>{title} coverage</h1>
+<p class="sub">{generated} · {commit}</p>
+
+<div class="cards">
+ <div class="card"><div class="big">{line_pct}%</div>
+ <div class="lbl">lines, {line_cov} of {line_tot}</div></div>
+ {reach_card}{union_card}{scen_card}
+</div>
+
+<h2>Totals</h2>
+<table>
+<thead><tr><th scope="col">counter</th>
+<th scope="col" colspan="3">simulator</th>{union_head}</tr>
+<tr><th scope="col"></th>
+<th scope="col" class="num">covered</th><th scope="col" class="num">%</th>
+<th scope="col"></th>{union_sub}</tr></thead>
+<tbody>{rows_counters}</tbody>
+</table>
+
+<h2>Packages, ranked by what can still be reached</h2>
+<p class="sub">Lines inside screenshot-only composables and the dead functions of
+<a href="https://bugs.gnunet.org/view?id=11981">11981</a> are left out of the
+ranking: counting them points the next round at work nobody can do. JaCoCo's
+own pages below still paint them red, because JaCoCo does not know about them.</p>
+<table>
+<thead><tr><th scope="col">package</th><th scope="col" class="num">reachable missed</th>
+<th scope="col" class="num">covered</th><th scope="col"></th><th scope="col"></th></tr></thead>
+<tbody>{rows_pkg}</tbody>
+</table>
+
+<h2>Biggest untouched methods, known-unreachable ones removed</h2>
+<p class="sub">Still includes what needs hardware or a credential this build
+does not have — <code>sumup</code> wants an affiliate key and a card
+reader, <code>devices</code> a Bluetooth or USB display, and
+<code>reportNfcPayload</code> an NFC adapter no emulator provides. Those are
+reachable in principle and not by us.</p>
+<table>
+<thead><tr><th scope="col" class="num">lines</th><th scope="col">method</th>
+<th scope="col">file</th></tr></thead>
+<tbody>{rows_methods}</tbody>
+</table>
+
+<h2>Known unreachable</h2>
+<p class="sub">{marked} source lines are marked as impossible for a
+<code>sim</code> build to enter — {debug_only} in composables whose only
+caller is the <code>debug</code> source set, {dead} in functions with no caller
+at all (<a href="https://bugs.gnunet.org/view?id=11981">11981</a>). Of those,
+<strong>{unreachable}</strong> are lines JaCoCo counted as missed, and it is
+that figure which comes off the denominator above.</p>
+
+<h2>The full report</h2>
+<p><a class="btn" href="html/index.html">JaCoCo report, simulator only</a>
+{union_link}</p>
+
+{provenance}
+</div>
+</html>
+"""
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/pos-simulator/coverage/union_summary.py b/pos-simulator/coverage/union_summary.py
@@ -0,0 +1,45 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Print the union of the simulator and the unit tests, and what each adds.
+
+ union_summary.py coverage-with-units.xml coverage.xml
+
+The second figure is the one that changes what to do next: a line the unit
+tests already reach is a line not worth an emulator and ninety seconds.
+"""
+
+import sys
+import xml.etree.ElementTree as ET
+
+
+def counters(path: str) -> dict[str, tuple[int, int]]:
+ root = ET.parse(path).getroot()
+ return {c.get("type"): (int(c.get("covered")), int(c.get("missed")))
+ for c in root.findall("counter")}
+
+
+def main(argv: list[str]) -> int:
+ both, sim = counters(argv[0]), counters(argv[1])
+ for kind, (covered, missed) in both.items():
+ total = covered + missed
+ if not total:
+ continue
+ gained = covered - sim.get(kind, (0, 0))[0]
+ print(f"{kind.lower():12} {covered:7}/{total:<7} "
+ f"{100 * covered / total:5.1f}% (+{gained} from unit tests)")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/pos-simulator/coverage/validate_ec.py b/pos-simulator/coverage/validate_ec.py
@@ -0,0 +1,131 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Print the .ec files that are complete execution data, skip the rest.
+
+A dump whose app was killed while writing leaves a truncated file, and jacoco's
+`merge` aborts on the first one it cannot read -- so one bad file out of a
+thousand loses a whole campaign's coverage. Rather than merge in batches and
+guess, this walks each file's block structure once and keeps only the files
+that end on a block boundary.
+
+ python3 validate_ec.py <dir> [--quiet] # one good path per line on stdout
+
+The format is org.jacoco.core.data.ExecutionDataWriter's: a header block, then
+session-info and execution-data blocks, with Java DataOutput encodings and
+jacoco's own var-int for array lengths.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+BLOCK_HEADER = 0x01
+BLOCK_SESSIONINFO = 0x10
+BLOCK_EXECUTIONDATA = 0x11
+MAGIC = 0xC0C0
+
+
+class Truncated(Exception):
+ pass
+
+
+class Reader:
+ def __init__(self, data: bytes) -> None:
+ self.data = data
+ self.pos = 0
+
+ def take(self, n: int) -> bytes:
+ if self.pos + n > len(self.data):
+ raise Truncated(f"wanted {n} bytes at {self.pos} of {len(self.data)}")
+ out = self.data[self.pos:self.pos + n]
+ self.pos += n
+ return out
+
+ def u8(self) -> int:
+ return self.take(1)[0]
+
+ def u16(self) -> int:
+ return int.from_bytes(self.take(2), "big")
+
+ def u64(self) -> int:
+ return int.from_bytes(self.take(8), "big")
+
+ def utf(self) -> bytes:
+ return self.take(self.u16())
+
+ def var_int(self) -> int:
+ value, shift = 0, 0
+ while True:
+ b = self.u8()
+ value |= (b & 0x7F) << shift
+ if not b & 0x80:
+ return value
+ shift += 7
+
+ def boolean_array(self) -> None:
+ bits = self.var_int()
+ self.take((bits + 7) // 8)
+
+
+def complete(path: Path) -> bool:
+ """Whether this file is execution data all the way to its last byte."""
+ r = Reader(path.read_bytes())
+ if not r.data:
+ return False
+ try:
+ while r.pos < len(r.data):
+ block = r.u8()
+ if block == BLOCK_HEADER:
+ if r.u16() != MAGIC:
+ return False
+ r.u16() # format version
+ elif block == BLOCK_SESSIONINFO:
+ r.utf()
+ r.u64() # start
+ r.u64() # dump
+ elif block == BLOCK_EXECUTIONDATA:
+ r.u64() # class id
+ r.utf() # class name
+ r.boolean_array()
+ else:
+ return False
+ except Truncated:
+ return False
+ return True
+
+
+def main() -> int:
+ if len(sys.argv) < 2:
+ print(__doc__, file=sys.stderr)
+ return 2
+ quiet = "--quiet" in sys.argv
+ files = sorted(Path(sys.argv[1]).rglob("*.ec"))
+ good = []
+ for f in files:
+ if complete(f):
+ good.append(f)
+ elif not quiet:
+ print(f"skipping incomplete {f} ({f.stat().st_size} bytes)",
+ file=sys.stderr)
+ if not quiet:
+ print(f"{len(good)} of {len(files)} execution data files are complete",
+ file=sys.stderr)
+ for f in good:
+ print(f)
+ return 0 if good else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/pos-simulator/driver/campaign.py b/pos-simulator/driver/campaign.py
@@ -0,0 +1,195 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Run the suite, or an exploration, across several emulators at once.
+
+Sharding is by tag, not round-robin, and that is deliberate. The `demo`
+scenarios all talk to the same shared `sandbox` instance, and two of them
+running at once would see each other's orders in the history list -- so they
+stay on one worker, and the `mock` scenarios, which each bring their own
+backend, go on the others.
+
+ python3 campaign.py suite --workers 2
+ python3 campaign.py suite --workers 4 --tag mock
+ python3 campaign.py explore --workers 2 --steps 200
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+SIM_ROOT = Path(os.environ.get("POS_SIM_ROOT", "/tmp/taler-pos-sim"))
+
+
+def scenarios_matching(tags: list[str], skip: list[str]) -> list[str]:
+ """The scenario names a tag selection covers, from the registry itself.
+
+ Imported rather than parsed out of `suite.py --list`: the listing is for
+ people, and a selection built by matching its text picked up scenarios
+ whose *description* happened to contain the tag.
+ """
+ import suite
+ out = []
+ for name, (_, scenario_tags, _) in suite.SCENARIOS.items():
+ if tags and not set(tags) & set(scenario_tags):
+ continue
+ if set(skip) & set(scenario_tags):
+ continue
+ out.append(name)
+ return out
+
+
+def shard_suite(workers: int, tags: list[str], skip: list[str]) -> list[list[str]]:
+ """The arguments for each worker's suite process.
+
+ Sharding is by tag rather than round-robin because the `demo` scenarios
+ all talk to the same shared `sandbox` instance: two of them at once would
+ see each other's orders in the history list, and one would delete an order
+ the other was waiting on. So they stay on one worker, and the `mock`
+ scenarios -- which each bring a backend of their own on a port of their
+ own -- are split across the rest.
+ """
+ if tags:
+ # An explicit selection means the caller has said these may run beside
+ # each other, so they are split evenly.
+ chosen = scenarios_matching(tags, skip)
+ shards: list[list[str]] = [[] for _ in range(workers)]
+ for i, name in enumerate(chosen):
+ shards[i % workers].append(name)
+ return [s for s in shards if s]
+
+ plans: list[list[str]] = [["--all", "--skip-tag", "mock"]]
+ for t in skip:
+ plans[0] += ["--skip-tag", t]
+ mock = scenarios_matching(["mock"], skip)
+ # The scenarios tagged "form" are about the login form itself, and the
+ # form is unusable on a phone (findings/login-form-collapses-under-the-
+ # keyboard.md). Worker 0 is the tablet, so they go there with the demo
+ # set rather than onto a worker that can only report that they could not
+ # be reached.
+ needs_form = set(scenarios_matching(["form"], skip))
+ if needs_form:
+ mock = [n for n in mock if n not in needs_form]
+ # Scenarios whose point is the *phone* half of a layout. Worker 0 is a
+ # tablet by convention, so running them there passes trivially and proves
+ # nothing: `login_form_fits_a_phone` is green on a tablet because the form
+ # fits. POS_PHONE_WORKERS names the workers whose AVD is phone-sized.
+ phone_workers = [int(w) for w in
+ os.environ.get("POS_PHONE_WORKERS", "1,2").split(",")
+ if w.strip().isdigit()]
+ needs_phone = set(scenarios_matching(["phone"], skip))
+ mock_workers = max(0, workers - 1)
+ if mock_workers == 0:
+ # One worker runs everything, in one process.
+ return [["--all"] + [a for t in skip for a in ("--skip-tag", t)]]
+ for i in range(mock_workers):
+ share = mock[i::mock_workers]
+ if share:
+ plans.append(share)
+ if needs_form:
+ # Appended as explicit names after worker 0's "--all --skip-tag mock",
+ # which would otherwise leave them out for being mock scenarios.
+ plans[0] = plans[0] + sorted(needs_form)
+ if needs_phone:
+ target = next((w for w in phone_workers if 0 < w < max(workers, 1)), None)
+ if target is not None and target < len(plans):
+ plans[target] = plans[target] + sorted(needs_phone)
+ # and off the tablet, where they prove nothing
+ plans[0] = [a for a in plans[0] if a not in needs_phone]
+ plans[0] = plans[0] + ["--skip-tag", "phone"]
+ return plans[:workers]
+
+def launch(worker: int, argv: list[str], out: Path, tag: str,
+ exclusive_demo: bool = True) -> subprocess.Popen:
+ env = dict(os.environ)
+ env["POS_WORKER"] = str(worker)
+ env["POS_MOCK_PORT"] = str(19443 + worker)
+ # `suite.py` said "the campaign sets it" and the campaign did not, so
+ # every run asserted an exclusivity nobody had established. It is set
+ # here now, and it is only true for the one worker that owns the demo
+ # plan: the others bring a mock backend of their own, and anything run by
+ # hand beside the campaign is not accounted for either way.
+ env["POS_EXCLUSIVE_DEMO"] = "1" if exclusive_demo else "0"
+ log = SIM_ROOT / "run" / f"{tag}-w{worker}.log"
+ log.parent.mkdir(parents=True, exist_ok=True)
+ handle = open(log, "w")
+ # -u matters: without it a worker's progress sits in a pipe buffer and the
+ # log stays empty for the whole run, which looks exactly like a hang.
+ proc = subprocess.Popen(
+ [sys.executable, "-u", *argv, "--out", str(out / f"w{worker}")],
+ cwd=str(HERE), env=env, stdout=handle, stderr=subprocess.STDOUT)
+ print(f"worker {worker}: {' '.join(argv[1:])} -> {log}")
+ return proc
+
+
+def main(argv: list[str]) -> int:
+ ap = argparse.ArgumentParser(description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("what", choices=["suite", "explore"])
+ ap.add_argument("--workers", type=int, default=2)
+ ap.add_argument("--tag", action="append", default=[])
+ ap.add_argument("--skip-tag", action="append", default=[])
+ ap.add_argument("--steps", type=int, default=150)
+ ap.add_argument("--seed", type=int, default=None)
+ ap.add_argument("--label", default=None)
+ args = ap.parse_args(argv)
+
+ stamp = time.strftime("%Y%m%d-%H%M%S")
+ label = args.label or f"{args.what}-{stamp}"
+ out = SIM_ROOT / "out" / label
+ out.mkdir(parents=True, exist_ok=True)
+
+ procs = []
+ if args.what == "suite":
+ shards = shard_suite(args.workers, args.tag, args.skip_tag)
+ # Worker 0 is the only one handed the demo set by `shard_suite`; an
+ # explicit --tag selection is split evenly and nobody owns it.
+ owns_demo = 0 if not args.tag else None
+ for worker, plan in enumerate(shards):
+ procs.append(launch(worker, ["suite.py", *plan], out, label,
+ exclusive_demo=(worker == owns_demo)))
+ time.sleep(2) # stagger, so two workers do not mint a token at once
+ else:
+ for worker in range(args.workers):
+ seed = (args.seed or 0) + worker if args.seed is not None else None
+ plan = ["explore.py", "--steps", str(args.steps)]
+ if seed is not None:
+ plan += ["--seed", str(seed)]
+ procs.append(launch(worker, plan, out, label))
+
+ codes = [p.wait() for p in procs]
+ print(f"\n{len(procs)} worker(s) finished with {codes}")
+
+ merged = []
+ for path in sorted(out.rglob("suite.json")):
+ merged += json.loads(path.read_text())
+ if merged:
+ (out / "campaign.json").write_text(json.dumps(merged, indent=2))
+ serious = sum(s.get("serious", 0) for s in merged)
+ unreached = [s["name"] for s in merged if s.get("outcome") == "unreached"]
+ print(f"{len(merged)} scenario(s), {serious} serious finding(s)")
+ if unreached:
+ print(f"unreached: {', '.join(unreached)}")
+ print(f"artifacts: {out}")
+ return 0 if all(c == 0 for c in codes) else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/pos-simulator/driver/counterparty.py b/pos-simulator/driver/counterparty.py
@@ -0,0 +1,368 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""The customer: a bank account and a wallet, driven from the command line.
+
+A point-of-sale terminal does almost nothing on its own. Every interesting
+screen is waiting for a customer to do something -- scan the code, confirm the
+contract, accept a refund -- or to fail to. `taler-wallet-cli` is that
+customer, and this module is the harness's grip on it:
+
+* **pay** a displayed order, which is what turns the payment screen into the
+ success screen;
+* **claim without paying**, which is what puts an order in the one state the
+ terminal needs a force-delete dialog for;
+* **walk away**, which is what the payment timeout is about;
+* **accept a refund**, which is what clears the refund screen.
+
+Money comes from a registered account at the demo bank. A fresh account there
+starts at zero but has a debit threshold, so a withdrawal works immediately
+and no funding step is needed.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import shutil
+import subprocess
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+WALLET_CLI = os.environ.get(
+ "POS_WALLET_CLI",
+ shutil.which("taler-wallet-cli") or "/root/.local/bin/taler-wallet-cli",
+)
+BANK = os.environ.get("POS_BANK", "https://bank.demo.taler.net")
+EXCHANGE = os.environ.get("POS_EXCHANGE", "https://exchange.demo.taler.net/")
+
+
+class WalletError(RuntimeError):
+ pass
+
+
+def _http(method: str, url: str, *, body: Any = None,
+ auth: Optional[tuple[str, str]] = None,
+ expect: tuple[int, ...] = (200, 204)) -> Any:
+ data = json.dumps(body).encode() if body is not None else None
+ headers = {}
+ if data is not None:
+ headers["Content-Type"] = "application/json"
+ if auth:
+ raw = base64.b64encode(f"{auth[0]}:{auth[1]}".encode()).decode()
+ headers["Authorization"] = f"Basic {raw}"
+ req = urllib.request.Request(url, data=data, headers=headers, method=method)
+ try:
+ with urllib.request.urlopen(req, timeout=40) as resp:
+ payload, status = resp.read(), resp.status
+ except urllib.error.HTTPError as e:
+ payload, status = e.read(), e.code
+ if status not in expect:
+ raise WalletError(f"HTTP {status} from {url}: "
+ f"{payload.decode(errors='replace')[:300]}")
+ if not payload:
+ return None
+ try:
+ return json.loads(payload)
+ except json.JSONDecodeError:
+ return payload.decode(errors="replace")
+
+
+@dataclass
+class BankAccount:
+ """A registered account at the demo bank."""
+
+ username: str
+ password: str
+ bank: str = BANK
+
+ @property
+ def auth(self) -> tuple[str, str]:
+ return (self.username, self.password)
+
+ def balance(self) -> str:
+ info = _http("GET", f"{self.bank}/accounts/{self.username}", auth=self.auth)
+ bal = info.get("balance", {})
+ sign = "-" if bal.get("credit_debit_indicator") == "debit" else ""
+ return f"{sign}{bal.get('amount', '?')}"
+
+ def start_withdrawal(self, amount: str) -> tuple[str, str]:
+ """Ask the bank for a withdrawal; returns (withdrawal id, taler URI)."""
+ res = _http("POST", f"{self.bank}/accounts/{self.username}/withdrawals",
+ body={"amount": amount}, auth=self.auth)
+ return res["withdrawal_id"], res["taler_withdraw_uri"]
+
+ def confirm_withdrawal(self, withdrawal_id: str, timeout: int = 90) -> None:
+ """Approve the withdrawal, the way the customer does in their banking app.
+
+ Two traps here, and each one costs a four-hundred-second timeout
+ somewhere else if it is not handled.
+
+ The endpoint lives under the account, not at the bank root: a POST to
+ `/withdrawals/<id>/confirm` answers 404 with "no endpoint defined for
+ the URL", which reads like the withdrawal is gone rather than like a
+ wrong path.
+
+ And it cannot be approved before the wallet has chosen an exchange for
+ it. `taler-wallet-cli withdraw` returns as soon as it has created the
+ transaction, which is a moment or two before that choice reaches the
+ bank, so an immediate confirmation gets a 409 -- and a 409 that is
+ quietly accepted leaves the withdrawal pending forever while the wallet
+ waits for a confirmation that never came. So this retries until the
+ bank takes it.
+ """
+ url = (f"{self.bank}/accounts/{self.username}"
+ f"/withdrawals/{withdrawal_id}/confirm")
+ deadline = time.monotonic() + timeout
+ last = ""
+ while time.monotonic() < deadline:
+ try:
+ _http("POST", url, body={}, auth=self.auth, expect=(204, 200))
+ return
+ except WalletError as e:
+ last = str(e)
+ if "409" not in last:
+ raise
+ time.sleep(2)
+ raise WalletError(
+ f"the bank would not confirm withdrawal {withdrawal_id} within "
+ f"{timeout}s; it is still waiting for the wallet to select an "
+ f"exchange: {last[:200]}")
+
+
+def register_account(username: str, password: str, name: Optional[str] = None,
+ bank: str = BANK) -> BankAccount:
+ """Register a bank account, or adopt the existing one of the same name.
+
+ The demo bank allows registrations and asks for no TAN, so this needs no
+ operator involvement. A repeat registration answers 409, which is fine:
+ the harness wants *an* account by that name, not necessarily a new one --
+ as long as the password still matches. A name somebody else (or an
+ earlier run with a different convention) already took does not, and the
+ 401 only shows up on the next call, several steps away from the cause, so
+ the credential is checked here where it can still be explained.
+ """
+ _http("POST", f"{bank}/accounts",
+ body={"username": username, "password": password,
+ "name": name or f"POS simulator {username}"},
+ expect=(200, 204, 409))
+ account = BankAccount(username=username, password=password, bank=bank)
+ try:
+ account.balance()
+ except WalletError as e:
+ if "401" not in str(e):
+ raise
+ raise WalletError(
+ f"the bank account {username!r} exists but this password does not "
+ f"open it -- pick another name, or pass the right password"
+ ) from e
+ return account
+
+
+class Wallet:
+ """One `taler-wallet-cli` database, used as the customer's wallet.
+
+ Every call shells out. That is deliberate: the wallet under test is the
+ terminal, and keeping the customer in a separate process means nothing the
+ harness does to it can be mistaken for the terminal's own behaviour.
+ """
+
+ def __init__(self, db: str | Path, cli: str = WALLET_CLI,
+ exchange: str = EXCHANGE):
+ self.db = Path(db)
+ self.cli = cli
+ self.exchange = exchange
+ self.db.parent.mkdir(parents=True, exist_ok=True)
+
+ # -- plumbing ---------------------------------------------------------
+
+ def run(self, *args: str, timeout: int = 300,
+ check: bool = True) -> subprocess.CompletedProcess:
+ # A ".json" database path makes the CLI pick its memory backend, which
+ # then refuses every command with "memory backend not supported"; the
+ # suffix is load-bearing, so it is asserted rather than hoped for.
+ if self.db.suffix != ".sqlite3":
+ raise WalletError(f"wallet db must end in .sqlite3, got {self.db}")
+ cmd = [self.cli, f"--wallet-db={self.db}", "--non-interactive", *args]
+ proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+ if check and proc.returncode != 0:
+ raise WalletError(
+ f"{' '.join(args)} failed ({proc.returncode}): "
+ f"{(proc.stderr or proc.stdout)[-800:]}")
+ return proc
+
+ def reset(self) -> None:
+ """Start from an empty wallet."""
+ for suffix in ("", "-journal", "-wal", "-shm"):
+ p = Path(str(self.db) + suffix)
+ if p.exists():
+ p.unlink()
+
+ # -- getting money ----------------------------------------------------
+
+ def trust_exchange(self) -> None:
+ self.run("exchanges", "add", self.exchange, check=False)
+ self.run("exchanges", "accept-tos", self.exchange, check=False)
+
+ def withdraw(self, account: BankAccount, amount: str,
+ timeout: int = 420) -> None:
+ """Withdraw into this wallet, start to finish.
+
+ Three parties have to agree and the order matters. The bank creates
+ the operation; the wallet picks it up, chooses an exchange and
+ registers a reserve with the bank; only then can the account holder
+ approve it.
+
+ The middle step is the one that bites. `taler-wallet-cli withdraw`
+ returns as soon as the transaction exists, leaving it in
+ `pending:bank-register-reserve` -- and the wallet only makes progress
+ while one of its processes is running, so nothing advances it after
+ that command exits. Approving at that point gets "cannot confirm an
+ unselected withdrawal" forever. So the wallet is run again, waiting
+ for the state that means "your turn", and the approval goes after
+ that.
+ """
+ self.trust_exchange()
+ wid, uri = account.start_withdrawal(amount)
+ self.run("withdraw", f"--uri={uri}", timeout=timeout)
+ if not self.wait_last(state="pending:bank-confirm-transfer",
+ timeout=min(timeout, 180)):
+ raise WalletError(
+ f"the wallet never got as far as asking for the withdrawal to "
+ f"be approved; it is in {self.state_of_last()!r}")
+ account.confirm_withdrawal(wid)
+ if not self.wait_last(timeout=timeout):
+ raise WalletError(
+ f"the withdrawal did not finish within {timeout}s; it is in "
+ f"{self.state_of_last()!r}")
+
+ def state_of_last(self) -> str:
+ """The newest transaction's state, for an error message worth reading."""
+ out = self.run("transactions", "--oneline", "--pretty",
+ timeout=120, check=False).stdout
+ line = out.strip().splitlines()[0] if out.strip() else ""
+ import re
+ m = re.search(r"\[([^\]]+)\]", line)
+ return m.group(1) if m else (line[:120] or "unknown")
+
+ def balance(self) -> dict:
+ out = self.run("balance", timeout=120).stdout
+ try:
+ return json.loads(out)
+ except json.JSONDecodeError:
+ return {}
+
+ def available(self, currency: str) -> str:
+ for scope in self.balance().get("balances", []):
+ if scope.get("available", "").startswith(f"{currency}:"):
+ return scope["available"]
+ return f"{currency}:0"
+
+ def has_at_least(self, amount: str) -> bool:
+ """Whether the wallet can pay `amount`, comparing in minor units."""
+ currency, value = amount.split(":", 1)
+ return _as_fraction(self.available(currency).split(":", 1)[1]) >= \
+ _as_fraction(value)
+
+ # -- being a customer -------------------------------------------------
+
+ def pay(self, pay_uri: str, timeout: int = 300) -> None:
+ """Scan the terminal's code and go through with the payment."""
+ self.run("handle-uri", pay_uri, "--yes", timeout=timeout)
+
+ def claim_only(self, pay_uri: str) -> None:
+ """Look at the contract and stop there.
+
+ This is the state the terminal calls "claimed": the order is spoken for,
+ so it can no longer be deleted the ordinary way, and the payment screen
+ switches from "scan this" to "waiting for the customer to confirm".
+ `--inhibit` stops the wallet after it has the contract, which is
+ exactly where a hesitating customer stops.
+ """
+ proc = subprocess.run(
+ [self.cli, f"--wallet-db={self.db}", "--non-interactive",
+ "--inhibit=pay", "handle-uri", pay_uri],
+ capture_output=True, text=True, timeout=180)
+ if proc.returncode != 0 and "inhibit" not in (proc.stderr or ""):
+ # Not fatal: the point is the order's state at the backend, which
+ # the caller checks. But a wallet that refused outright did not
+ # claim anything, and the scenario should say so rather than wait.
+ raise WalletError(
+ f"claim-only did not get as far as the contract: "
+ f"{(proc.stderr or proc.stdout)[-600:]}")
+
+ def accept_refund(self, refund_uri: str, timeout: int = 300) -> None:
+ """Take the refund the terminal is offering."""
+ self.run("handle-uri", refund_uri, "--yes", timeout=timeout)
+
+ def abort_last(self) -> None:
+ self.run("transactions", "abort", "^", check=False)
+
+ def wait_last(self, state: str = "final", timeout: int = 300) -> bool:
+ """Block until the newest transaction settles; False on timeout."""
+ proc = self.run("wait-tx", "^", "-s", state, timeout=timeout, check=False)
+ return proc.returncode == 0
+
+ def transactions(self) -> list[dict]:
+ out = self.run("transactions", "--json", timeout=120, check=False).stdout
+ try:
+ return json.loads(out).get("transactions", [])
+ except (json.JSONDecodeError, AttributeError):
+ return []
+
+
+def _as_fraction(value: str) -> int:
+ """A Taler amount's value as an integer number of 1e-8 units."""
+ whole, _, frac = value.partition(".")
+ frac = (frac + "00000000")[:8]
+ return int(whole or 0) * 100_000_000 + int(frac)
+
+
+def customer(name: str = "possim", password: Optional[str] = None,
+ db_dir: str = "/opt/taler-pos-sim/run/wallets") -> tuple[Wallet, BankAccount]:
+ """A funded-on-demand customer: a bank account and a wallet of its own.
+
+ The bank password is derived from the name so that a re-run adopts the same
+ account rather than failing to register a new one, and so that the
+ credential is not a secret worth protecting -- this is a demo bank holding
+ play money.
+ """
+ password = password or f"{name}-pos-simulator"
+ account = register_account(name, password)
+ wallet = Wallet(Path(db_dir) / f"{name}.sqlite3")
+ return wallet, account
+
+
+if __name__ == "__main__":
+ import sys
+ cmd = sys.argv[1] if len(sys.argv) > 1 else "info"
+ w, acct = customer(db_dir=os.environ.get("POS_WALLET_DIR", "/tmp/pos-sim-wallets"))
+ if cmd == "fund":
+ amount = sys.argv[2] if len(sys.argv) > 2 else "KUDOS:20"
+ print(f"bank balance before: {acct.balance()}")
+ w.withdraw(acct, amount)
+ print(f"wallet now holds {w.available(amount.split(':')[0])}")
+ elif cmd == "pay":
+ w.pay(sys.argv[2])
+ print("paid")
+ else:
+ print(f"cli {w.cli}")
+ print(f"db {w.db}")
+ print(f"bank {acct.username} at {acct.bank}, balance {acct.balance()}")
+ print(f"wallet {w.balance().get('balances', [])}")
diff --git a/pos-simulator/driver/coverage.py b/pos-simulator/driver/coverage.py
@@ -0,0 +1,79 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Pull JaCoCo execution data out of a running terminal.
+
+The simulator drives the app from outside, so AGP's own instrumented-test
+coverage plumbing never runs. Instead the "sim" build type carries the JaCoCo
+agent plus the PosSimHooks receiver, and this module asks the agent for what it
+has collected so far. Data accumulates in the live process, so dumping is
+cheap and can be done between episodes; the file only has to be collected
+before the process dies.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from device import ADB, HOOKS, PKG, Device
+
+ACTION = f"{PKG}.sim.DUMP_COVERAGE"
+
+# Every jacoco .exec stream starts with a block header and this magic.
+MAGIC = b"\x01\xc0\xc0"
+
+
+def dump(dev: Device, out_path: str | Path, name: str = "coverage.ec") -> Path:
+ """Dump coverage from the app and copy it off the device.
+
+ Raises if the agent is missing, which means the APK under test was not
+ built from the "sim" build type.
+ """
+ out = Path(out_path)
+ out.parent.mkdir(parents=True, exist_ok=True)
+ res = dev.shell(f"am broadcast -a {ACTION} -n {HOOKS} --es file {name}")
+ if "Broadcast completed" not in res:
+ raise RuntimeError(f"coverage broadcast not delivered: {res.strip()}")
+ # run-as is the only way into the app's private files; the sim build is
+ # debuggable, so it is allowed.
+ data = subprocess.run(
+ [ADB, "-s", dev.serial, "exec-out", "run-as", PKG, "cat", f"files/{name}"],
+ capture_output=True, timeout=120,
+ )
+ if not data.stdout:
+ raise RuntimeError(
+ f"no coverage data (stderr: {data.stderr.decode(errors='replace').strip()}); "
+ "is this the sim APK?")
+ # A dump whose process was killed while writing leaves a truncated file,
+ # and jacoco's `merge` aborts on the first one it cannot read -- losing
+ # every other file's data with it. So a dump that does not at least begin
+ # like execution data never gets the final name.
+ if not data.stdout.startswith(MAGIC):
+ raise RuntimeError(
+ f"coverage data for {name} is not jacoco execution data "
+ f"({len(data.stdout)} bytes, starts {data.stdout[:8]!r}); "
+ "the app was probably killed mid-dump")
+ part = out.with_suffix(out.suffix + ".part")
+ part.write_bytes(data.stdout)
+ part.replace(out)
+ return out
+
+
+if __name__ == "__main__":
+ import sys
+ d = Device(sys.argv[2] if len(sys.argv) > 2 else None)
+ target = sys.argv[1] if len(sys.argv) > 1 \
+ else "/opt/taler-pos-sim/run/coverage/manual.ec"
+ p = dump(d, target)
+ print(f"{p} ({p.stat().st_size} bytes)")
diff --git a/pos-simulator/driver/device.py b/pos-simulator/driver/device.py
@@ -0,0 +1,842 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Thin adb wrapper: one emulator, seen through the accessibility tree.
+
+The terminal is Fragments and XML views with a Compose navigation shell on top,
+and carries no testTags anywhere, so widgets are addressed through the
+semantics the app already exposes -- text, content-description and bounds.
+Everything here is black-box; the only app-specific knowledge is the package
+name and the one activity.
+
+Two things differ from the wallet's equivalent and matter everywhere:
+
+* **The terminal is no longer landscape-locked.** It declared
+ `screenOrientation="landscape"` through round three and declares `fullUser`
+ on master, so the window follows `user_rotation` and portrait is a live set
+ of layouts. `wm size` still reports the panel and does not move when the
+ device turns. Sizes therefore come from the view hierarchy's own root
+ bounds, and only fall back to `wm size`.
+* **A setup URI is a VIEW deep link**, not an ACTION_SEND. The manifest's
+ VIEW filter covers the `taler-pos` scheme, which is the only scheme the
+ terminal accepts, so the ordinary deep-link path is also the real one.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import subprocess
+import time
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from typing import Optional
+
+ADB = os.environ.get("POS_ADB", "/opt/android-sdk/platform-tools/adb")
+
+# The emulator console port a worker gets. Deliberately *not* 5554: the wallet
+# simulator numbers its workers from there, and on a host running both, the
+# second harness to start does not boot anything -- the ports are taken -- it
+# silently attaches to the other one's emulators and drives the wrong app.
+# Neither side notices, because adb reports a device either way.
+PORT_BASE = int(os.environ.get("POS_PORT_BASE", "5584"))
+PKG = os.environ.get("POS_PKG", "net.taler.merchantpos")
+ACTIVITY = f"{PKG}/{PKG}.MainActivity"
+HOOKS = f"{PKG}/{PKG}.sim.PosSimHooks"
+
+BOUNDS_RE = re.compile(r"\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]")
+
+
+def serial_for(worker: int | str | None = None) -> str:
+ """The adb serial for a worker index.
+
+ `POS_SERIAL` overrides it outright, for attaching to an emulator somebody
+ else started.
+ """
+ if os.environ.get("POS_SERIAL"):
+ return os.environ["POS_SERIAL"]
+ if worker is None:
+ worker = os.environ.get("POS_WORKER", "0")
+ return f"emulator-{PORT_BASE + 2 * int(worker)}"
+
+
+@dataclass(frozen=True)
+class Node:
+ """One node of the accessibility tree, flattened."""
+
+ cls: str
+ text: str
+ desc: str
+ rid: str
+ clickable: bool
+ scrollable: bool
+ editable: bool
+ checkable: bool
+ checked: bool
+ enabled: bool
+ selected: bool
+ bounds: tuple[int, int, int, int]
+
+ @property
+ def center(self) -> tuple[int, int]:
+ x1, y1, x2, y2 = self.bounds
+ return (x1 + x2) // 2, (y1 + y2) // 2
+
+ @property
+ def label(self) -> str:
+ return self.text or self.desc
+
+ @property
+ def area(self) -> int:
+ x1, y1, x2, y2 = self.bounds
+ return max(0, x2 - x1) * max(0, y2 - y1)
+
+ def __str__(self) -> str:
+ kind = self.cls.rsplit(".", 1)[-1]
+ flags = "".join(
+ f for f, on in (("C", self.clickable), ("S", self.scrollable),
+ ("E", self.editable), ("v", self.checked),
+ ("x", not self.enabled))
+ if on
+ )
+ rid = self.rid.rsplit("/", 1)[-1]
+ return (f"{kind}{'[' + flags + ']' if flags else ''} "
+ f"{self.label!r}{'#' + rid if rid else ''} @{self.center}")
+
+
+@dataclass
+class Screen:
+ """A parsed UI dump plus the cheap derived views the driver needs."""
+
+ nodes: list[Node] = field(default_factory=list)
+ activity: str = ""
+
+ def labelled(self) -> list[Node]:
+ return [n for n in self.nodes if n.label.strip()]
+
+ def tappable(self) -> list[Node]:
+ """Clickable nodes, plus labelled leaves.
+
+ The terminal's two keypads (amount entry and the order grid) build each
+ key as a Button whose label is a child TextView, and the product cards
+ in the order grid mark only the card clickable -- so both the
+ containers and the labels have to count as tap targets for novelty
+ tracking to mean anything.
+ """
+ out = [n for n in self.nodes if n.clickable and n.enabled and n.area > 0]
+ seen = {n.bounds for n in out}
+ for n in self.labelled():
+ if n.bounds not in seen and n.area > 0:
+ out.append(n)
+ seen.add(n.bounds)
+ return out
+
+ def editable(self) -> list[Node]:
+ return [n for n in self.nodes if n.editable and n.enabled]
+
+ def texts(self) -> list[str]:
+ return [n.label.strip() for n in self.labelled()]
+
+ def root_bounds(self) -> Optional[tuple[int, int, int, int]]:
+ """The largest node's box, which is the window the app is drawing in."""
+ if not self.nodes:
+ return None
+ return max(self.nodes, key=lambda n: n.area).bounds
+
+ def tap_target(self, node: Node) -> Node:
+ """The node that actually reacts when the user aims at `node`.
+
+ Three shapes occur in this app: the labelled node is itself clickable
+ (most of Compose); the label sits inside a clickable ancestor (the
+ product cards, the drawer rows); or the label is a separate TextView
+ next to an unlabelled clickable, which is how the amount keypad and the
+ history row actions are built. The last case needs a neighbour search,
+ not a containment search, or the tap lands on nothing at all.
+ """
+ if node.clickable:
+ return node
+ cx, cy = node.center
+ # Containment is checked against *every* clickable, enabled or not.
+ # A disabled Compose Button is still a clickable node, and skipping it
+ # sent the search off to the nearest enabled neighbour -- which for
+ # the amount keypad's Charge button is a digit key three rows up. The
+ # caller then read that key's "enabled" and concluded that charging
+ # nothing was allowed, which is the opposite of what the screen does.
+ clickables = [n for n in self.nodes if n.clickable and n.area > 0]
+ containing = [n for n in clickables
+ if n.bounds[0] <= cx <= n.bounds[2]
+ and n.bounds[1] <= cy <= n.bounds[3]]
+ if containing:
+ return min(containing, key=lambda n: n.area)
+ clickables = [n for n in clickables if n.enabled]
+ x1, y1, x2, y2 = node.bounds
+
+ def neighbour_distance(n: Node) -> Optional[int]:
+ if n.bounds[2] < x1 or n.bounds[0] > x2:
+ return None
+ if n.bounds[3] <= y1:
+ return y1 - n.bounds[3]
+ if n.bounds[1] >= y2:
+ return n.bounds[1] - y2
+ return 0
+
+ scored = [(d, n) for n in clickables
+ if (d := neighbour_distance(n)) is not None and d <= 120]
+ if scored:
+ return min(scored, key=lambda row: row[0])[1]
+ return node
+
+ def unnamed_clickables(self) -> list[Node]:
+ """Clickable nodes a screen reader cannot announce.
+
+ A clickable with no text of its own is fine when the label sits
+ *inside* it: the semantics merge and TalkBack reads the child. What is
+ not fine is a label that is only a neighbour, or no label at all --
+ which is what an icon button without a contentDescription looks like.
+ """
+ labelled = [n for n in self.nodes if n.label.strip() and n.area > 0]
+ out = []
+ for node in self.nodes:
+ if not (node.clickable and node.enabled and node.area > 0):
+ continue
+ if node.label.strip():
+ continue
+ x1, y1, x2, y2 = node.bounds
+ if (x2 - x1) >= 900 and (y2 - y1) >= 600:
+ continue # a full-screen container, not a control
+ contains_label = any(
+ x1 <= n.bounds[0] and y1 <= n.bounds[1]
+ and n.bounds[2] <= x2 and n.bounds[3] <= y2
+ for n in labelled
+ )
+ if not contains_label:
+ out.append(node)
+ return out
+
+ def find(self, pattern: str) -> Optional[Node]:
+ rx = re.compile(pattern, re.I)
+ for n in self.nodes:
+ if n.label and rx.search(n.label):
+ return n
+ return None
+
+ def find_all(self, pattern: str) -> list[Node]:
+ rx = re.compile(pattern, re.I)
+ return [n for n in self.nodes if n.label and rx.search(n.label)]
+
+ def has(self, pattern: str) -> bool:
+ return self.find(pattern) is not None
+
+ def signature(self) -> str:
+ """Stable-ish identity of a screen, for novelty tracking and oracles.
+
+ Only the set of labels and the shape of the interactive nodes go in, so
+ the same screen with a different order total still matches itself.
+ """
+ labels = sorted({re.sub(r"\d+[.,]?\d*", "#", t) for t in self.texts()})
+ shape = f"{len(self.tappable())}/{len(self.editable())}"
+ return f"{self.activity}|{shape}|{'|'.join(labels)}"
+
+ def __str__(self) -> str:
+ return "\n".join(str(n) for n in self.labelled())
+
+
+class Device:
+ def __init__(self, serial: Optional[str] = None, pkg: str = PKG):
+ serial = serial or serial_for()
+ self.serial = serial
+ self.pkg = pkg
+ self._sdk_int: Optional[int] = None
+ self._size: Optional[tuple[int, int]] = None
+ self._display: Optional[tuple[int, int]] = None
+ # Where the soft keyboard starts, learned rather than asked for: the
+ # IME is not in the accessibility dump and its window frame is the
+ # whole screen, so neither can be read directly. What can be read is
+ # the app's own window, which shrinks to the keyboard's top edge -- so
+ # the first dump taken over a resized window records it, and dialogs,
+ # whose dump covers only the dialog, use the figure from then on.
+ self._ime_top: Optional[int] = None
+ self._swdp: Optional[int] = None
+
+ # -- plumbing ---------------------------------------------------------
+
+ def adb(self, *args: str, timeout: int = 60, check: bool = True) -> str:
+ proc = subprocess.run(
+ [ADB, "-s", self.serial, *args],
+ capture_output=True, text=True, timeout=timeout,
+ )
+ if check and proc.returncode != 0:
+ raise RuntimeError(f"adb {' '.join(args)} failed: {proc.stderr.strip()}")
+ return proc.stdout
+
+ def shell(self, cmd: str, timeout: int = 60, check: bool = True) -> str:
+ return self.adb("shell", cmd, timeout=timeout, check=check)
+
+ # -- observation ------------------------------------------------------
+
+ @property
+ def sdk_int(self) -> int:
+ if self._sdk_int is None:
+ out = self.shell("getprop ro.build.version.sdk", check=False)
+ try:
+ self._sdk_int = int(out.strip() or 0)
+ except ValueError:
+ self._sdk_int = 0
+ return self._sdk_int
+
+ def current_activity(self) -> str:
+ out = self.shell("dumpsys activity activities | grep -m1 ResumedActivity", check=False)
+ m = re.search(r"([A-Za-z0-9_.]+/[A-Za-z0-9_.]+)", out)
+ return m.group(1) if m else ""
+
+ def dump(self, retries: int = 3) -> Screen:
+ """Read the accessibility tree.
+
+ uiautomator fails while the UI is still settling ("could not get idle
+ state"), which is routine right after a tap, so this retries. The
+ terminal makes it worse than the wallet does: the order grid animates
+ its stock badges and the payment screen re-renders a QR code every
+ second, so a dump during a payment check can need all three attempts.
+ """
+ xml = ""
+ for attempt in range(retries):
+ out = self.shell("uiautomator dump /sdcard/ui.xml", check=False)
+ if "dumped" in out.lower():
+ xml = self.adb("exec-out", "cat", "/sdcard/ui.xml", check=False)
+ if xml.lstrip().startswith("<?xml"):
+ break
+ time.sleep(1 + attempt)
+ if not xml.lstrip().startswith("<?xml"):
+ return Screen(activity=self.current_activity())
+ screen = self._parse(xml)
+ # The window the app draws in is the authority on size, not wm size:
+ # a landscape-locked activity on a portrait device makes the two
+ # disagree, and every swipe computed from the wrong one misses.
+ box = screen.root_bounds()
+ if box:
+ self._size = (box[2] - box[0], box[3] - box[1])
+ full_h = self.display_size()[1]
+ if 0 < box[3] < full_h * 0.95 and box[1] == 0:
+ self._ime_top = box[3]
+ return screen
+
+ def _parse(self, xml: str) -> Screen:
+ screen = Screen(activity=self.current_activity())
+ try:
+ root = ET.fromstring(xml)
+ except ET.ParseError:
+ return screen
+ for el in root.iter("node"):
+ m = BOUNDS_RE.match(el.get("bounds", ""))
+ if not m:
+ continue
+ cls = el.get("class", "")
+ screen.nodes.append(Node(
+ cls=cls,
+ text=el.get("text", ""),
+ desc=el.get("content-desc", ""),
+ rid=el.get("resource-id", ""),
+ clickable=el.get("clickable") == "true",
+ scrollable=el.get("scrollable") == "true",
+ editable=cls.endswith("EditText"),
+ checkable=el.get("checkable") == "true",
+ checked=el.get("checked") == "true",
+ enabled=el.get("enabled") == "true",
+ selected=el.get("selected") == "true",
+ bounds=tuple(int(v) for v in m.groups()), # type: ignore[arg-type]
+ ))
+ return screen
+
+ def screenshot(self, path: str) -> None:
+ png = subprocess.run([ADB, "-s", self.serial, "exec-out", "screencap", "-p"],
+ capture_output=True, timeout=60).stdout
+ with open(path, "wb") as f:
+ f.write(png)
+
+ def logcat(self, clear: bool = False, lines: Optional[int] = None) -> str:
+ """Read the log, or clear it.
+
+ `lines` bounds the read to the most recent entries. Reading the whole
+ buffer costs seconds once it has filled, which is far too slow to do
+ after every action.
+ """
+ if clear:
+ self.adb("logcat", "-c", check=False)
+ return ""
+ args = ["logcat", "-d"]
+ if lines:
+ args += ["-t", str(lines)]
+ return self.adb(*args, timeout=120, check=False)
+
+ def _physical(self) -> tuple[int, int]:
+ """What `wm size` reports: the panel, in its natural orientation."""
+ out = self.shell("wm size")
+ m = re.search(r"Override size: (\d+)x(\d+)", out) or \
+ re.search(r"Physical size: (\d+)x(\d+)", out)
+ return (int(m.group(1)), int(m.group(2))) if m else (1080, 2400)
+
+ def rotation(self) -> int:
+ """The device's rotation, 0-3, as the system has it."""
+ out = self.shell("settings get system user_rotation", check=False) or ""
+ try:
+ return int(out.strip()) % 4
+ except ValueError:
+ return 0
+
+ def is_portrait(self) -> bool:
+ """Whether the app's window is currently taller than it is wide.
+
+ Derived rather than assumed. `wm size` does not move when the device
+ turns -- it reports the panel -- so the orientation is the natural one
+ rotated by `user_rotation`, and which *value* means portrait depends
+ on the panel: every AVD this harness creates is landscape-natural
+ (`emu.sh` writes the LCD geometry), a stock phone AVD is not.
+ """
+ w, h = self._physical()
+ natural_portrait = h > w
+ quarter_turned = self.rotation() % 2 == 1
+ return natural_portrait != quarter_turned
+
+ def rotate(self, portrait: bool, timeout: float = 25.0) -> tuple[int, int]:
+ """Turn the device and wait for the app's window to follow.
+
+ The terminal used to be locked to landscape and is not any more --
+ `android:screenOrientation` is `fullUser` on master -- so portrait is
+ a live set of layouts rather than dead code. Auto-rotation is pinned
+ off and `user_rotation` is written directly, because an emulator has
+ no accelerometer to tilt.
+
+ Which value means portrait depends on the panel's natural
+ orientation, so both are *tried* rather than worked out: a value
+ computed from `wm size` was right in principle and wrong in practice
+ often enough to turn a rotation failure into a harness error for
+ every scenario that followed. The window is the only authority, and
+ it is asked.
+
+ Returns the window size afterwards, or raises if neither value turned
+ it: a caller that thinks it is testing portrait and is not would
+ report every landscape layout under a portrait name.
+ """
+ self.shell("settings put system accelerometer_rotation 0", check=False)
+ w, h = self._physical()
+ natural_portrait = h > w
+ first = 0 if (natural_portrait == portrait) else 1
+ # Each value gets its own budget. Giving up on one after a single
+ # dump was wrong twice over: the first dump after a write is often
+ # taken before the window manager has resized anything, so a correct
+ # value looked wrong, and the "other" value was then written on top of
+ # it -- turning the device away from what was asked for.
+ per_value = max(6.0, timeout / 2)
+ for value in (first, 1 - first):
+ self.shell(f"settings put system user_rotation {value}",
+ check=False)
+ deadline = time.monotonic() + per_value
+ while time.monotonic() < deadline:
+ time.sleep(1.0)
+ self._size = self._display = None
+ try:
+ box = self.dump().root_bounds()
+ except Exception:
+ continue # a dump during a rotation can come back torn
+ if box is None:
+ continue
+ width, height = box[2] - box[0], box[3] - box[1]
+ if (height > width) == portrait:
+ self._size = (width, height)
+ return self._size
+ self._size = self._display = None
+ raise RuntimeError(
+ f"the window did not turn to {'portrait' if portrait else 'landscape'} "
+ f"within {timeout}s (user_rotation={self.rotation()}, "
+ f"physical={w}x{h})")
+
+ def size(self) -> tuple[int, int]:
+ """The app window's size in pixels.
+
+ A dump fills this in; without one, fall back to the panel's size
+ turned to match the current rotation. It used to be forced landscape
+ unconditionally, which was right while the terminal was locked to
+ landscape and wrong the moment it stopped being.
+ """
+ if self._size is None:
+ w, h = self._physical()
+ if (h > w) != self.is_portrait():
+ w, h = h, w
+ self._size = (w, h)
+ return self._size
+
+ def smallest_width_dp(self) -> int:
+ """The `smallestScreenWidthDp` five of the terminal's screens branch on.
+
+ Read from the device rather than guessed from the AVD profile: the
+ profile does not decide it, the LCD geometry written into the AVD
+ does, and a harness that assumed "tablet" ran half the layouts it
+ thought it was covering.
+ """
+ if self._swdp is None:
+ width, height = self.display_size()
+ density = 160
+ out = self.shell("wm density", check=False) or ""
+ m = re.search(r"(?:Override|Physical) density:\s*(\d+)", out)
+ if m:
+ density = int(m.group(1))
+ self._swdp = int(min(width, height) * 160 / max(density, 1))
+ return self._swdp
+
+ def is_phone_layout(self) -> bool:
+ """True where the terminal picks its phone layouts."""
+ return self.smallest_width_dp() < 720
+
+ def display_size(self) -> tuple[int, int]:
+ """The physical display, turned to match the current rotation.
+
+ `size()` answers with the app's window, which the keyboard shrinks and
+ a dialog replaces entirely; this one only moves when the device does.
+ """
+ if self._display is None:
+ w, h = self._physical()
+ if (h > w) != self.is_portrait():
+ w, h = h, w
+ self._display = (w, h)
+ return self._display
+
+ IME_INSET = re.compile(
+ r"InsetsSource[^\n]*type=ime[^\n]*frame=\[(\d+),(\d+)\]\[(\d+),(\d+)\]"
+ r"[^\n]*visible=true")
+
+ def ime_top(self) -> Optional[int]:
+ """The y where the soft keyboard starts, or None if it is not up.
+
+ The window manager publishes it as an inset, which is the only exact
+ source: the keyboard is not in the accessibility dump and its own
+ window frame covers the whole screen. A dump taken over a window the
+ keyboard resized gives the same number and is kept as a fallback,
+ because an app whose screens do not resize under the IME -- this one's
+ login form does not -- never produces one.
+ """
+ if not self.keyboard_shown():
+ return None
+ out = self.shell("dumpsys window displays", check=False)
+ m = self.IME_INSET.search(out or "")
+ if m:
+ self._ime_top = int(m.group(2))
+ return self._ime_top
+
+ # -- acting -----------------------------------------------------------
+
+ def tap(self, x: int, y: int) -> None:
+ self.shell(f"input tap {x} {y}")
+
+ def tap_node(self, node: Node, screen: Optional[Screen] = None) -> None:
+ target = screen.tap_target(node) if screen is not None else node
+ x, y = target.center
+ self.tap(x, y)
+
+ def long_press(self, node: Node, ms: int = 800) -> None:
+ """Hold a finger on a node long enough for a long-press gesture.
+
+ A zero-distance `input swipe` is what works: a press that never moved.
+ Moving even two pixels turns it into a drag and cancels the long press.
+ """
+ x, y = node.center
+ self.shell(f"input swipe {x} {y} {x} {y} {ms}")
+
+ def type_text(self, s: str) -> None:
+ """Type into the focused field.
+
+ "input text" maps each character through a KeyCharacterMap and throws
+ NullPointerException on anything it cannot map, so non-ASCII goes
+ through the clipboard instead (which needs the sim build's hooks).
+ """
+ if not s:
+ return
+ if not s.isascii() or len(s) > 200:
+ self.paste_text(s)
+ return
+ for chunk in re.split(r"( )", s):
+ if not chunk:
+ continue
+ if chunk == " ":
+ self.shell("input keyevent 62")
+ else:
+ self.shell(f"input text {shlex.quote(chunk)}", check=False)
+
+ def paste_text(self, s: str) -> None:
+ """Put text on the clipboard through the sim hooks, then paste it."""
+ res = self.shell(
+ f"am broadcast -a {self.pkg}.sim.SET_CLIPBOARD "
+ f"-n {HOOKS} --es text {shlex.quote(s)}",
+ check=False,
+ )
+ if "Broadcast completed" not in res:
+ raise RuntimeError(
+ f"clipboard hook unavailable (is this the sim APK?): {res.strip()[:200]}"
+ )
+ self.shell("input keyevent KEYCODE_PASTE")
+
+ def clear_field(self, node: Node, screen: Optional[Screen] = None,
+ width: int = 48) -> None:
+ """Empty a text field by selecting all of it and deleting.
+
+ `KEYCODE_DEL` alone needs as many events as the field has characters,
+ and the merchant URL field comes prefilled with a host name -- so the
+ select-all shortcut does it in two events instead of forty.
+ """
+ self.tap_node(node, screen)
+ time.sleep(0.3)
+ self.shell("input keyevent KEYCODE_MOVE_END")
+ self.shell(f"input keyevent --longpress {' '.join(['KEYCODE_DEL'] * width)}",
+ check=False)
+
+ def key(self, keycode: str) -> None:
+ self.shell(f"input keyevent {keycode}")
+
+ def keyboard_shown(self) -> bool:
+ """Whether the soft keyboard is up.
+
+ This matters more than it sounds. The IME is its own window, and the
+ terminal's login form does not resize under it -- so the hierarchy
+ still reports the Connect button at its layout position while the
+ keyboard is drawn on top of it, and a tap aimed there lands on a key.
+ Nothing is logged, nothing changes on screen, and the scenario waits
+ out its timeout concluding that the button does nothing.
+ """
+ out = self.shell("dumpsys input_method | grep -m1 mInputShown", check=False)
+ return "mInputShown=true" in out
+
+ def hide_keyboard(self, timeout: float = 6.0) -> bool:
+ """Put the soft keyboard away, and say whether it went.
+
+ BACK is what does it: the IME consumes the first BACK to dismiss
+ itself, so this cannot navigate away by accident *while the keyboard
+ is up* -- which is why the state is checked first and after rather
+ than pressing hopefully. ESCAPE looks like the tidier choice and does
+ nothing at all on a soft keyboard.
+ """
+ if not self.keyboard_shown():
+ return True
+ deadline = time.monotonic() + timeout
+ while time.monotonic() < deadline:
+ self.key("KEYCODE_BACK")
+ time.sleep(0.8)
+ if not self.keyboard_shown():
+ return True
+ return False
+
+ def back(self) -> None:
+ self.key("KEYCODE_BACK")
+
+ def scroll(self, down: bool = True, screen: Optional[Screen] = None,
+ node: Optional[Node] = None) -> None:
+ """Swipe inside the scrollable area of the current screen.
+
+ Fixed coordinates break as soon as the layout changes, so the gesture
+ is derived from a scrollable node when there is one and from the window
+ otherwise. `node` pins it to one of several scrollables, which the
+ order screen needs: its category list and its product grid scroll
+ independently and the grid is not always the larger of the two.
+ """
+ width, height = self.size()
+ area = None
+ if node is not None:
+ area = node.bounds
+ elif screen is not None:
+ scrollables = [n for n in screen.nodes if n.scrollable and n.area > 0]
+ if scrollables:
+ area = max(scrollables, key=lambda n: n.area).bounds
+ if area is None:
+ area = (0, height // 8, width, height - height // 8)
+ x1, y1, x2, y2 = area
+ x = (x1 + x2) // 2
+ near, far = y1 + (y2 - y1) // 6, y2 - (y2 - y1) // 6
+ start, end = (far, near) if down else (near, far)
+ # 800 ms makes this a drag rather than a fling: a fling carries on
+ # under its own momentum and can scroll a whole row past the next dump.
+ self.shell(f"input swipe {x} {start} {x} {end} 800")
+
+ def swipe_from_left_edge(self) -> None:
+ """Open the navigation drawer with the edge gesture.
+
+ The hamburger button is the ordinary way in and is what scenarios use;
+ this exists because the drawer is also reachable by gesture, and
+ `gesturesEnabled` is switched off while the terminal has no valid
+ config -- which is a thing worth testing rather than assuming.
+ """
+ width, height = self.size()
+ y = height // 2
+ self.shell(f"input swipe 2 {y} {width // 2} {y} 400")
+
+ # -- app lifecycle and entry points -----------------------------------
+
+ def launch(self, timeout: int = 90) -> None:
+ """Bring the terminal to the front.
+
+ `am start -W` waits for the activity to be drawn, which is what makes
+ the next dump meaningful -- and which hangs for the full timeout when
+ the launch is blocked by a system dialog ("Taler POS keeps stopping")
+ or when the activity dies while starting. A `subprocess.TimeoutExpired`
+ there aborts the whole scenario with a traceback about adb, so it is
+ caught and retried without the wait; a scenario that then finds no app
+ reports that instead, which is a far more useful failure.
+ """
+ try:
+ self.shell(f"am start -W -n {ACTIVITY}", timeout=timeout, check=False)
+ return
+ except subprocess.TimeoutExpired:
+ pass
+ self.shell(f"am start -n {ACTIVITY}", timeout=30, check=False)
+ time.sleep(3)
+
+ def stop(self) -> None:
+ self.shell(f"am force-stop {self.pkg}")
+
+ def kill(self) -> None:
+ """Process death without a clean shutdown, to test state restoration."""
+ self.shell(f"am kill {self.pkg}")
+
+ def clear_data(self) -> None:
+ self.shell(f"pm clear {self.pkg}")
+
+ def grant_camera(self) -> None:
+ """Re-grant the camera permission, which "pm clear" takes away."""
+ self.shell(f"pm grant {self.pkg} android.permission.CAMERA", check=False)
+
+ def revoke_camera(self) -> None:
+ self.shell(f"pm revoke {self.pkg} android.permission.CAMERA", check=False)
+
+ def setup_uri(self, uri: str) -> None:
+ """Hand a `taler-pos://` setup URI to the terminal.
+
+ This is a plain VIEW deep link, which is both what the manifest filter
+ declares and what the QR scanner synthesises internally -- so the two
+ provisioning paths differ only in how the string is obtained.
+ """
+ self.shell(f"am start -a android.intent.action.VIEW -d {shlex.quote(uri)} "
+ f"-n {ACTIVITY}", timeout=120, check=False)
+
+ def _hook_report(self, action: str, marker: str,
+ timeout: float = 8.0) -> Optional[str]:
+ """Ask a reporting hook a question and read its answer out of the log.
+
+ A broadcast receiver cannot return a value, so the hooks that read
+ something out of the app process print it instead. The log is cleared
+ first so that an answer from an earlier call cannot be mistaken for
+ this one.
+ """
+ self.adb("logcat", "-c", "-b", "main", check=False)
+ res = self.shell(f"am broadcast -a {self.pkg}.sim.{action} -n {HOOKS}",
+ check=False)
+ if "Broadcast completed" not in res:
+ return None
+ deadline = time.monotonic() + timeout
+ pattern = re.compile(rf"{re.escape(marker)}\s*(.*)$")
+ while time.monotonic() < deadline:
+ for line in self.logcat(lines=500).splitlines():
+ m = pattern.search(line)
+ if m:
+ return m.group(1).strip()
+ time.sleep(0.5)
+ return None
+
+ def report_nfc_payload(self) -> Optional[str]:
+ """What the terminal is offering over host card emulation.
+
+ Returns the URI, the string "none" when the terminal published
+ nothing, or None when the hook did not answer at all. On an emulator
+ this is always "none": the NFC service refuses to publish anything on
+ a device with no NFC adapter, and no emulator image has one -- so this
+ is a check that the terminal is *not* publishing, not a way to read
+ the pay URI. `read_clipboard` is that.
+ """
+ return self._hook_report("REPORT_NFC_PAYLOAD", "nfc-payload:")
+
+ def read_clipboard(self) -> Optional[str]:
+ """What is on the clipboard, read from inside the app.
+
+ The clipboard may only be read by the foreground app, and the hook
+ runs in it -- so this is how a URI the terminal only draws as a QR
+ code becomes readable: tap the screen's copy button, then ask.
+ """
+ value = self._hook_report("REPORT_CLIPBOARD", "clipboard:")
+ return None if value in (None, "none") else value
+
+ def airplane_mode(self, on: bool) -> None:
+ self.shell(f"cmd connectivity airplane-mode {'enable' if on else 'disable'}",
+ check=False)
+
+ def set_app_locale(self, tag: str) -> None:
+ """Set the per-app language, as the terminal's own Settings screen does.
+
+ API 33 and later only; below that the app's language picker writes a
+ value the framework ignores, which is itself worth knowing but is not
+ what this is for.
+ """
+ if self.sdk_int < 33:
+ raise RuntimeError(f"per-app locales need API 33, device is {self.sdk_int}")
+ self.shell(f"cmd locale set-app-locales {self.pkg} --locales {tag}",
+ check=False)
+
+ # -- waiting and convenience ------------------------------------------
+
+ def wait_for(self, pattern: str, timeout: int = 60, poll: float = 1.5) -> Screen:
+ """Poll the UI until some label matches, and return that screen.
+
+ Raises TimeoutError with the last screen's labels attached, which is
+ what makes a failing scenario readable afterwards.
+ """
+ deadline = time.monotonic() + timeout
+ last = Screen()
+ while time.monotonic() < deadline:
+ last = self.dump()
+ if last.find(pattern):
+ return last
+ time.sleep(poll)
+ raise TimeoutError(
+ f"no label matching {pattern!r} within {timeout}s; "
+ f"screen showed: {last.texts()}"
+ )
+
+ def wait_gone(self, pattern: str, timeout: int = 60, poll: float = 1.5) -> Screen:
+ """Poll until no label matches any more."""
+ deadline = time.monotonic() + timeout
+ last = Screen()
+ while time.monotonic() < deadline:
+ last = self.dump()
+ if not last.find(pattern):
+ return last
+ time.sleep(poll)
+ raise TimeoutError(
+ f"{pattern!r} still on screen after {timeout}s: {last.texts()}")
+
+ def tap_text(self, pattern: str, timeout: int = 30) -> Screen:
+ """Wait for a label, tap what serves it, and return that screen."""
+ screen = self.wait_for(pattern, timeout=timeout)
+ node = screen.find(pattern)
+ if node is None:
+ raise RuntimeError(f"{pattern!r} matched but was gone before the tap; "
+ f"screen now: {self.dump().texts()}")
+ self.tap_node(node, screen)
+ return screen
+
+
+if __name__ == "__main__":
+ import sys
+ d = Device(sys.argv[1] if len(sys.argv) > 1 else None)
+ s = d.dump()
+ print(f"activity: {s.activity}")
+ print(f"window: {d.size()}")
+ print(f"nodes: {len(s.nodes)} labelled: {len(s.labelled())} "
+ f"tappable: {len(s.tappable())} editable: {len(s.editable())}")
+ print(s)
+ print("signature:", s.signature()[:300])
diff --git a/pos-simulator/driver/episode.py b/pos-simulator/driver/episode.py
@@ -0,0 +1,278 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""One run of the simulator: actions in, artifacts and findings out.
+
+Every action is recorded in a form that can be replayed, which is what makes a
+finding useful: the artifact directory holds the sequence that produced it, not
+just a stack trace. Actions are addressed by label wherever possible, because
+coordinates stop meaning anything as soon as a layout shifts -- and the
+terminal's layout shifts with the width of the screen, since it has a tablet
+and a phone variant of the config screen.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+import coverage as coverage_mod
+import oracles
+from device import Device, Screen
+from pos import Pos
+
+
+@dataclass
+class Action:
+ """A replayable step."""
+
+ op: str
+ arg: Any = None
+
+ def describe(self) -> str:
+ return f"{self.op}({self.arg!r})" if self.arg is not None else f"{self.op}()"
+
+
+class Episode:
+ def __init__(
+ self,
+ dev: Device,
+ out_dir: str | Path,
+ name: str = "episode",
+ settle: float = 1.2,
+ coverage_dir: str | Path | None = None,
+ ):
+ self.dev = dev
+ self.app = Pos(dev)
+ # Whatever has been exercised so far lives in the app process; a wipe
+ # takes it with it unless it is dumped first.
+ self.app.before_wipe = lambda: self.dump_coverage("before-wipe")
+ self.dir = Path(out_dir) / name
+ self.dir.mkdir(parents=True, exist_ok=True)
+ self.name = name
+ self.settle = settle
+ self.actions: list[Action] = []
+ self.session = oracles.Session()
+ self.signatures: set[str] = set()
+ self.steps = 0
+ self.notes: list[str] = []
+ self._shots = 0
+ self._progress_since = time.monotonic()
+ self._progress_signature = ""
+ self.coverage_dir = Path(coverage_dir) if coverage_dir else None
+ self._dumps = 0
+ self.dev.logcat(clear=True)
+
+ # -- acting -----------------------------------------------------------
+
+ def note(self, text: str) -> None:
+ """Record something the scenario established, for the write-up.
+
+ A finding is only half the story; the other half is what the harness
+ had arranged, and that is rarely visible in a screenshot -- "the token
+ had 12 seconds left" is the difference between a bug and a
+ misunderstanding.
+ """
+ self.notes.append(f"[{self.steps}] {text}")
+
+ def perform(self, action: Action, screen: Optional[Screen] = None) -> None:
+ """Run one action, recording it first so a crash still leaves a trace."""
+ self.actions.append(action)
+ self._write_actions()
+ op, arg = action.op, action.arg
+ if op == "tap_label":
+ current = screen or self.dev.dump()
+ target = current.find(f"^{_escape(arg)}$") or current.find(_escape(arg))
+ if target is None:
+ return
+ before = current.signature()
+ resolved = current.tap_target(target)
+ # A control the keyboard is drawing over cannot be tapped where
+ # the dump says it is -- and a dialog's dump covers only the
+ # dialog, so it reports its buttons at coordinates the keyboard
+ # owns. Tapping there presses a key: an attempt at the
+ # custom-product dialog's Add typed a "u" into the price field and
+ # the scenario went on believing it had pressed the button.
+ ime_top = self.dev.ime_top()
+ if ime_top is not None and resolved.bounds[1] >= ime_top:
+ self.note(f"{arg!r} is behind the keyboard at "
+ f"{resolved.bounds}; not tapping it")
+ return
+ interactive = resolved.clickable and resolved.enabled
+ self.dev.tap_node(target, current)
+ time.sleep(self.settle)
+ after = self.dev.dump()
+ if interactive:
+ fresh = self.session.add(oracles.silent_failure(
+ self.dev, str(arg), before, after.signature()))
+ for finding in fresh:
+ self._capture(finding, after, None)
+ elif op == "tap_xy":
+ self.dev.tap(arg[0], arg[1])
+ elif op == "long_press_label":
+ target = (screen or self.dev.dump()).find(_escape(arg))
+ if target is not None:
+ self.dev.long_press(target)
+ elif op == "type":
+ fields = (screen or self.dev.dump()).editable()
+ if fields:
+ self.dev.clear_field(fields[0], screen)
+ self.dev.type_text(arg)
+ elif op == "scroll_down":
+ self.dev.scroll(down=True, screen=screen)
+ elif op == "scroll_up":
+ self.dev.scroll(down=False, screen=screen)
+ elif op == "back":
+ self.dev.back()
+ elif op == "drawer_gesture":
+ self.dev.swipe_from_left_edge()
+ elif op == "setup_uri":
+ self.dev.setup_uri(arg)
+ elif op == "offline_blip":
+ self.dev.airplane_mode(True)
+ time.sleep(4)
+ self.dev.airplane_mode(False)
+ time.sleep(3)
+ elif op == "offline":
+ self.dev.airplane_mode(bool(arg))
+ time.sleep(3)
+ elif op == "process_death":
+ self.dump_coverage("before-kill")
+ self.dev.kill()
+ time.sleep(1.5)
+ self.dev.launch()
+ elif op == "relaunch":
+ self.dump_coverage("before-relaunch")
+ self.dev.stop()
+ self.dev.launch()
+ else:
+ raise ValueError(f"unknown action {op}")
+ self.steps += 1
+ time.sleep(self.settle)
+
+ # -- observing --------------------------------------------------------
+
+ def observe(self, with_log: bool = True,
+ log_lines: int = 800) -> tuple[Screen, list[oracles.Finding]]:
+ """Read the screen, run the oracles, keep the evidence for anything new.
+
+ Only the tail of the log is read: the whole buffer takes seconds once
+ it has filled, and the oracles are looking at what just happened.
+ """
+ # A dump that lost its race with the UI comes back empty, and every
+ # oracle then reasons about a screen that was never read.
+ screen = self.app._stable_dump()
+ # A progress message is only stuck if it has been the *same* progress
+ # message for a while, so the clock restarts whenever the screen
+ # changes.
+ signature = screen.signature()
+ if signature != self._progress_signature:
+ self._progress_signature = signature
+ self._progress_since = time.monotonic()
+ log = self.dev.logcat(lines=log_lines) if with_log else None
+ fresh = self.session.check(self.dev, screen=screen, log=log,
+ progress_since=self._progress_since)
+ self.signatures.add(signature)
+ for finding in fresh:
+ self._capture(finding, screen, log)
+ return screen, fresh
+
+ def judge(self, found: list[oracles.Finding],
+ screen: Optional[Screen] = None) -> list[oracles.Finding]:
+ """Record findings a scenario produced by its own reasoning.
+
+ The screen oracles see every dump; a scenario's own checks -- that the
+ backend and the screen disagree, that an order was left behind -- have
+ to be handed in, and this is where they get their screenshot and their
+ action list.
+ """
+ fresh = self.session.add(found)
+ if fresh:
+ shot = screen or self.dev.dump()
+ for finding in fresh:
+ self._capture(finding, shot, None)
+ return fresh
+
+ def _capture(self, finding: oracles.Finding, screen: Screen,
+ log: Optional[str]) -> None:
+ stem = f"{finding.kind}-{finding.fingerprint}"
+ self._shots += 1
+ try:
+ self.dev.screenshot(str(self.dir / f"{stem}.png"))
+ except Exception:
+ pass
+ payload = {
+ "finding": asdict(finding),
+ "fingerprint": finding.fingerprint,
+ "step": self.steps,
+ "screen": screen.texts(),
+ "signature": screen.signature(),
+ "notes": list(self.notes),
+ "actions": [asdict(a) for a in self.actions],
+ }
+ (self.dir / f"{stem}.json").write_text(json.dumps(payload, indent=2))
+ if log:
+ (self.dir / f"{stem}.logcat.txt").write_text(log[-400_000:])
+
+ # -- finishing --------------------------------------------------------
+
+ def _write_actions(self) -> None:
+ (self.dir / "actions.json").write_text(
+ json.dumps([asdict(a) for a in self.actions], indent=2))
+
+ def dump_coverage(self, tag: str = "end") -> Optional[Path]:
+ """Collect execution data, if this is an instrumented build."""
+ if self.coverage_dir is None:
+ return None
+ self._dumps += 1
+ target = self.coverage_dir / f"{self.name}-{self._dumps:02d}-{tag}.ec"
+ try:
+ return coverage_mod.dump(self.dev, target, name=f"{tag}.ec")
+ except Exception as e:
+ print(f"coverage dump failed ({tag}): {e}")
+ return None
+
+ def finish(self, extra: Optional[dict] = None) -> dict:
+ self.dump_coverage("end")
+ findings = list(self.session.findings.values())
+ summary = {
+ "name": self.name,
+ "steps": self.steps,
+ "distinct_screens": len(self.signatures),
+ "notes": self.notes,
+ "findings": [asdict(f) | {"fingerprint": f.fingerprint} for f in findings],
+ "serious": len(self.session.serious()),
+ **(extra or {}),
+ }
+ (self.dir / "summary.json").write_text(json.dumps(summary, indent=2))
+ # The terminal's own tags are what the oracles read, so they are kept
+ # in full; the rest of the system log keeps its tail, which is where
+ # an ANR or a native abort shows up.
+ log = self.dev.logcat()
+ mine = [l for l in log.splitlines()
+ if any(tag in l for tag in (
+ "taler-pos", "ConfigManager", "ConfigFragment", "PaymentManager",
+ "HistoryManager", "RefundManager", "OrderManager",
+ "PosSimHooks", "taler-wallet-hce", "MainActivity"))]
+ (self.dir / "logcat.txt").write_text(
+ "\n".join(mine)[-4_000_000:] + "\n--- other tags, tail ---\n"
+ + log[-400_000:])
+ return summary
+
+
+def _escape(text: str) -> str:
+ import re
+ return re.escape(text)
diff --git a/pos-simulator/driver/explore.py b/pos-simulator/driver/explore.py
@@ -0,0 +1,184 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Clicking on everything, in an order nobody would choose.
+
+The scenarios walk the terminal the way it is meant to be walked. This walks
+it the way it is not: from a configured, already-used terminal, pick a control
+at random -- biased towards screens the walk has not seen -- and press it. It
+is the part of the harness that finds sequences no one thought to write down.
+
+Two things keep it from wandering off into the system:
+
+* a control that would leave the app (the tutorial link opens a browser) is
+ followed, judged, and then the terminal is brought back to the front -- so
+ the walk cannot spend a hundred steps in Chrome's search suggestions;
+* the terminal is re-provisioned whenever it ends up unconfigured, because an
+ unconfigured terminal has one screen and the walk would stay on it.
+
+ python3 explore.py --steps 150 --seed 7
+ python3 explore.py --steps 400 --seed 7 --faults
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import re
+import sys
+import time
+from collections import Counter
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import merchant
+from device import Device, Screen, serial_for
+from episode import Action, Episode
+from pos import Pos, PosError
+
+SIM_ROOT = Path(os.environ.get("POS_SIM_ROOT", "/tmp/taler-pos-sim"))
+WORKER = int(os.environ.get("POS_WORKER", "0"))
+SERIAL = serial_for(WORKER)
+
+# Labels the walk must not press, and why.
+#
+# Logging out is not forbidden -- it is a legitimate thing to do and the walk
+# recovers by re-provisioning -- but it costs a provisioning round trip every
+# time, so it is rare rather than impossible.
+AVOID = re.compile(r"(?i)^(Log out)$")
+# "Share" opens the system chooser, which is a whole other app to get out of,
+# so it is tried occasionally rather than constantly.
+RARE = re.compile(r"(?i)log out|Force delete|tutorials|^share$")
+
+# Text a walk should type into whatever field it lands on: a price, something
+# that is not a price, and something a layout was not designed for.
+TYPED = [
+ "1.00", "0", "0.00", "99999999", "-1", "1,5", "1.2.3", "abc",
+ " ", "'; drop table orders; --", "Добро",
+ "القهوة", "\U0001F382", "x" * 300,
+]
+
+
+def choose(screen: Screen, seen: Counter, rng: random.Random):
+ """Pick the next action, favouring what has not been pressed yet."""
+ candidates = []
+ for node in screen.tappable():
+ label = node.label.strip()
+ if label and AVOID.search(label):
+ continue
+ weight = 1.0 / (1 + seen[label or str(node.bounds)])
+ if label and RARE.search(label):
+ weight *= 0.05
+ candidates.append((weight, node))
+ if not candidates:
+ return Action("back")
+ total = sum(w for w, _ in candidates)
+ pick = rng.uniform(0, total)
+ upto = 0.0
+ for weight, node in candidates:
+ upto += weight
+ if upto >= pick:
+ label = node.label.strip()
+ if node.editable:
+ return Action("type", rng.choice(TYPED))
+ if label:
+ return Action("tap_label", label)
+ return Action("tap_xy", list(node.center))
+ return Action("back")
+
+
+def main(argv: list[str]) -> int:
+ ap = argparse.ArgumentParser(description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--steps", type=int, default=150)
+ ap.add_argument("--seed", type=int, default=None)
+ ap.add_argument("--faults", action="store_true",
+ help="mix in airplane mode, process death and relaunches")
+ ap.add_argument("--out", default=None)
+ args = ap.parse_args(argv)
+
+ seed = args.seed if args.seed is not None else random.randrange(1 << 30)
+ rng = random.Random(seed)
+ stamp = time.strftime("%Y%m%d-%H%M%S")
+ out_dir = Path(args.out or (SIM_ROOT / "out" / f"explore-{stamp}-w{WORKER}"))
+ out_dir.mkdir(parents=True, exist_ok=True)
+
+ dev = Device(SERIAL)
+ ep = Episode(dev, out_dir, name=f"explore-seed{seed}",
+ coverage_dir=SIM_ROOT / "run" / "coverage")
+ app = Pos(dev)
+ app.before_wipe = lambda: ep.dump_coverage("before-wipe")
+
+ inst = merchant.demo()
+ ep.note(f"seed {seed}, {args.steps} steps, demo instance "
+ f"{inst.merchant.instance}")
+ app.fresh_start()
+ app.provision_by_uri(inst.setup_uri())
+ ep.observe()
+
+ seen: Counter[str] = Counter()
+ for step in range(args.steps):
+ screen, _ = ep.observe()
+ if not screen.activity.startswith("net.taler.merchantpos"):
+ # Back first, then launch. Bringing the terminal to the front
+ # while a system dialog is up -- the share sheet, which "Share
+ # payment URI" opens -- leaves the dialog on top of it, so the
+ # next step sees the same foreign activity and the walk spends the
+ # rest of its budget bouncing off it. One seed lost 150 of its
+ # 220 steps that way.
+ ep.note(f"step {step}: outside the app ({screen.activity}); coming back")
+ dev.back()
+ time.sleep(1.5)
+ if not dev.dump().activity.startswith("net.taler.merchantpos"):
+ dev.launch()
+ time.sleep(3)
+ continue
+ if screen.find(r"Merchant portal URL") and rng.random() < 0.7:
+ # Unconfigured: one screen, nothing to explore. Put it back.
+ ep.note(f"step {step}: unconfigured; provisioning again")
+ try:
+ app.provision_by_uri(inst.setup_uri())
+ except (PosError, TimeoutError) as e:
+ ep.note(f"could not re-provision: {e}")
+ app.fresh_start()
+ continue
+ if args.faults and rng.random() < 0.04:
+ fault = rng.choice(["offline_blip", "process_death", "relaunch"])
+ ep.note(f"step {step}: fault {fault}")
+ ep.perform(Action(fault))
+ time.sleep(4)
+ continue
+ action = choose(screen, seen, rng)
+ if action.op == "tap_label":
+ seen[str(action.arg)] += 1
+ ep.perform(action, screen)
+ if step % 25 == 0:
+ ep.dump_coverage(f"step{step:04d}")
+ print(f" step {step:>4} {len(ep.signatures)} screens, "
+ f"{len(ep.session.serious())} serious finding(s)", flush=True)
+
+ summary = ep.finish({"seed": seed, "steps_requested": args.steps,
+ "faults": args.faults})
+ print(json.dumps({k: v for k, v in summary.items() if k != "findings"},
+ indent=2))
+ for finding in summary["findings"]:
+ print(f" [{finding['kind']}] {finding['detail'][:200]}")
+ print(f"artifacts: {out_dir}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/pos-simulator/driver/faults.py b/pos-simulator/driver/faults.py
@@ -0,0 +1,453 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Breaking a backend that works, with `taler-twister`.
+
+The mock backend answers the ways a *misconfigured* merchant answers: a fresh
+instance, no bank account, the wrong currency. What it cannot do is be the
+real backend and go wrong halfway through, because everything it says is
+something the harness wrote. A reply that is the demo backend's own, with one
+field deleted or one status code changed, is a different kind of input: the
+terminal's own parsers and error branches see something they have no reason to
+expect, and the rest of the exchange is real.
+
+That is what twister is for -- the fault-injecting proxy GNU Taler's C test
+suites use. It sits in front of a real backend and, on command, mutates the
+*next* request or response: a status code, a deleted JSON field, a replaced
+value, a flipped character, a truncated body. Each mutation is consumed when
+it fires, which suits a test script issuing one request at a time and does not
+suit a UI that polls; `Twister.sustain()` covers that by re-arming in a loop.
+
+Two things have to be bridged to put it under the terminal.
+
+* **TLS.** The terminal hard-codes `https://` for the merchant URL -- see
+ `ConfigFragment.sanitizeMerchantUrlAndUpdateFields` -- and twister is a plain
+ HTTP proxy. `TlsFront` terminates TLS with the same certificate the mock
+ uses, which the `sim` build type trusts, and relays bytes to twister. A byte
+ relay is enough: nothing here needs to understand the HTTP it carries, so
+ keep-alive, chunking and uploads pass through untouched.
+* **The path prefix.** Twister appends the request's path to
+ `DESTINATION_BASE_URL`, so the instance path has to be in the terminal's
+ merchant URL and not in the destination. `Twister.merchant_url` says what
+ to configure the terminal with.
+
+`TlsFront` also injects the faults twister has no notion of, because they
+happen below HTTP: a connection that closes in the middle of a response body,
+or one that is reset while the request is still going up. Those are the inputs
+that reach `Response.getFailureString`'s `IOException` arm, which no status
+code can produce.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import select
+import socket
+import ssl
+import subprocess
+import threading
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator, Optional
+
+HERE = Path(__file__).resolve().parent
+TLS_DIR = HERE.parent / "tls"
+
+# Built on the emulator host against its system GNUnet; see README.
+TWISTER_PREFIX = Path(os.environ.get("POS_TWISTER_PREFIX", "/tmp/twister-build/inst"))
+SERVICE = os.environ.get("POS_TWISTER_SERVICE", str(TWISTER_PREFIX / "bin" / "taler-twister-service"))
+CLI = os.environ.get("POS_TWISTER_CLI", str(TWISTER_PREFIX / "bin" / "taler-twister"))
+
+
+class FaultError(RuntimeError):
+ """The fault could not be armed -- a harness problem, not the app's."""
+
+
+def available() -> bool:
+ return Path(SERVICE).is_file() and Path(CLI).is_file()
+
+
+def _env() -> dict:
+ env = dict(os.environ)
+ lib = str(TWISTER_PREFIX / "lib")
+ env["LD_LIBRARY_PATH"] = lib + ":" + env.get("LD_LIBRARY_PATH", "")
+ return env
+
+
+@dataclass
+class Twister:
+ """A `taler-twister-service` in front of one backend.
+
+ `destination` is the backend's origin with no path and no trailing slash
+ (`https://backend.demo.taler.net`); twister concatenates it with whatever
+ path the terminal asks for. `chaos` is a percentage: every proxied request
+ has that chance of coming back 503 without being asked, which is what the
+ random walk wants and what a deliberate scenario does not.
+ """
+
+ destination: str
+ port: int
+ front_port: int
+ run_dir: Path
+ chaos: int = 0
+ _proc: Optional[subprocess.Popen] = None
+ _front: Optional["TlsFront"] = None
+ _conf: Optional[Path] = None
+ _armed: list[str] = field(default_factory=list)
+
+ @property
+ def host(self) -> str:
+ """What the terminal should be pointed at."""
+ return f"localhost:{self.front_port}"
+
+ def merchant_url(self, instance: str) -> str:
+ return f"https://{self.host}/instances/{instance}"
+
+ # -- lifecycle --------------------------------------------------------
+
+ def start(self) -> "Twister":
+ self.run_dir.mkdir(parents=True, exist_ok=True)
+ self._conf = self.run_dir / f"twister-{self.port}.conf"
+ sock = self.run_dir / f"twister-{self.port}.sock"
+ # UNIX_MATCH_UID/GID off: the driver and the service are the same user
+ # here, but a harness run under sudo is not, and the failure that
+ # produces is an unexplained hang in the CLI rather than a refusal.
+ self._conf.write_text(
+ "[twister]\n"
+ f"HTTP_PORT = {self.port}\n"
+ "SERVE = tcp\n"
+ f"DESTINATION_BASE_URL = {self.destination.rstrip('/')}\n"
+ "HOSTNAME = localhost\n"
+ "ACCEPT_FROM = 127.0.0.1;\n"
+ "ACCEPT_FROM6 = ::1;\n"
+ f"UNIXPATH = {sock}\n"
+ "UNIX_MATCH_UID = NO\n"
+ "UNIX_MATCH_GID = NO\n"
+ + (f"CHAOS_RATE = {self.chaos}\n" if self.chaos else "")
+ )
+ log = open(self.run_dir / f"twister-{self.port}.log", "ab")
+ self._proc = subprocess.Popen(
+ [SERVICE, "-c", str(self._conf)], env=_env(),
+ stdout=log, stderr=subprocess.STDOUT)
+ self._wait_alive()
+ self._front = TlsFront(listen=self.front_port, upstream=self.port).start()
+ return self
+
+ def _wait_alive(self, timeout: float = 15.0) -> None:
+ """Wait for the control socket, which is the last thing to come up."""
+ deadline = time.time() + timeout
+ last = ""
+ while time.time() < deadline:
+ if self._proc and self._proc.poll() is not None:
+ raise FaultError(
+ f"twister-service exited with {self._proc.returncode}; see "
+ f"{self.run_dir}/twister-{self.port}.log")
+ try:
+ self._cli("-a")
+ return
+ except FaultError as e:
+ last = str(e)
+ time.sleep(0.3)
+ raise FaultError(f"twister-service did not come up: {last}")
+
+ def stop(self) -> None:
+ if self._front is not None:
+ self._front.stop()
+ self._front = None
+ if self._proc is not None:
+ self._proc.terminate()
+ try:
+ self._proc.wait(timeout=5)
+ except subprocess.TimeoutExpired:
+ self._proc.kill()
+ self._proc = None
+
+ def __enter__(self) -> "Twister":
+ return self.start()
+
+ def __exit__(self, *exc) -> None:
+ self.stop()
+
+ # -- arming -----------------------------------------------------------
+
+ def _cli(self, *args: str) -> str:
+ assert self._conf is not None
+ cmd = [CLI, "-c", str(self._conf), *args]
+ try:
+ out = subprocess.run(cmd, env=_env(), capture_output=True,
+ text=True, timeout=20)
+ except subprocess.TimeoutExpired:
+ raise FaultError(f"twister CLI hung: {' '.join(args)}")
+ if out.returncode != 0:
+ raise FaultError(
+ f"twister CLI failed ({out.returncode}): {' '.join(args)}: "
+ f"{(out.stderr or out.stdout).strip()[:200]}")
+ return out.stdout
+
+ def _arm(self, *args: str, label: str) -> None:
+ self._cli(*args)
+ self._armed.append(label)
+
+ @property
+ def armed(self) -> list[str]:
+ """What has been armed, for the episode's notes."""
+ return list(self._armed)
+
+ def status(self, code: int) -> None:
+ """Answer the next proxied request with this status code."""
+ self._arm("-r", str(code), label=f"status {code}")
+
+ def delete(self, path: str) -> None:
+ """Drop a field from the next response (`a.b.0` indexes arrays)."""
+ self._arm("-d", path, label=f"delete {path}")
+
+ def modify(self, path: str, value: str) -> None:
+ """Replace a field in the next response.
+
+ A value that parses as JSON is inserted as JSON, so `"null"` and `"[]"`
+ are objects and anything else is a string. The field has to exist
+ already -- twister replaces, it does not add.
+ """
+ self._arm("-m", path, "-V", value, label=f"modify {path}={value}")
+
+ def modify_upload(self, path: str, value: str) -> None:
+ """Replace a field in the next *request* the terminal sends."""
+ self._arm("-X", path, "-V", value, label=f"modify-ul {path}={value}")
+
+ def header(self, name: str, value: str) -> None:
+ """Replace a response header."""
+ self._arm("-H", name, "-V", value, label=f"header {name}={value}")
+
+ def flip(self, path: str) -> None:
+ """Flip a random character in a string field of the next response."""
+ self._arm("-f", path, label=f"flip {path}")
+
+ def malform(self) -> None:
+ """Truncate the next response body, so it is not JSON any more."""
+ self._arm("-M", label="malform")
+
+ def malform_upload(self) -> None:
+ self._arm("-U", label="malform-ul")
+
+ # -- a mutation that outlives one request -----------------------------
+
+ @contextmanager
+ def sustain(self, *arm: tuple, every: float = 0.4) -> Iterator[None]:
+ """Keep a mutation armed while the block runs.
+
+ A twister mutation fires once. The terminal polls -- the payment
+ screen re-checks the order every second or so -- so a mutation armed
+ once is visible for a single poll and then undone by the next, and the
+ dialog it was supposed to raise opens and closes before the harness can
+ see it. Re-arming in a loop keeps the backend wrong for as long as the
+ scenario needs it to be.
+
+ with tw.sustain(("modify", "taler_pay_uri", insecure)):
+ app.read_dialog()
+
+ Each tuple is a method name and its arguments. Failures inside the
+ loop are collected rather than raised: the loop runs in its own thread,
+ where an exception would be lost, and arming can legitimately fail at
+ the end of a block when the service is already going away.
+ """
+ stop = threading.Event()
+ errors: list[str] = []
+
+ def pump() -> None:
+ while not stop.is_set():
+ for spec in arm:
+ try:
+ getattr(self, spec[0])(*spec[1:])
+ except FaultError as e:
+ errors.append(str(e))
+ stop.set()
+ return
+ stop.wait(every)
+
+ for spec in arm: # fail loudly on a bad spec
+ getattr(self, spec[0])(*spec[1:])
+ thread = threading.Thread(target=pump, daemon=True)
+ thread.start()
+ try:
+ yield
+ finally:
+ stop.set()
+ thread.join(timeout=5)
+ if errors:
+ raise FaultError(errors[0])
+
+
+# --------------------------------------------------------------------------
+# The TLS front
+
+
+@dataclass
+class TlsFront:
+ """TLS termination in front of twister, with transport-level faults.
+
+ `fault` is set between requests and applies to every connection until it
+ is cleared:
+
+ none relay faithfully
+ cut forward the response headers, then close the connection
+ in the middle of the body
+ reset reset the connection as soon as the request is complete
+ trickle relay the response a few bytes at a time
+
+ `cut` is the one that matters. Every HTTP error the terminal can be shown
+ through a status code it already has a branch for; a body that stops
+ arriving halfway is an `IOException` out of the Ktor engine, which is a
+ different arm of `Response.getFailureString` and reaches the terminal as a
+ message nobody wrote.
+ """
+
+ listen: int
+ upstream: int
+ fault: str = "none"
+ cut_after: int = 200
+ _sock: Optional[socket.socket] = None
+ _ctx: Optional[ssl.SSLContext] = None
+ _stop: threading.Event = field(default_factory=threading.Event)
+ _thread: Optional[threading.Thread] = None
+ seen: int = 0
+
+ def start(self) -> "TlsFront":
+ self._ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+ self._ctx.load_cert_chain(certfile=str(TLS_DIR / "srv.crt"),
+ keyfile=str(TLS_DIR / "srv.key"))
+ self._sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ self._sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ self._sock.bind(("127.0.0.1", self.listen))
+ self._sock.listen(32)
+ self._sock.settimeout(0.5)
+ self._thread = threading.Thread(target=self._accept_loop, daemon=True)
+ self._thread.start()
+ return self
+
+ def stop(self) -> None:
+ self._stop.set()
+ if self._thread is not None:
+ self._thread.join(timeout=3)
+ if self._sock is not None:
+ self._sock.close()
+ self._sock = None
+
+ def _accept_loop(self) -> None:
+ assert self._sock is not None and self._ctx is not None
+ while not self._stop.is_set():
+ try:
+ raw, _ = self._sock.accept()
+ except socket.timeout:
+ continue
+ except OSError:
+ return
+ self.seen += 1
+ threading.Thread(target=self._serve, args=(raw,), daemon=True).start()
+
+ def _serve(self, raw: socket.socket) -> None:
+ assert self._ctx is not None
+ try:
+ client = self._ctx.wrap_socket(raw, server_side=True)
+ except (ssl.SSLError, OSError):
+ raw.close()
+ return
+ fault = self.fault
+ if fault == "reset":
+ # SO_LINGER with a zero timeout turns close() into an RST, which is
+ # what a peer going away without a FIN looks like.
+ client.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER,
+ b"\x01\x00\x00\x00\x00\x00\x00\x00")
+ client.close()
+ return
+ try:
+ up = socket.create_connection(("127.0.0.1", self.upstream), timeout=10)
+ except OSError:
+ client.close()
+ return
+ self._relay(client, up, fault)
+
+ def _relay(self, client: ssl.SSLSocket, up: socket.socket, fault: str) -> None:
+ """Pump both directions until either side is done."""
+ sent_down = 0
+ headers_done = False
+ try:
+ client.setblocking(False)
+ up.setblocking(False)
+ while True:
+ ready, _, _ = select.select([client, up], [], [], 30)
+ if not ready:
+ return
+ for sock in ready:
+ try:
+ data = sock.recv(65536)
+ except ssl.SSLWantReadError:
+ continue
+ except OSError:
+ return
+ if not data:
+ return
+ if sock is client:
+ up.sendall(data)
+ continue
+ if fault == "trickle":
+ for i in range(0, len(data), 8):
+ client.sendall(data[i:i + 8])
+ time.sleep(0.05)
+ continue
+ if fault == "cut":
+ if not headers_done and b"\r\n\r\n" in data:
+ head, _, body = data.partition(b"\r\n\r\n")
+ client.sendall(head + b"\r\n\r\n")
+ headers_done = True
+ data = body
+ if headers_done:
+ room = max(0, self.cut_after - sent_down)
+ if room:
+ client.sendall(data[:room])
+ sent_down += min(room, len(data))
+ if sent_down >= self.cut_after:
+ return
+ continue
+ client.sendall(data)
+ finally:
+ for sock in (client, up):
+ try:
+ sock.close()
+ except OSError:
+ pass
+
+ @contextmanager
+ def transport(self, fault: str) -> Iterator[None]:
+ """Apply a transport fault for the duration of the block."""
+ before = self.fault
+ self.fault = fault
+ try:
+ yield
+ finally:
+ self.fault = before
+
+
+def front_of(tw: Twister) -> TlsFront:
+ assert tw._front is not None, "twister not started"
+ return tw._front
+
+
+# The pay URI the terminal is supposed to object to. `taler+http://` is what a
+# backend behind a plain-HTTP reverse proxy hands out, and the terminal offers
+# to upgrade it, to use it anyway, or to cancel the order -- three branches of
+# `PaymentManager` that no correctly configured backend can reach.
+def insecure_pay_uri(uri: str) -> str:
+ return re.sub(r"^taler://", "taler+http://", uri)
diff --git a/pos-simulator/driver/inventory.py b/pos-simulator/driver/inventory.py
@@ -0,0 +1,164 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""A catalogue on a *real* backend, arranged to stress the screens that show it.
+
+The mock can answer anything, which is exactly why it cannot settle what the
+order grid, the order-details page and the receipt do with a product that a
+real merchant really sold: the mock's products are never bought, never
+recorded in a contract and never read back out of an order. So this puts a
+handful of deliberately awkward products on the demo instance and leaves them
+there, named so that a passer-by can see where they came from:
+
+ possim-image carries a real PNG, to see whether anything renders it
+ possim-long-name a description no column is wide enough for
+ possim-kg sold by weight, so the quantity is fractional
+ possim-unicode a name in four scripts and an emoji
+ possim-cheap one cent, which is where per-unit arithmetic rounds
+ possim-free zero, which several screens treat as "no price"
+
+They go in a category of their own ("POS simulator") so they can be found in
+the grid without scrolling past the instance's own hundred-odd products, and
+so that the category tab itself gets exercised.
+
+ python3 inventory.py show
+ python3 inventory.py ensure
+ python3 inventory.py remove
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import struct
+import sys
+import zlib
+from pathlib import Path
+from typing import Optional
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import merchant
+
+CATEGORY = "POS simulator"
+PREFIX = "possim-"
+
+
+def _png(width: int, height: int, rgb: tuple[int, int, int]) -> bytes:
+ """A solid-colour PNG, built here rather than shipped as a binary blob.
+
+ `decodeProductImage` asks `BitmapFactory` for the real dimensions before
+ it decodes, so the image has to be a real one; a one-pixel placeholder
+ would not tell us what the grid does with an image that has a shape.
+ """
+ raw = b"".join(b"\x00" + bytes(rgb) * width for _ in range(height))
+
+ def chunk(tag: bytes, data: bytes) -> bytes:
+ return (struct.pack(">I", len(data)) + tag + data
+ + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF))
+
+ header = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+ return (b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", header)
+ + chunk(b"IDAT", zlib.compress(raw, 9)) + chunk(b"IEND", b""))
+
+
+def data_url(width: int = 240, height: int = 240,
+ rgb: tuple[int, int, int] = (0x00, 0x42, 0xB3)) -> str:
+ """The `data:image/png;base64,...` shape the terminal accepts."""
+ return "data:image/png;base64," + base64.b64encode(
+ _png(width, height, rgb)).decode()
+
+
+# description, price (without the currency), unit, extra
+SPEC: list[tuple[str, str, str, str, dict]] = [
+ ("image", "Simulator tile with a picture", "2.50", "item",
+ {"image": data_url()}),
+ ("long-name",
+ "Simulator product with a deliberately long description that no column "
+ "on any of the terminal's screens is wide enough to show in one line, "
+ "written out at length so that the truncation can be seen",
+ "1.00", "item", {}),
+ ("kg", "Simulator loose goods", "4.00", "kg", {}),
+ ("unicode", "Café ☕ ことわざ Ωμέγα عربى", "3.00", "item", {}),
+ ("cheap", "Simulator one-cent item", "0.01", "item", {}),
+ ("free", "Simulator free sample", "0.00", "item", {}),
+]
+
+
+def ensure(inst: Optional[merchant.Instance] = None) -> dict:
+ """Put the catalogue in place, and say what was already there.
+
+ Idempotent: a product that exists is left alone (the backend answers 409
+ and `add_product` accepts that), so this can be run before every round.
+ """
+ inst = inst or merchant.demo()
+ token = inst.token.value
+ existing = {c["name"]: c["category_id"] for c in inst.merchant.categories(token)}
+ if CATEGORY in existing:
+ category_id = existing[CATEGORY]
+ else:
+ category_id = inst.merchant.add_category(token, CATEGORY)
+ have = {p["product_id"] for p in inst.merchant.products(token)}
+ added = []
+ for suffix, description, price, unit, extra in SPEC:
+ product_id = PREFIX + suffix
+ if product_id in have:
+ continue
+ inst.merchant.add_product(
+ token, product_id, description, f"{inst.currency}:{price}",
+ total_stock=-1, unit=unit,
+ categories=[category_id] if category_id >= 0 else None,
+ extra=extra)
+ added.append(product_id)
+ return {"category": CATEGORY, "category_id": category_id,
+ "added": added, "already": sorted(have & {PREFIX + s[0] for s in SPEC})}
+
+
+def remove(inst: Optional[merchant.Instance] = None) -> list[str]:
+ """Take them away again. A product in a past order cannot be deleted."""
+ inst = inst or merchant.demo()
+ token = inst.token.value
+ gone = []
+ for product in inst.merchant.products(token):
+ if product["product_id"].startswith(PREFIX):
+ inst.merchant.delete_product(token, product["product_id"])
+ gone.append(product["product_id"])
+ return gone
+
+
+def show(inst: Optional[merchant.Instance] = None) -> None:
+ inst = inst or merchant.demo()
+ token = inst.token.value
+ print(f"{inst.label}: {inst.currency}")
+ for category in inst.merchant.categories(token):
+ print(f" category {category['category_id']}: {category['name']}")
+ # The list endpoint answers with summaries; the detail endpoint is where
+ # the price, the unit and the image actually are.
+ for entry in inst.merchant.products(token):
+ if not entry["product_id"].startswith(PREFIX):
+ continue
+ full = inst.merchant.product(token, entry["product_id"])
+ image = full.get("image") or ""
+ print(f" {entry['product_id']:<20} {full.get('price')!r:<14} "
+ f"{full.get('unit')!r:<8} image={len(image):>6}B "
+ f"{str(full.get('description'))[:44]!r}")
+
+
+if __name__ == "__main__":
+ want = sys.argv[1] if len(sys.argv) > 1 else "show"
+ if want == "ensure":
+ print(ensure())
+ elif want == "remove":
+ print(remove())
+ else:
+ show()
diff --git a/pos-simulator/driver/merchant.py b/pos-simulator/driver/merchant.py
@@ -0,0 +1,447 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""The merchant backend, as the harness sees it.
+
+Two jobs. The first is *provisioning*: minting the access tokens the terminal
+is configured with, which is the only way to give it a credential that expires
+on a schedule the harness chooses -- the login form always asks for
+`TokenDuration.Forever`, so an expiring session cannot be set up through the
+UI at all. The second is acting as the merchant's own back office, so a
+scenario can arrange the state the terminal is supposed to react to: an order
+that is already claimed, an order past its refund deadline, a product that is
+out of stock.
+
+Only the standard merchant HTTP API is used, over `urllib`, so this runs
+wherever Python does and needs nothing installed.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+DEMO_BASE = os.environ.get("POS_MERCHANT", "https://backend.demo.taler.net")
+DEMO_INSTANCE = os.environ.get("POS_INSTANCE", "sandbox")
+# The password the terminal's own "Fill demo credentials" button types.
+DEMO_SECRET = os.environ.get("POS_SECRET", "sandbox")
+
+TIMEOUT = 30
+
+
+class MerchantError(RuntimeError):
+ """A backend request that came back with a status the caller did not expect."""
+
+ def __init__(self, status: int, body: str, url: str):
+ self.status = status
+ self.body = body
+ self.url = url
+ try:
+ detail = json.loads(body)
+ hint = detail.get("hint") or detail.get("detail") or body
+ self.code = detail.get("code")
+ except (json.JSONDecodeError, AttributeError):
+ hint = body
+ self.code = None
+ super().__init__(f"HTTP {status} from {url}: {str(hint)[:300]}")
+
+
+@dataclass
+class Token:
+ """An access token, with the expiry the harness asked for.
+
+ `expires_at` is wall-clock seconds, as the backend reports it; it is the
+ only honest way to decide whether a session *should* still be alive, since
+ the terminal shows nothing about its own credential.
+ """
+
+ value: str
+ scope: str
+ expires_at: Optional[int]
+ refreshable: bool = False
+
+ @property
+ def expired(self) -> bool:
+ return self.expires_at is not None and time.time() >= self.expires_at
+
+ @property
+ def seconds_left(self) -> Optional[float]:
+ if self.expires_at is None:
+ return None
+ return self.expires_at - time.time()
+
+ def __str__(self) -> str:
+ if self.expires_at is None:
+ return f"token(forever, {self.value[:18]}...)"
+ return f"token({self.seconds_left:.0f}s left, {self.value[:18]}...)"
+
+
+class Merchant:
+ """One instance of one merchant backend.
+
+ `base` is the backend root (no instance path); `instance` names the
+ instance. The terminal is configured with `<base>/instances/<instance>`,
+ which is what `pos_url` returns.
+ """
+
+ def __init__(self, base: str = DEMO_BASE, instance: str = DEMO_INSTANCE,
+ secret: str = DEMO_SECRET, ca_file: Optional[str] = None):
+ self.base = base.rstrip("/")
+ self.instance = instance
+ self.secret = secret
+ # The mock backend answers TLS with the simulator's own CA, which the
+ # host's trust store does not know; the emulator learns it from the
+ # sim build's network security config, and the driver from here.
+ self.ctx: Optional[ssl.SSLContext] = None
+ if ca_file:
+ self.ctx = ssl.create_default_context(cafile=ca_file)
+
+ # -- plumbing ---------------------------------------------------------
+
+ @property
+ def instance_url(self) -> str:
+ return f"{self.base}/instances/{self.instance}"
+
+ def pos_url(self) -> str:
+ """What the terminal stores as its merchant URL."""
+ return self.instance_url
+
+ def _request(self, method: str, path: str, *, token: Optional[str] = None,
+ body: Any = None, headers: Optional[dict[str, str]] = None,
+ expect: tuple[int, ...] = (200, 204),
+ absolute: bool = False) -> tuple[int, Any]:
+ url = path if absolute else f"{self.instance_url}/{path.lstrip('/')}"
+ data = None
+ hdrs = dict(headers or {})
+ if body is not None:
+ data = json.dumps(body).encode()
+ hdrs["Content-Type"] = "application/json"
+ if token:
+ # The backend accepts the token with or without its prefix, but
+ # only the prefixed form works everywhere, and the terminal adds
+ # the prefix itself when a bare token gets a 401 -- so normalise.
+ value = token if token.startswith("secret-token:") else f"secret-token:{token}"
+ hdrs["Authorization"] = f"Bearer {value}"
+ req = urllib.request.Request(url, data=data, headers=hdrs, method=method)
+ try:
+ with urllib.request.urlopen(req, timeout=TIMEOUT, context=self.ctx) as resp:
+ raw = resp.read()
+ status = resp.status
+ except urllib.error.HTTPError as e:
+ raw = e.read()
+ status = e.code
+ payload: Any = None
+ if raw:
+ try:
+ payload = json.loads(raw)
+ except json.JSONDecodeError:
+ payload = raw.decode(errors="replace")
+ if status not in expect:
+ raise MerchantError(status, raw.decode(errors="replace") if raw else "", url)
+ return status, payload
+
+ # -- the backend itself -----------------------------------------------
+
+ def config(self) -> dict:
+ _, payload = self._request("GET", f"{self.base}/config", absolute=True)
+ return payload
+
+ def currency(self) -> str:
+ return self.config()["currency"]
+
+ def backend_version(self) -> str:
+ return self.config()["version"]
+
+ # -- credentials ------------------------------------------------------
+
+ def mint_token(self, seconds: Optional[int] = None, scope: str = "write",
+ secret: Optional[str] = None,
+ refreshable: bool = False) -> Token:
+ """Mint an access token, optionally one that expires.
+
+ `seconds=None` asks for a token that never expires, which is what the
+ login form would produce. Anything else is a credential the terminal
+ cannot obtain for itself, and is the whole point of this method: the
+ only way to watch the app handle a session ending is to hand it a
+ session that ends.
+ """
+ duration = {"d_us": "forever"} if seconds is None else {
+ "d_us": int(seconds * 1_000_000)}
+ body: dict[str, Any] = {"scope": scope, "duration": duration}
+ if refreshable:
+ body["refreshable"] = True
+ status, payload = self._request(
+ "POST", "private/token", token=secret or self.secret, body=body,
+ expect=(200, 202))
+ if status == 202:
+ raise MerchantError(
+ 202, json.dumps(payload),
+ f"{self.instance_url}/private/token")
+ expires = None
+ exp = payload.get("expiration") or {}
+ if isinstance(exp, dict) and isinstance(exp.get("t_s"), int):
+ expires = exp["t_s"]
+ return Token(
+ value=payload["token"],
+ scope=payload.get("scope", scope),
+ expires_at=expires,
+ refreshable=bool(payload.get("refreshable")),
+ )
+
+ def revoke_token(self, token: str) -> None:
+ """Drop a token server side, so the next request with it gets a 401.
+
+ This is how a session is ended at a moment of the harness's choosing,
+ without waiting out an expiry.
+ """
+ self._request("DELETE", "private/token", token=token, expect=(204, 200, 404))
+
+ def pos_config(self, token: str) -> dict:
+ """What the terminal reads at startup: categories and products."""
+ _, payload = self._request("GET", "private/pos", token=token)
+ return payload
+
+ # -- instances --------------------------------------------------------
+
+ def provision_instance(self, instance_id: str, name: str, password: str,
+ email: Optional[str] = None,
+ token_validity_ms: int = 86_400_000) -> dict:
+ """Self-provision a fresh instance.
+
+ Returns the body on success. A backend with a mandatory TAN channel
+ answers 202 with a challenge instead, which is not something the
+ harness can solve on its own -- see README, "a fresh instance" -- so
+ that case is raised with the challenge attached rather than swallowed.
+ """
+ body = {
+ "id": instance_id,
+ "name": name,
+ "auth": {"method": "token", "password": f"secret-token:{password}"},
+ "address": {},
+ "jurisdiction": {},
+ "use_stefan": True,
+ }
+ if email:
+ body["email"] = email
+ status, payload = self._request(
+ "POST", f"{self.base}/instances?token_validity_ms={token_validity_ms}",
+ body=body, absolute=True, expect=(200, 204, 202, 409))
+ if status == 202:
+ raise MerchantError(202, json.dumps(payload), f"{self.base}/instances")
+ if status == 409:
+ raise MerchantError(409, json.dumps(payload), f"{self.base}/instances")
+ return payload or {}
+
+ def accounts(self, token: str) -> list[dict]:
+ """The instance's bank accounts.
+
+ An instance with none cannot be paid out and the backend refuses to
+ create orders for it, which is one of the two ways a terminal can be
+ pointed at a badly configured merchant.
+ """
+ _, payload = self._request("GET", "private/accounts", token=token)
+ return (payload or {}).get("accounts", [])
+
+ # -- inventory --------------------------------------------------------
+
+ def products(self, token: str) -> list[dict]:
+ _, payload = self._request("GET", "private/products", token=token)
+ return (payload or {}).get("products", [])
+
+ def product(self, token: str, product_id: str) -> dict:
+ _, payload = self._request("GET", f"private/products/{product_id}", token=token)
+ return payload
+
+ def add_product(self, token: str, product_id: str, description: str,
+ price: str, *, total_stock: int = -1,
+ unit: str = "item", categories: Optional[list[int]] = None,
+ extra: Optional[dict] = None) -> None:
+ body: dict[str, Any] = {
+ "product_id": product_id,
+ "description": description,
+ "unit": unit,
+ "price": price,
+ "total_stock": total_stock,
+ "address": {},
+ "next_restock": {"t_s": "never"},
+ }
+ if categories is not None:
+ body["categories"] = categories
+ if extra:
+ body.update(extra)
+ self._request("POST", "private/products", token=token, body=body,
+ expect=(204, 200, 409))
+
+ def delete_product(self, token: str, product_id: str) -> None:
+ self._request("DELETE", f"private/products/{product_id}", token=token,
+ expect=(204, 200, 404, 409))
+
+ def categories(self, token: str) -> list[dict]:
+ _, payload = self._request("GET", "private/categories", token=token)
+ return (payload or {}).get("categories", [])
+
+ def add_category(self, token: str, name: str,
+ name_i18n: Optional[dict] = None) -> int:
+ body: dict[str, Any] = {"name": name}
+ if name_i18n:
+ body["name_i18n"] = name_i18n
+ _, payload = self._request("POST", "private/categories", token=token,
+ body=body, expect=(200, 204, 409))
+ return (payload or {}).get("category_id", -1)
+
+ # -- orders -----------------------------------------------------------
+
+ def create_order(self, token: str, amount: str, summary: str, *,
+ pay_deadline_s: Optional[int] = None,
+ refund_deadline_s: Optional[int] = None,
+ fulfillment_url: Optional[str] = None,
+ extra_order: Optional[dict] = None) -> dict:
+ """Post an order the way the terminal would, with a controllable deadline.
+
+ A pay deadline a few seconds out is how the "no payment within the
+ payment period" path is reached without waiting an hour, and a refund
+ deadline in the past is how the refund screen's deadline error is.
+ """
+ order: dict[str, Any] = {"amount": amount, "summary": summary}
+ if pay_deadline_s is not None:
+ order["pay_deadline"] = {"t_s": int(time.time()) + pay_deadline_s}
+ if refund_deadline_s is not None:
+ order["refund_deadline"] = {"t_s": int(time.time()) + refund_deadline_s}
+ if fulfillment_url:
+ order["fulfillment_url"] = fulfillment_url
+ if extra_order:
+ order.update(extra_order)
+ _, payload = self._request("POST", "private/orders", token=token,
+ body={"order": order})
+ return payload
+
+ def order_status(self, token: str, order_id: str) -> dict:
+ _, payload = self._request("GET", f"private/orders/{order_id}", token=token)
+ return payload
+
+ def pay_uri(self, token: str, order_id: str) -> Optional[str]:
+ return self.order_status(token, order_id).get("taler_pay_uri")
+
+ def delete_order(self, token: str, order_id: str, force: bool = False) -> int:
+ suffix = "?force=yes" if force else ""
+ status, _ = self._request("DELETE", f"private/orders/{order_id}{suffix}",
+ token=token, expect=(204, 200, 404, 409))
+ return status
+
+ def history(self, token: str, limit: int = -20,
+ offset: Optional[int] = None) -> list[dict]:
+ query = f"?limit={limit}"
+ if offset is not None:
+ query += f"&offset={offset}"
+ _, payload = self._request("GET", f"private/orders{query}", token=token)
+ return (payload or {}).get("orders", [])
+
+ def refund(self, token: str, order_id: str, amount: str,
+ reason: str = "pos-simulator") -> dict:
+ _, payload = self._request("POST", f"private/orders/{order_id}/refund",
+ token=token,
+ body={"refund": amount, "reason": reason})
+ return payload
+
+ def claim_order(self, order_id: str, claim_token: Optional[str] = None,
+ nonce: Optional[str] = None) -> dict:
+ """Claim an order without paying it, the way a wallet does first.
+
+ This is the only way to reach the terminal's force-delete dialog: a
+ claimed order cannot be deleted normally, and the dialog exists for
+ exactly that. The claim is a public endpoint -- no merchant
+ credential -- because it is the customer's side of the contract.
+ """
+ nonce = nonce or base64.b32encode(os.urandom(16)).decode().rstrip("=")
+ body: dict[str, Any] = {"nonce": nonce}
+ if claim_token:
+ body["token"] = claim_token
+ _, payload = self._request("POST", f"orders/{order_id}/claim", body=body)
+ return payload
+
+
+@dataclass
+class Instance:
+ """A provisioned instance plus the credentials the harness holds for it."""
+
+ merchant: Merchant
+ token: Token
+ currency: str
+ label: str = ""
+ products: list[dict] = field(default_factory=list)
+
+ def setup_uri(self, host: Optional[str] = None, style: str = "path") -> str:
+ """The `taler-pos://` URI that configures a terminal for this instance.
+
+ Two shapes reach the same place, and MainActivity parses them with
+ different code:
+
+ * `path`: taler-pos://<host>/instances/<id>#<token>
+ * `params`: taler-pos://<host>#username=<id>&password=<token>
+
+ The scheme is fixed and so is https -- the terminal rebuilds the base
+ URL itself and hard-codes the scheme -- so the host must be reachable
+ over TLS from inside the emulator.
+ """
+ parsed = urllib.parse.urlsplit(self.merchant.base)
+ host = host or parsed.netloc
+ token = self.token.value
+ if style == "path":
+ return (f"taler-pos://{host}/instances/{self.merchant.instance}"
+ f"#{urllib.parse.quote(token, safe='')}")
+ if style == "params":
+ return (f"taler-pos://{host}#username={urllib.parse.quote(self.merchant.instance)}"
+ f"&password={urllib.parse.quote(token, safe='')}")
+ raise ValueError(f"unknown setup-uri style {style!r}")
+
+
+def demo(instance: str = DEMO_INSTANCE, secret: str = DEMO_SECRET,
+ seconds: Optional[int] = None) -> Instance:
+ """The public demo backend, with a freshly minted token.
+
+ The `sandbox` instance is shared and already carries a large inventory and
+ a long order history, which is what makes it worth testing against: the
+ terminal's pagination, its stock badges and its history list never see that
+ much data on a stack the harness builds itself. Nothing here modifies
+ anybody else's data beyond adding orders and refunds of its own.
+ """
+ m = Merchant(instance=instance, secret=secret)
+ token = m.mint_token(seconds=seconds)
+ cfg = m.config()
+ return Instance(merchant=m, token=token, currency=cfg["currency"],
+ label=f"demo/{instance}")
+
+
+if __name__ == "__main__":
+ import sys
+ want = sys.argv[1] if len(sys.argv) > 1 else "info"
+ inst = demo()
+ if want == "info":
+ print(f"{inst.label}: {inst.currency}, {inst.token}")
+ print(f" backend {inst.merchant.backend_version()}")
+ print(f" pos url {inst.merchant.pos_url()}")
+ pos = inst.merchant.pos_config(inst.token.value)
+ print(f" products {len(pos.get('products', []))}"
+ f" categories {len(pos.get('categories', []))}")
+ print(f" accounts {len(inst.merchant.accounts(inst.token.value))}")
+ print(f" history {len(inst.merchant.history(inst.token.value, limit=-5))} of the last 5")
+ elif want == "uri":
+ print(inst.setup_uri())
diff --git a/pos-simulator/driver/oracles.py b/pos-simulator/driver/oracles.py
@@ -0,0 +1,500 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""What counts as a failure.
+
+An ordinary error is not a finding. A terminal pointed at a backend that is
+down is supposed to say so; a refund larger than the order is supposed to be
+refused. A finding is the terminal breaking its own contract: a crash, an ANR,
+a dialog that names no cause the cashier can act on, an exception message
+shown as if it were one, a screen that waits forever, a state on screen that
+the backend contradicts, or a payment code the customer cannot use.
+
+Two things make this different from the wallet's equivalent. There is no
+wallet-core here, so there is no error-code registry to lean on -- every
+judgement comes from the screen, the log and the backend. And the terminal is
+one half of a transaction, so the backend is an oracle in its own right: what
+the order really is, as opposed to what the terminal says it is.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from typing import Iterable, Optional
+
+from device import PKG, Device, Screen
+
+CRASH_PATTERNS = (
+ ("crash", re.compile(r"FATAL EXCEPTION")),
+ ("anr", re.compile(r"ANR in ")),
+ ("native-crash", re.compile(r"\*\*\* \*\*\* \*\*\*|signal \d+ \(SIG")),
+ # The terminal asserts its way through a configuration it believes in:
+ # `configManager.merchantConfig!!` appears in nine places across the
+ # payment, history and refund managers, and a session that ends while one
+ # of them is in flight is a KotlinNullPointerException rather than an
+ # error message.
+ ("kotlin-npe", re.compile(r"KotlinNullPointerException|"
+ r"NullPointerException.*merchantConfig|"
+ r"lateinit property .* has not been initialized")),
+ ("strict-mode", re.compile(r"StrictMode policy violation")),
+ ("main-thread-io", re.compile(r"NetworkOnMainThreadException")),
+)
+
+# Dialog and screen text that no cashier can act on. These are the terminal's
+# own words, so matching them is exact rather than heuristic.
+USELESS_MESSAGES = (
+ ("catch-all-config-error", re.compile(r"^Error: Invalid configuration\.?$")),
+ ("catch-all-malformed", re.compile(r"^Error: The configuration JSON is malformed\.?$")),
+)
+
+# Text that should never reach a user.
+LEAK_PATTERNS = (
+ ("placeholder-leak", re.compile(r"%[0-9]+\$[sd]|%s(?![a-zA-Z])|%d(?![a-zA-Z])")),
+ ("null-leak", re.compile(r"(?<![A-Za-z])(null|undefined|NaN|Infinity)(?![A-Za-z])")),
+ ("exception-leak", re.compile(r"java\.lang\.|java\.net\.|javax\.net\.|"
+ r"kotlin\.[A-Za-z]*Exception|"
+ r"[A-Za-z]{3,}Exception(:|\b)|"
+ r"io\.ktor\.|UnknownHostException|"
+ r"SSLHandshakeException|ConnectException")),
+ # A word stuck to a number, like "KUDOS1.00": a currency whose symbol is a
+ # word, formatted as if it were a sign.
+ ("glued-currency", re.compile(r"(?:^|[\s:])[A-Z]{3,}\d+[.,]\d\d(?:$|\s)")),
+ ("raw-resource-name", re.compile(r"\b(?:config|payment|refund|history|order|"
+ r"settings|error|toast|menu)_[a-z_]{3,}\b")),
+)
+# Labels that legitimately contain such words. The About block prints a URL
+# and a version; a product description is the merchant's own text and may
+# contain anything, including the word "null" -- but only the sandbox
+# instance's inventory does, which is why this is narrow.
+LEAK_EXEMPT = re.compile(
+ r"(?i)^https?://|^payto://|^taler(\+http)?://|^taler-pos://"
+ r"|^[0-9a-f-]{20,}$|^\d{4}\.\d{3}-[A-Z0-9]+$"
+)
+
+# Kinds that describe the terminal behaving reasonably (refusing bad input,
+# waiting for a counterparty) rather than a defect. They are still recorded:
+# whether a refusal was right depends on what the scenario was trying to do,
+# and the write-up needs the evidence either way.
+# "empty-hierarchy" is here because an empty dump is almost always
+# `uiautomator` losing a race, not a screen with nothing on it: a real one
+# shows up as "blank-screen", which has nodes to count. Episode.observe
+# retries the dump, so one that is still empty is worth keeping -- but not
+# worth calling a defect.
+INFORMATIONAL = {"error-dialog", "harness-crash", "slow-screen",
+ "logged-backend-error", "empty-hierarchy"}
+
+
+@dataclass(frozen=True)
+class Finding:
+ kind: str
+ detail: str
+ evidence: str = ""
+
+ @property
+ def fingerprint(self) -> str:
+ """Dedup key: the same bug found twice should collapse to one entry."""
+ norm = re.sub(r"\b\d{4}\.\d{3}-[A-Z0-9]+\b", "<ORDER>", self.detail)
+ norm = re.sub(r"[0-9A-Z]{20,}", "<ID>", norm)
+ norm = re.sub(r"\b\d+\b", "#", norm)
+ norm = re.sub(r"0x[0-9a-f]+", "<ADDR>", norm)
+ return hashlib.sha256(f"{self.kind}|{norm}".encode()).hexdigest()[:16]
+
+ def __str__(self) -> str:
+ return f"[{self.kind}] {self.detail}"
+
+
+def from_logcat(log: str, pkg: str = PKG) -> list[Finding]:
+ """Crashes, ANRs and the exceptions the terminal swallows.
+
+ A crash is only the app's when the trace says so: `uiautomator dump` dies
+ with "UiAutomationService ... already registered!" whenever two dumps
+ overlap, and that is the driver's problem.
+ """
+ out: list[Finding] = []
+ lines = log.splitlines()
+ for kind, pattern in CRASH_PATTERNS:
+ for i, line in enumerate(lines):
+ if not pattern.search(line):
+ continue
+ context = "\n".join(lines[i:i + 14])
+ if kind in ("crash", "native-crash", "anr") and pkg not in context:
+ out.append(Finding("harness-crash",
+ f"not the app: {line.strip()[:200]}", context))
+ continue
+ out.append(Finding(kind, line.strip()[:400], context))
+ return out
+
+
+# The terminal logs every backend failure and then decides what, if anything,
+# to show. An exception logged while nothing appeared on screen is the shape
+# of a swallowed error.
+SWALLOWED = re.compile(
+ r"(?:ConfigManager|ConfigFragment|PaymentManager|HistoryManager|"
+ r"RefundManager|OrderManager)\s*:.*"
+ r"(Error|Failed|failed|Exception)")
+
+
+def swallowed_errors(log: str) -> list[Finding]:
+ """Backend failures the terminal logged and did not surface.
+
+ Recorded as information on their own; `silent_failure` is what turns one
+ into a finding, by checking that the screen did not change either.
+ """
+ out = []
+ for line in log.splitlines():
+ if SWALLOWED.search(line):
+ out.append(Finding("logged-backend-error", line.strip()[:300], line))
+ return out
+
+
+def dialog_quality(screen: Screen) -> list[Finding]:
+ """Error dialogs judged on whether they say anything.
+
+ The terminal has one dialog for every failure, and what goes in it is
+ decided by a small number of `when` branches -- so the interesting
+ question is not "was there an error" but "did the message name a cause".
+ Three shapes are defects: a catch-all that covers several unrelated
+ failures, a dialog whose message is empty, and one that quotes a stack
+ trace or a Ktor exception at the cashier.
+ """
+ texts = [t for t in screen.texts() if t]
+ if not texts:
+ return []
+ has_ok = any(re.fullmatch(r"(?i)ok", t) for t in texts)
+ if not has_ok:
+ return []
+ body = " | ".join(texts)
+ out: list[Finding] = []
+ for kind, pattern in USELESS_MESSAGES:
+ for text in texts:
+ if pattern.match(text.strip()):
+ out.append(Finding(
+ kind,
+ f"the only thing the dialog says is {text.strip()!r}, which "
+ f"covers several unrelated failures",
+ body[:800]))
+ # A dialog whose title is the app's name and whose message is the app's
+ # name too has lost its text somewhere: the dialog falls back to the app
+ # name as a title when it has no detail, so both being the app name means
+ # the message never arrived.
+ app_titles = [t for t in texts if t.strip() == "Taler POS"]
+ if len(app_titles) >= 2:
+ out.append(Finding("empty-dialog",
+ "an error dialog with the app name and nothing else",
+ body[:800]))
+ return out
+
+
+def screen_leaks(screen: Screen) -> list[Finding]:
+ """Rendering that is obviously wrong, whatever the screen is for.
+
+ An unsubstituted format string, a stray "null", a resource name shown as a
+ label, an exception class name or a currency word glued to a number are
+ defects no matter which flow produced them, and they are cheap to check on
+ every dump.
+ """
+ out: list[Finding] = []
+ for text in screen.texts():
+ label = text.strip()
+ if not label or LEAK_EXEMPT.search(label):
+ continue
+ for kind, pattern in LEAK_PATTERNS:
+ if pattern.search(label):
+ out.append(Finding(kind, f"{label[:160]!r} on {screen.activity}",
+ " | ".join(screen.texts())[:800]))
+ break
+ return out
+
+
+def blank_screen(screen: Screen) -> list[Finding]:
+ """A screen with nothing to read and nothing to tap is a dead end."""
+ if not screen.nodes:
+ return [Finding("empty-hierarchy", "no view hierarchy returned")]
+ if not screen.labelled() and not screen.tappable():
+ return [Finding("blank-screen",
+ f"{len(screen.nodes)} nodes, none labelled or tappable")]
+ return []
+
+
+def unnamed_controls(screen: Screen) -> list[Finding]:
+ """Controls a screen reader cannot announce.
+
+ Only reported for the terminal's own screens, and only for controls that
+ have no label anywhere inside them: a tile whose text is a child is read
+ correctly by TalkBack, an icon button with no contentDescription is not.
+ """
+ if not screen.activity.startswith(PKG):
+ return []
+ anonymous = screen.unnamed_clickables()
+ if not anonymous:
+ return []
+ return [Finding(
+ "unnamed-control",
+ f"{len(anonymous)} clickable control(s) with no accessible name on "
+ f"{screen.activity}: {[n.center for n in anonymous[:6]]}",
+ "\n".join(str(n) for n in anonymous[:12]),
+ )]
+
+
+# A spinner that is still spinning after this long is not loading any more.
+STUCK_AFTER = 75.0
+
+
+def stuck_progress(dev: Device, screen: Screen, since: float,
+ now: float) -> list[Finding]:
+ """A screen that is still saying "please wait" long after it should be.
+
+ "Fetching configuration..." is the one the terminal can genuinely get
+ stuck on: `ConfigFetcherFragment` shows a spinner and waits for a result
+ that a dropped connection never delivers.
+ """
+ if not screen.find(r"Fetching configuration|Updating order history"):
+ return []
+ waited = now - since
+ if waited < STUCK_AFTER:
+ return []
+ return [Finding(
+ "stuck-progress",
+ f"still showing a progress message after {waited:.0f}s on "
+ f"{screen.activity}",
+ " | ".join(screen.texts())[:500],
+ )]
+
+
+LOGCAT_STAMP = re.compile(r"^(\d\d)-(\d\d) (\d\d):(\d\d):(\d\d)\.(\d+)")
+TAIL_ERROR = re.compile(
+ r"(?:E|W)/?\s*(?:ConfigManager|PaymentManager|HistoryManager|RefundManager|"
+ r"ConfigFragment|OrderManager)"
+ r"|Error retrieving merchant config"
+ r"|Error (?:fetching|processing|handling)"
+ r"|FATAL EXCEPTION")
+
+
+def recent_lines(log: str, seconds: float = 6.0) -> list[str]:
+ """Log lines written within the last few seconds.
+
+ logcat has no "since my last read" option, so the timestamps are compared
+ against the wall clock. The device and the host share it closely enough
+ for a window this wide.
+ """
+ import time
+ now = time.localtime()
+ cutoff = time.time() - seconds
+ out = []
+ for line in log.splitlines():
+ m = LOGCAT_STAMP.match(line)
+ if not m:
+ continue
+ month, day, hour, minute, second = (int(m.group(i)) for i in range(1, 6))
+ stamp = time.mktime((now.tm_year, month, day, hour, minute, second,
+ 0, 0, now.tm_isdst))
+ if stamp >= cutoff:
+ out.append(line)
+ return out
+
+
+# Labels whose tap is *meant* to change nothing on screen, or which are not
+# controls at all. Without this the oracle fires on every price in the order
+# grid during a random walk, because the terminal's managers log a backend
+# error every few seconds against a busy demo instance and the two get
+# correlated by nothing more than happening at the same time.
+NOT_AN_ACTION = re.compile(
+ r"^\s*(?:[\u20ac$\u00a3\u00a5\u20b9\u30af]\s?)?\d+[.,]\d+\s*$" # a price
+ r"|^(?:out of stock|unavailable|wrong currency|unpaid|paid|refunded"
+ r"|payment pending|payment claimed|refund pending)$"
+ r"|^(?:copy|share)$" # clipboard and share-sheet
+ r"|^(?:ref|receipt)\s*#", # an order reference
+ re.I,
+)
+
+
+def silent_failure(dev: Device, label: str, before: str, after: str,
+ lines: int = 300) -> list[Finding]:
+ """A primary action that did nothing, while the log says it failed.
+
+ The terminal's managers log every backend error and then decide what to
+ show; several branches decide to show nothing. Comparing the screen
+ before and after a tap catches the whole class without having to know
+ which branch it was.
+ """
+ if before != after:
+ return []
+ if NOT_AN_ACTION.search(label.strip()):
+ return []
+ activity = dev.dump().activity
+ if activity and not activity.startswith(PKG):
+ return []
+ tail = dev.adb("logcat", "-d", "-t", str(lines), check=False)
+ fresh = "\n".join(recent_lines(tail))
+ errors = [ln for ln in fresh.splitlines() if TAIL_ERROR.search(ln)]
+ if not errors:
+ return []
+ return [Finding(
+ "silent-failure",
+ f"tapping {label!r} changed nothing on screen while the log reported "
+ f"a backend error",
+ "\n".join(errors[-8:])[:2000],
+ )]
+
+
+# -- the backend as an oracle --------------------------------------------
+
+
+def payment_code_usable(screen: Screen, offered: Optional[str],
+ expected: Optional[str]) -> list[Finding]:
+ """The payment screen must offer a code the customer can actually use.
+
+ Three ways it can fail, all of them silent on screen: the terminal shows
+ the "scan this" prompt while having no URI at all; it offers a URI for a
+ different order than the one the backend created; or it offers a
+ `taler+http://` URI, which a wallet with its security defaults will not
+ open -- the terminal has a dialog for exactly that case, so reaching the
+ payment screen without it is a defect rather than a policy choice.
+ """
+ if not screen.find(r"scan QR Code"):
+ return []
+ out: list[Finding] = []
+ if offered is None:
+ out.append(Finding(
+ "payment-without-code",
+ "the payment screen asks the customer to scan a code while the "
+ "terminal is publishing none",
+ " | ".join(screen.texts())[:500]))
+ return out
+ if offered.lower().startswith("taler+http://"):
+ out.append(Finding(
+ "insecure-payment-code",
+ f"the terminal offered an insecure pay URI without asking: "
+ f"{offered[:120]}",
+ offered))
+ if expected and offered.split("?")[0] != expected.split("?")[0]:
+ out.append(Finding(
+ "payment-code-mismatch",
+ f"the terminal offers {offered[:90]} while the backend's order is "
+ f"{expected[:90]}",
+ f"offered: {offered}\nbackend: {expected}"))
+ return out
+
+
+PAID_MARKS = re.compile(r"(?i)^(Paid|Refunded|Refund pending)$")
+UNPAID_MARKS = re.compile(r"(?i)^(Unpaid|Payment pending|Payment claimed)$")
+
+
+def history_matches_backend(screen: Screen, backend_orders: list[dict]
+ ) -> list[Finding]:
+ """What the history list says about an order, against what the order is.
+
+ Only orders the list actually shows are judged, and only the paid/unpaid
+ distinction -- that is the one a cashier acts on, and the one the terminal
+ derives rather than reads.
+ """
+ by_id = {o.get("order_id"): o for o in backend_orders}
+ out: list[Finding] = []
+ labels = [n for n in screen.nodes if n.label.strip()]
+ for node in labels:
+ m = re.match(r"(?i)^(?:Ref|Receipt)\s*#\s*(\S+)", node.label.strip())
+ if not m:
+ continue
+ order = by_id.get(m.group(1))
+ if order is None:
+ continue
+ # The status chip sits on the same row as the reference.
+ row = [n.label.strip() for n in labels
+ if abs(n.center[1] - node.center[1]) < 70]
+ shown_paid = any(PAID_MARKS.match(t) for t in row)
+ shown_unpaid = any(UNPAID_MARKS.match(t) for t in row)
+ if not (shown_paid or shown_unpaid):
+ continue
+ really_paid = bool(order.get("paid"))
+ if really_paid and shown_unpaid and not shown_paid:
+ out.append(Finding(
+ "history-state-wrong",
+ f"order {m.group(1)} is paid at the backend and listed as "
+ f"{[t for t in row if UNPAID_MARKS.match(t)][0]!r}",
+ f"row: {row}\nbackend: {order}"))
+ if not really_paid and shown_paid and not shown_unpaid:
+ out.append(Finding(
+ "history-state-wrong",
+ f"order {m.group(1)} is unpaid at the backend and listed as "
+ f"{[t for t in row if PAID_MARKS.match(t)][0]!r}",
+ f"row: {row}\nbackend: {order}"))
+ return out
+
+
+def orphaned_orders(before: list[dict], after: list[dict],
+ allowed: Iterable[str] = ()) -> list[Finding]:
+ """Unpaid orders the terminal created and left behind.
+
+ Cancelling a payment is supposed to delete the order, and the terminal
+ says so in its log ("Deleting cancelled and unpaid order ..."); an unpaid
+ order that outlives the scenario means that delete did not happen, and the
+ merchant's order list fills up with rows nobody can explain.
+ """
+ allowed = set(allowed)
+ known = {o.get("order_id") for o in before}
+ leftover = [o for o in after
+ if o.get("order_id") not in known
+ and not o.get("paid")
+ and o.get("order_id") not in allowed]
+ if not leftover:
+ return []
+ return [Finding(
+ "orphaned-order",
+ f"{len(leftover)} unpaid order(s) left at the backend after the "
+ f"payment was cancelled: {[o.get('order_id') for o in leftover[:5]]}",
+ str(leftover[:5])[:1200],
+ )]
+
+
+@dataclass
+class Session:
+ """Collects findings over an episode, deduplicated."""
+
+ findings: dict[str, Finding] = field(default_factory=dict)
+
+ def add(self, found: Iterable[Finding]) -> list[Finding]:
+ fresh = []
+ for f in found:
+ if f.fingerprint not in self.findings:
+ self.findings[f.fingerprint] = f
+ fresh.append(f)
+ return fresh
+
+ def check(self, dev: Device, screen: Optional[Screen] = None,
+ log: Optional[str] = None,
+ progress_since: Optional[float] = None) -> list[Finding]:
+ import time
+ found: list[Finding] = []
+ # Screen oracles only apply to the terminal's own screens. A random
+ # walk leaves the app now and then -- the tutorial link opens a browser
+ # -- and a browser's suggestions are full of the words these oracles
+ # look for.
+ if screen is not None and screen.activity \
+ and not screen.activity.startswith(PKG):
+ screen = None
+ if screen is not None:
+ found += blank_screen(screen)
+ found += screen_leaks(screen)
+ found += dialog_quality(screen)
+ found += unnamed_controls(screen)
+ if progress_since is not None:
+ found += stuck_progress(dev, screen, progress_since, time.monotonic())
+ if log is not None:
+ found += from_logcat(log)
+ return self.add(found)
+
+ def serious(self) -> list[Finding]:
+ """Everything except what only describes the terminal refusing or waiting."""
+ return [f for f in self.findings.values() if f.kind not in INFORMATIONAL]
diff --git a/pos-simulator/driver/pos.py b/pos-simulator/driver/pos.py
@@ -0,0 +1,1573 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""The terminal as a set of things one can ask it to do.
+
+`device.py` knows about taps and labels; this knows about the point-of-sale
+app: how it is provisioned, how its four screens are reached, how an order is
+built and billed, and how long each of those legitimately takes. Scenarios are
+written against this, so that a change to the app's wording costs one edit here
+rather than one per scenario.
+
+Every label is a regular expression matched against the English strings in
+`merchant-terminal/src/main/res/values/strings.xml`, which is the source of
+truth for translations and therefore the only locale a scenario may assume.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+from device import Device, Node, Screen
+
+# Screens, by something only that screen shows. The terminal has no titles on
+# most screens -- the Compose shell draws one top bar for the order screen, one
+# for history and a bare one for everything else -- so these key off content.
+MARK_CONFIG = r"Merchant portal URL|Manual config|QR config"
+MARK_FETCHING = r"Fetching configuration"
+MARK_AMOUNT = r"Create order \(charge amount\)|Charge"
+MARK_ORDER = r"Bill|Everything|Add custom product"
+# The complete-order button is "Bill" with an empty order and "Bill <amount>"
+# with anything in it, so a pattern with the space baked in matches only half
+# the time -- which read as a screen with no way to bill. Written once here
+# because it drifted the moment it was written twice.
+BILL_BUTTON = r"^Bill( .*)?$|^Complete order$"
+MARK_HISTORY = r"Refresh history|Payment history"
+MARK_SETTINGS = r"App settings|Login settings|Modify login settings"
+# The payment screen reached from a checkout words its instruction
+# differently ("Scan the QR code with your mobile wallet.") and offers "Back
+# to payment options" where a plain order offers "Cancel payment", so a marker
+# built from the old wording waited two minutes on a screen that was already
+# there.
+MARK_PAYMENT = (r"scan QR Code|Scan the QR code|Cancel payment"
+ r"|confirm payment|Back to payment options|^Pay with$")
+# Anchored, and not negotiable: `Screen.find` matches case-insensitively, and
+# the terminal's failure string is "Error: No payment received" -- which
+# contains this one. Unanchored, a scenario asking "did the payment NOT
+# succeed?" was answered "it did" by the very error that says it did not.
+MARK_SUCCESS = r"^Payment received$"
+# Master renamed the refund form's submit button: it was "Approve refund" and
+# is now "Refund Taler", beside a "Refund method" chooser that lets the
+# cashier pick which payment to give back. Both wordings are matched so the
+# harness can be run against either build.
+MARK_REFUND_FORM = r"Approve refund|^Refund Taler$|Refund method"
+APPROVE_REFUND = r"Approve refund|^Refund Taler$"
+MARK_REFUND_URI = r"offer refund"
+# The mixed-payment checkout, which stands between the order and the payment
+# screen as soon as a second payment option is turned on. "Order total" is
+# the tablet heading and "To pay:" the compact one, so both are listed.
+MARK_CHECKOUT = (r"Choose payment method|Order total|To pay:|Total:"
+ r"|Payments so far|Charge with Taler"
+ r"|Charge remaining with Taler|Complete payment")
+MARK_CHECKOUT_PAD = r"Record .* cash|Charge .* on card"
+# The Settings screen quotes the payment-options description in its own card,
+# so "Taler is always available" matches both screens and a reader that waited
+# for it never left Settings. The per-option descriptions are only on the
+# options screen itself.
+MARK_PAYMENT_OPTIONS = r"^Open .* settings$"
+
+# The error dialog, which is one AlertDialog reused for everything: a title, a
+# message and an OK button. Its message is the only place several failures say
+# anything at all, so it is read rather than just dismissed.
+ERROR_TITLES = (
+ r"Taler POS", r"Error: ", r"No payment received", r"Could not create order",
+ r"Not enough inventory", r"Could not delete order", r"Invalid username",
+ r"Could not connect", r"configuration JSON is malformed",
+ r"Invalid configuration", r"Enter an amount", r"Unsupported currency",
+ r"Refund state is no longer available",
+)
+
+
+class PosError(RuntimeError):
+ """The harness could not get the terminal to where the scenario needs it."""
+
+
+@dataclass
+class Dialog:
+ """A modal the terminal is showing, flattened to what a tester reads."""
+
+ title: str
+ message: str
+ buttons: list[str]
+
+ def __str__(self) -> str:
+ return f"{self.title!r}: {self.message!r} {self.buttons}"
+
+
+class Pos:
+ """One terminal, driven through its UI."""
+
+ def __init__(self, dev: Device):
+ self.dev = dev
+ # Anything that wipes the app takes the coverage collected so far with
+ # it; the episode plugs in a dump here.
+ self.before_wipe: Optional[Callable[[], None]] = None
+
+ # -- lifecycle --------------------------------------------------------
+
+ def fresh_start(self, grant_camera: bool = True) -> None:
+ """An unconfigured terminal on a settled device.
+
+ A wipe is the only reliable way back to the login screen: "Log out"
+ leaves the saved language and the initial-order-screen preference
+ behind, which is right for a user and wrong for a scenario that wants
+ to know what a first run looks like.
+ """
+ if self.before_wipe:
+ self.before_wipe()
+ self.dev.stop()
+ self.dev.clear_data()
+ # Every scenario starts from a known orientation. A scenario that
+ # turns the device and then fails would otherwise leave the worker in
+ # portrait, and the next twenty scenarios would quietly test the other
+ # half of five layouts while reporting the names of this one.
+ want_portrait = os.environ.get("POS_PORTRAIT", "0") != "0"
+ if self.dev.is_portrait() != want_portrait:
+ # Noted and carried on with rather than raised: a device that
+ # will not turn is worth knowing about, but failing here turns
+ # every scenario after a rotating one into a harness error and
+ # hides whatever they would have found.
+ try:
+ self.dev.rotate(portrait=want_portrait)
+ except RuntimeError as exc:
+ print(f" !! could not restore orientation: {exc}")
+ if grant_camera:
+ # pm clear revokes it, and the QR config screen asks for it the
+ # moment that tab is selected -- a permission dialog on top of the
+ # screen under test is not what any scenario is looking at.
+ self.dev.grant_camera()
+ self.dev.launch()
+ self.wait_for_config_screen()
+
+ def relaunch(self) -> None:
+ self.dev.stop()
+ self.dev.launch()
+ time.sleep(2)
+
+ def process_death(self) -> None:
+ """Kill the process the way the system would, then come back."""
+ self.dev.kill()
+ time.sleep(1.5)
+ self.dev.launch()
+ time.sleep(2)
+
+ # -- provisioning -----------------------------------------------------
+
+ def wait_for_config_screen(self, timeout: int = 90) -> Screen:
+ """Wait for the login form, fields and all.
+
+ The tab row ("Manual config", "QR config") and the screen title are
+ laid out before the fields are, and all three match MARK_CONFIG -- so
+ a wait on the marker alone came back with a form that had nothing to
+ type into, and every scenario that provisions by form failed at the
+ first field with "no text field on screen at all". What a scenario
+ is actually waiting for is somewhere to type.
+ """
+ screen = self.dev.wait_for(MARK_CONFIG, timeout=timeout)
+ deadline = time.monotonic() + 20
+ while time.monotonic() < deadline:
+ if screen.editable() or screen.find(r"Scan the QR|Fetching"):
+ return screen
+ time.sleep(1.0)
+ screen = self._stable_dump()
+ return screen
+
+ def provision_by_uri(self, uri: str, timeout: int = 120,
+ expect_success: bool = True) -> Screen:
+ """Configure the terminal with a `taler-pos://` setup URI.
+
+ This is how a merchant provisions a terminal in practice: the back
+ office shows a QR code, the terminal scans it. Delivering the same
+ string as a deep link exercises every line of the parse and the fetch
+ that follows, and leaves the camera out of it -- `provision_by_qr`
+ covers the camera.
+ """
+ self.dev.setup_uri(uri)
+ if not expect_success:
+ time.sleep(4)
+ return self.dev.dump()
+ return self.wait_for_order_entry(timeout=timeout)
+
+ def _reach_next_field(self, label: str, screen: Screen,
+ tries: int = 3) -> Screen:
+ """Bring the next field of a form into view, the way a cashier does.
+
+ On a screen too short to hold the form under the keyboard -- a phone
+ in landscape is 411 dp and the keyboard takes two thirds of it -- the
+ form shows one field at a time and the others are not laid out at all.
+ Neither a scroll gesture nor a dump can reach them: there is nothing
+ to swipe, because the list has one item in it.
+
+ What does reach them is the keyboard's own Next key. The form wires
+ every field's `ImeAction.Next` to `focusManager.moveFocus(Down)` and
+ the list scrolls whatever takes focus into view, so moving focus is
+ both how a cashier gets there and how the next field comes to exist.
+ """
+ for _ in range(tries):
+ if screen.find(label) or any(
+ re.search(label, n.label, re.I) for n in screen.labelled()):
+ return screen
+ self.dev.key("KEYCODE_TAB")
+ time.sleep(1.2)
+ screen = self._stable_dump()
+ return screen
+
+ def _wait_for_fields(self, count: int = 1, timeout: int = 25) -> Screen:
+ """A dump that actually has editable fields in it."""
+ deadline = time.monotonic() + timeout
+ screen = self._stable_dump()
+ while time.monotonic() < deadline:
+ if len(screen.editable()) >= count:
+ return screen
+ time.sleep(1.0)
+ screen = self._stable_dump()
+ return screen
+
+ def provision_by_form(self, host: str, instance: str, token: str,
+ save_password: bool = True, timeout: int = 120,
+ expect_success: bool = True) -> Screen:
+ """Type the merchant URL, instance and password into the login form.
+
+ The form is what a human uses, and it is also the only path that goes
+ through `POST /private/token` from the device -- so it is the only one
+ that can hit the two-factor challenge the backend may ask for.
+
+ Note what it does *not* do: the duration is hard-coded to "forever".
+ An expiring session cannot be set up here; it has to be minted outside
+ and delivered as a setup URI.
+ """
+ screen = self.wait_for_config_screen()
+ if screen.find(r"^Manual config$"):
+ self.tap_button(r"^Manual config$")
+ time.sleep(1)
+ # Switching tabs recomposes the form, and the tab row is drawn
+ # before the fields are. A plain dump here described a screen
+ # with nothing to type into, and every form-provisioned scenario
+ # died at the first field.
+ screen = self._wait_for_fields()
+
+ self.fill_field(r"Merchant portal URL", host, screen)
+ # A stable dump, not a plain one: filling a field raises the keyboard
+ # and the phone layout scrolls under it, so a dump taken while that is
+ # still happening describes a form that has already moved.
+ screen = self._stable_dump()
+ # Two fields are labelled "Password": the form's and, on some
+ # backends, a token-validity row. The form's is the editable one that
+ # follows Username, which is what fill_field resolves.
+ for label, value in ((r"^Username$", instance), (r"^Password$", token)):
+ screen = self._reach_next_field(label, screen)
+ self.fill_field(label, value, screen)
+ screen = self._stable_dump()
+
+ screen = self.dev.dump()
+ remember = screen.find(r"Remember password")
+ if remember is not None:
+ node = screen.tap_target(remember)
+ if node.checkable and node.checked != save_password:
+ self.dev.tap_node(remember, screen)
+ time.sleep(0.5)
+
+ self.tap_button(r"^Connect$")
+ if not expect_success:
+ time.sleep(6)
+ return self.dev.dump()
+ return self.wait_for_order_entry(timeout=timeout)
+
+ def fill_demo_credentials(self) -> Screen:
+ """Use the terminal's own "Fill demo credentials" button.
+
+ It prefills backend.demo.taler.net with the sandbox instance, which is
+ the first thing a reviewer does -- and the only path where the
+ credential never passes through the harness, so a defect in the
+ prefill itself is visible.
+ """
+ screen = self.wait_for_config_screen()
+ if not screen.find(r"Fill demo credentials"):
+ # The help card is collapsed until "No account?" is tapped; it was
+ # called "No instance?" before master renamed it.
+ self.tap_button(r"No account\?|No instance\?")
+ time.sleep(1)
+ screen = self.dev.wait_for(r"Fill demo credentials", timeout=20)
+ self.tap_button(r"Fill demo credentials")
+ time.sleep(1.5)
+ return self.dev.dump()
+
+ def provision_by_qr(self, timeout: int = 180) -> Screen:
+ """Switch to the QR tab and wait for the poster on the wall to be read.
+
+ The emulator's virtual scene can only be given its poster at launch, so
+ the image has to already be hanging there; `emu/emu.sh boot <w> <png>`
+ is what puts it up. This only selects the tab and waits.
+
+ It deliberately does not confirm that the QR screen appeared.
+ `uiautomator dump` returns the *previous* layout while a camera
+ preview is on screen -- the screenshot shows the live preview and the
+ "Scan the QR code" hint while the hierarchy still describes the login
+ form, for as long as the preview is up. So the tab selection is
+ verified by screenshot during development and by its effect here:
+ either the terminal provisions itself from what it saw, or it does
+ not.
+ """
+ screen = self.wait_for_config_screen()
+ node = screen.find(r"^QR config$")
+ if node is None:
+ raise PosError(f"no QR tab on the login screen: {screen.texts()}")
+ self.dev.tap_node(node, screen)
+ time.sleep(2)
+ return self.wait_for_order_entry(timeout=timeout)
+
+ # -- navigation -------------------------------------------------------
+
+ def open_drawer(self, timeout: int = 20) -> Screen:
+ """Open the navigation drawer through the hamburger button.
+
+ The button carries no contentDescription, so it cannot be found by
+ label; it is the leftmost small unlabelled clickable in the top bar,
+ which is stable across all three top-bar variants the shell draws.
+
+ A dump taken while the UI is settling comes back empty, and an empty
+ dump here reads as "this screen has no drawer button" -- which is the
+ same thing a locked drawer looks like. So the dump is retried before
+ any conclusion is drawn from it.
+ """
+ screen = self._stable_dump()
+ if screen.find(r"^History$") and screen.find(r"^Settings$"):
+ return screen # already open
+ _, height = self.dev.size()
+ candidates = [n for n in screen.nodes
+ if n.clickable and n.enabled and n.area > 0
+ and n.bounds[1] < height // 4
+ and not n.label.strip()
+ and (n.bounds[2] - n.bounds[0]) < 220]
+ if not candidates:
+ raise PosError(f"no drawer button in the top bar; screen: {screen.texts()}")
+ self.dev.tap_node(min(candidates, key=lambda n: n.bounds[0]), screen)
+ return self.dev.wait_for(r"^Settings$", timeout=timeout)
+
+ def _leave_subscreen(self, screen: Screen, tries: int = 4) -> Screen:
+ """Back out of a screen that has no drawer, so the drawer is reachable.
+
+ The payment-options screen, an option's own settings and the order
+ details page are routes of their own: the top bar carries a Back arrow
+ where the drawer button would be. Both are an unlabelled clickable
+ node in the top-left corner, so `open_drawer` cannot tell them apart
+ and happily pressed Back -- which left the terminal one screen up and
+ the navigation one tap behind, and the failure landed on whatever was
+ tapped next. There is one honest signal: the drawer button's own
+ content description.
+ """
+ for _ in range(tries):
+ if screen.find(r"^Open navigation menu$") or not screen.nodes:
+ return screen
+ self.dev.back()
+ time.sleep(1.0)
+ screen = self._stable_dump()
+ return screen
+
+ def _stable_dump(self, tries: int = 4) -> Screen:
+ """A dump with something in it.
+
+ `uiautomator dump` answers with an empty hierarchy often enough to
+ matter -- during a navigation animation, while a dialog is being
+ laid out -- and every caller that reasons about which nodes are
+ present needs to tell "nothing there" from "nothing read yet".
+ """
+ screen = self.dev.dump()
+ for _ in range(tries - 1):
+ if screen.nodes:
+ return screen
+ time.sleep(1.0)
+ screen = self.dev.dump()
+ return screen
+
+ def goto(self, destination: str, timeout: int = 60) -> Screen:
+ """Open one of the four drawer destinations and wait for it.
+
+ `destination` is one of "amount", "inventory", "history", "settings".
+ A destination the terminal is already showing is not navigated to
+ again: re-entering a route rebuilds its fragment, which throws away
+ whatever the scenario had just put on screen.
+ """
+ rows = {
+ "amount": (r"^Order by amount$", MARK_AMOUNT),
+ "inventory": (r"^Order by inventory$", MARK_ORDER),
+ "history": (r"^History$", MARK_HISTORY),
+ "settings": (r"^Settings$", MARK_SETTINGS),
+ }
+ if destination not in rows:
+ raise ValueError(f"unknown destination {destination!r}")
+ label, mark = rows[destination]
+ current = self._stable_dump()
+ # A modal blocks the drawer, and a scenario that has already recorded
+ # the dialog should still be able to carry on -- a backend hiccup in
+ # the middle of a scenario should not cost the rest of it.
+ if self.read_dialog(current) is not None:
+ self.dismiss_dialog()
+ current = self._stable_dump()
+ if current.find(mark) and not current.find(r"^Log out$|^History$"):
+ return current
+ if current.find(mark) and destination in ("amount", "inventory"):
+ return current
+ current = self._leave_subscreen(current)
+ # The drawer slides in, and a tap that lands while it is still moving
+ # selects nothing: the drawer stays open and the next wait times out
+ # on a screen that is showing four navigation rows. That reads like
+ # the destination does not exist, so it is retried rather than
+ # reported.
+ last: Optional[Exception] = None
+ for attempt in range(3):
+ self.open_drawer()
+ time.sleep(0.6)
+ try:
+ self.tap_button(label)
+ except PosError as exc:
+ last = exc
+ continue
+ try:
+ return self.dev.wait_for(mark, timeout=timeout // (1 + attempt))
+ except TimeoutError as exc:
+ last = exc
+ screen = self._stable_dump()
+ if not screen.find(r"^Close navigation menu$"):
+ raise
+ assert last is not None
+ raise last
+
+ def wait_for_order_entry(self, timeout: int = 120) -> Screen:
+ """Wait for whichever order screen the terminal starts on.
+
+ Which one it is depends on a saved preference, so a scenario that
+ wants a particular one asks for it with `goto`; this only waits for
+ provisioning to have finished. A configuration error arrives as a
+ dialog rather than as a screen, so it is turned into an exception that
+ names the message -- otherwise the timeout says nothing.
+ """
+ deadline = time.monotonic() + timeout
+ while time.monotonic() < deadline:
+ screen = self.dev.dump()
+ if screen.find(MARK_AMOUNT) or screen.find(MARK_ORDER):
+ return screen
+ dialog = self.read_dialog(screen)
+ if dialog is not None:
+ raise PosError(f"provisioning failed with a dialog: {dialog}")
+ time.sleep(1.5)
+ raise PosError(f"no order screen within {timeout}s; "
+ f"screen showed: {self.dev.dump().texts()}")
+
+ # -- widgets ----------------------------------------------------------
+
+ def tap_button(self, pattern: str, timeout: int = 30) -> Screen:
+ """Tap the control that carries a label, not the label's screen title.
+
+ The terminal reuses strings between a heading and the button below it
+ -- "Refund" is a history row's action and the refund screen's own
+ wording, "Settings" is a drawer row and a section heading -- so a plain
+ label search lands on text that cannot be tapped. The lowest matching
+ node that is itself clickable, or sits inside something clickable, is
+ the control.
+ """
+ screen = self._wait_or_scroll(pattern, timeout)
+ # The IME does not resize this app's screens, so a button the
+ # hierarchy still reports at its layout position may be underneath the
+ # keyboard; a tap there lands on a key and the scenario sees a control
+ # that "does nothing". Putting the keyboard away first removes the
+ # whole class -- but it is done with Back, and Back is also what
+ # dismisses a Compose AlertDialog. Where the IME had already gone, or
+ # where it never covered the control, that Back closed the dialog
+ # instead and the button "vanished before the tap": the custom-product
+ # dialog's Add and the two-factor dialog's OK, both of which a dialog
+ # window draws above the keyboard anyway.
+ #
+ # So the keyboard is only put away when the control is actually behind
+ # it, which the dump itself says: with the IME up the root bounds stop
+ # where the keyboard starts.
+ if self.dev.keyboard_shown() and not self._within_window(pattern, screen):
+ self.dev.hide_keyboard()
+ time.sleep(0.5)
+ screen = self._wait_or_scroll(pattern, max(timeout, 10))
+ screen = self._scroll_into_view(pattern, screen)
+ rx = re.compile(pattern, re.I)
+ matches = [n for n in screen.nodes if n.label and rx.search(n.label)]
+ if not matches:
+ raise PosError(f"{pattern!r} vanished before the tap")
+ scored = []
+ for node in matches:
+ target = screen.tap_target(node)
+ interactive = target.clickable and target.enabled
+ scored.append((0 if interactive else 1, -node.bounds[1], node))
+ scored.sort()
+ chosen = scored[0][2]
+ self.dev.tap_node(chosen, screen)
+ time.sleep(1.0)
+ return screen
+
+ def _wait_or_scroll(self, pattern: str, timeout: int,
+ tries: int = 4) -> Screen:
+ """Wait for a label, scrolling if the screen has somewhere to scroll.
+
+ A control below the fold is not on the screen *at all* -- a lazy list
+ does not compose what it is not showing -- so waiting for it times out
+ with a message that reads like the control does not exist. The login
+ form is the case that matters: once the keyboard is up it scrolls, and
+ Connect, "Remember password" and "No account?" are all underneath it.
+ Scrolling first and judging afterwards is the only way to tell "this
+ screen has no such button" from "this screen has not shown it yet".
+ """
+ last: Optional[Exception] = None
+ per_try = max(5, timeout // tries)
+ for attempt in range(tries):
+ try:
+ return self.dev.wait_for(pattern, timeout=per_try)
+ except TimeoutError as exc:
+ last = exc
+ screen = self._stable_dump()
+ if not any(n.scrollable for n in screen.nodes):
+ break
+ before = screen.texts()
+ self.dev.scroll(down=True, screen=screen)
+ time.sleep(0.8)
+ if self._stable_dump().texts() == before:
+ # Already at the end; one more wait would say the same thing.
+ break
+ assert last is not None
+ raise last
+
+ def _within_window(self, pattern: str, screen: Screen) -> bool:
+ """Whether a control can be tapped where the dump says it is.
+
+ Two things can hide it. The window the dump describes may end above
+ it, which is the ordinary "below the fold". Or the keyboard may be
+ drawing over it -- and for a *dialog* the dump covers only the dialog,
+ which happily reports its buttons at coordinates the keyboard owns.
+ That is not theoretical: a tap aimed at the custom-product dialog's
+ Add button landed on the letter u and typed it into the field.
+ """
+ box = screen.root_bounds()
+ if not box:
+ return False
+ ime_top = self.dev.ime_top()
+ if ime_top is None:
+ # The keyboard is up and nothing says where: assume it is in the
+ # way, which is what the driver did before it could ask. Guessing
+ # the other way taps a key and types a letter into whatever has
+ # focus.
+ return False
+ rx = re.compile(pattern, re.I)
+ bottom = min(box[3], ime_top)
+ return any(n.label and rx.search(n.label) and n.bounds[3] <= bottom
+ for n in screen.nodes)
+
+ def control_reachable(self, pattern: str,
+ screen: Optional[Screen] = None) -> bool:
+ """Whether a control can actually be pressed where it is drawn.
+
+ False when the keyboard is over it, which on a short screen is where
+ a dialog's buttons end up -- the dialog is its own window and reports
+ them at their layout position regardless.
+ """
+ screen = screen or self._stable_dump()
+ ime_top = self.dev.ime_top()
+ if ime_top is None:
+ return bool(screen.find(pattern))
+ rx = re.compile(pattern, re.I)
+ return any(n.label and rx.search(n.label) and n.bounds[3] <= ime_top
+ for n in screen.nodes)
+
+ def _scroll_into_view(self, pattern: str, screen: Screen,
+ tries: int = 3) -> Screen:
+ """Bring a control inside the window, if the layout has it below.
+
+ The login form is taller than a phone's screen in landscape and
+ Connect is the last thing on it: with the keyboard up the form scrolls
+ itself and Connect is reachable, with the keyboard down it is a couple
+ of hundred pixels past the bottom edge. A tap there does nothing at
+ all, which reads as a dead button -- and the keyboard has to be down
+ before the tap for the separate reason above, so one of the two has to
+ give and it is this one.
+ """
+ rx = re.compile(pattern, re.I)
+ _, height = self.dev.size()
+ for _ in range(tries):
+ matches = [n for n in screen.nodes if n.label and rx.search(n.label)]
+ if not matches or any(n.bounds[3] <= height for n in matches):
+ return screen
+ before = screen
+ self.dev.scroll(down=True, screen=before)
+ time.sleep(1)
+ screen = self._stable_dump()
+ # A scroll aimed at the largest scrollable can move something that
+ # is not the control -- a dialog's own list, say -- and carry the
+ # control off the screen altogether. Losing it is worse than not
+ # having moved it, so that is undone.
+ if not any(n.label and rx.search(n.label) for n in screen.nodes):
+ self.dev.scroll(down=False, screen=before)
+ time.sleep(1)
+ return self._stable_dump()
+ return screen
+
+ def field_for(self, label: str, screen: Optional[Screen] = None) -> Node:
+ """The text field a label belongs to.
+
+ A Material text field draws its label *inside* its own box while the
+ field is empty and lifts it to the top edge once there is content, so
+ the label and the field are two nodes whose relationship changes as
+ the form is filled. Three rules in order, each exact enough to be
+ wrong loudly rather than quietly:
+
+ 1. the field whose own label matches -- which is how a filled field
+ with a floating label and a placeholder presents itself;
+ 2. the field whose box contains the label's centre, which covers the
+ empty case and the lifted case alike;
+ 3. failing that, the nearest field below the label.
+
+ Rule 2 replaced a "first field at or below the label's top edge" test,
+ which looked equivalent and was not: the login form's empty Username
+ label starts a single pixel below its own field, so the field was
+ excluded and the *password* field was the nearest match. Typing the
+ instance name into the password box is not the kind of mistake a
+ scenario notices -- the form just refuses to log in.
+ """
+ screen = screen or self._stable_dump()
+ fields = screen.editable()
+ if not fields:
+ # The caller may have handed in a screen from before a navigation,
+ # or the dump may have lost its race; read it again before
+ # concluding that the form has no fields.
+ screen = self._stable_dump()
+ fields = screen.editable()
+ rx = re.compile(label, re.I)
+ if not fields:
+ raise PosError(f"no text field on screen at all; "
+ f"screen: {screen.texts()}")
+ direct = next((n for n in fields if rx.search(n.label)), None)
+ if direct is not None:
+ return direct
+ anchors = [n for n in screen.nodes if n.label and rx.search(n.label)]
+ if not anchors:
+ raise PosError(f"no field labelled {label!r}; screen: {screen.texts()}")
+ anchor = anchors[0]
+ ax, ay = anchor.center
+ containing = [n for n in fields
+ if n.bounds[0] <= ax <= n.bounds[2]
+ and n.bounds[1] <= ay <= n.bounds[3]]
+ if containing:
+ return min(containing, key=lambda n: n.area)
+ below = [n for n in fields if n.bounds[1] >= anchor.bounds[3] - 8]
+ if below:
+ return min(below, key=lambda n: (n.bounds[1], n.bounds[0]))
+ raise PosError(
+ f"{label!r} has no field inside or below it; "
+ f"label at {anchor.bounds}, fields at {[n.bounds for n in fields]}")
+
+ def fill_field(self, label: str, text: str,
+ screen: Optional[Screen] = None,
+ verify: bool = True) -> None:
+ """Clear the field belonging to a label and type into it.
+
+ With `verify`, what the field ends up holding is checked against what
+ was typed -- by content where the field shows its text, and by length
+ where it shows dots instead. A field that did not take the text is
+ the single most expensive kind of harness bug there is: the form then
+ fails to log in, and the scenario reports that the terminal rejected a
+ valid credential.
+ """
+ screen = screen or self._stable_dump()
+ field = self._field_in_view(label, screen)
+ self.dev.clear_field(field, screen)
+ self.dev.type_text(text)
+ time.sleep(0.5)
+ if not verify:
+ return
+ after = self._stable_dump()
+ try:
+ now = self.field_for(label, after)
+ except PosError:
+ return # the layout moved; nothing to check against
+ value = now.label
+ masked = set(value) <= set("\u2022*\u00b7 ")
+ if masked and value:
+ if len(value.strip()) != len(text):
+ raise PosError(
+ f"the field for {label!r} holds {len(value.strip())} "
+ f"masked characters, not the {len(text)} that were typed")
+ return
+ if value.strip() != text.strip():
+ raise PosError(
+ f"the field for {label!r} holds {value!r} after typing {text!r}")
+
+ def _field_in_view(self, label: str, screen: Screen) -> Node:
+ """The field for a label, at coordinates a tap can still reach.
+
+ On a tablet the login form fits and the coordinates in any dump are
+ good. On a phone it does not: the form scrolls itself to keep the
+ focused field above the soft keyboard, so the second field a scenario
+ fills has moved by a couple of hundred pixels since the dump it was
+ resolved from -- and a tap at the old place lands on the keyboard,
+ where it silently types a letter into the field that still has focus.
+
+ So the box is checked against the window the dump itself describes. If
+ it falls outside, the form is scrolled and the field resolved again;
+ if it is still outside, that is worth failing on rather than tapping
+ blind.
+ """
+ # A form short enough to scroll does not compose the fields it is not
+ # showing, so a field further down is not merely out of the window --
+ # it is not in the hierarchy at all, and `field_for` says there is no
+ # such field. That is the same sentence a form genuinely without the
+ # field would produce, so the scroll has to come first and the
+ # complaint afterwards.
+ for attempt in range(4):
+ try:
+ field = self.field_for(label, screen)
+ except PosError:
+ if attempt == 3:
+ raise
+ # Not "is anything scrollable?": a lazy form showing one item
+ # reports no scrollable node at all, and that is exactly the
+ # case this is for.
+ before = screen.texts()
+ self.dev.scroll(down=True, screen=screen)
+ time.sleep(1)
+ screen = self._stable_dump()
+ if screen.texts() == before:
+ raise
+ continue
+ _, height = self.dev.size()
+ if field.bounds[3] <= height:
+ return field
+ self.dev.scroll(down=True, screen=screen)
+ time.sleep(1)
+ screen = self._stable_dump()
+ field = self.field_for(label, screen)
+ _, height = self.dev.size()
+ if field.bounds[3] > height:
+ raise PosError(
+ f"the field for {label!r} is at {field.bounds}, below the "
+ f"{height}px window, and scrolling did not bring it up")
+ return field
+ raise PosError(f"no field labelled {label!r} after scrolling")
+
+ # Buttons that only a dialog has. Matching on the terminal's own wording
+ # rather than on a widget class, because a Compose AlertDialog's buttons
+ # are ordinary Buttons and nothing in the hierarchy says "dialog".
+ DIALOG_BUTTONS = re.compile(
+ r"(?i)^(ok|cancel|continue|force delete|log out|approve refund|abort|"
+ r"try fixed link|continue as is|cancel order|cancel payment|add|"
+ r"received|dismiss|close)$")
+
+ def read_dialog(self, screen: Optional[Screen] = None) -> Optional[Dialog]:
+ """The modal on screen, if there is one, as a tester reads it.
+
+ Recognised by shape rather than by wording, so that a dialog with an
+ unexpected message is still read -- "Error: Invalid configuration" with
+ nothing else is itself a finding.
+
+ The shape has to be found geometrically. The terminal uses two kinds of
+ modal: a `DialogFragment` (the error dialog), which is its own window
+ and dumps alone; and Compose `AlertDialog`s (logout, force delete, the
+ insecure-payment prompt), which are drawn *into the same window* as the
+ screen behind them -- so that dump contains the whole settings screen
+ as well, and any rule of the form "a dialog has few labels" calls it a
+ screen. What is reliably true is that the dialog's text sits directly
+ above its buttons and within their horizontal span, so that is what is
+ collected.
+ """
+ screen = screen or self._stable_dump()
+ buttons = [n for n in screen.nodes
+ if n.label.strip() and self.DIALOG_BUTTONS.fullmatch(n.label.strip())
+ and (n.clickable or screen.tap_target(n).clickable)]
+ if not buttons:
+ return None
+ labels = [n.label.strip() for n in buttons]
+ top = min(n.bounds[1] for n in buttons)
+ above = [n for n in screen.nodes
+ if n.label.strip()
+ and n.label.strip() not in labels
+ and n.bounds[3] <= top + 8
+ and n.bounds[1] >= top - 900]
+ if not above:
+ return None
+ # A dialog of the terminal's dumps as a window of its own, so what is
+ # above the buttons is the dialog and nothing else. The exception is
+ # a modal drawn into the screen behind it, which shows up as far more
+ # text than a dialog has -- and then the dialog's own text is what
+ # shares a column with its widest line.
+ if len(above) > 8:
+ anchor = max(above, key=lambda n: n.bounds[2] - n.bounds[0])
+ lo, hi = anchor.bounds[0] - 40, anchor.bounds[2] + 40
+ above = [n for n in above if n.bounds[0] >= lo and n.bounds[2] <= hi]
+ if not above:
+ return None
+ above.sort(key=lambda n: (n.bounds[1], n.bounds[0]))
+ texts = [n.label.strip() for n in above]
+ title = texts[0]
+ message = " ".join(texts[1:])[:600] if len(texts) > 1 else ""
+ return Dialog(title=title, message=message, buttons=labels)
+
+ def dismiss_dialog(self) -> Optional[Dialog]:
+ """Read and close whatever modal is up; returns what it said."""
+ dialog = self.read_dialog()
+ if dialog is None:
+ return None
+ for label in ("OK", "Ok", "ok"):
+ node = self.dev.dump().find(rf"^{label}$")
+ if node is not None:
+ self.dev.tap_node(node, self.dev.dump())
+ time.sleep(1)
+ return dialog
+ self.dev.back()
+ time.sleep(1)
+ return dialog
+
+ # -- building an order ------------------------------------------------
+
+ def enter_digits(self, digits: str) -> Screen:
+ """Press keypad keys, in order, without interpreting them.
+
+ The keypad is deliberately digits-only -- there is no decimal key at
+ all. It fills from the right, so "100" is one unit and "1" is one
+ cent, exactly like a till. Scenarios that care about the keypad's own
+ behaviour (overflow, leading zeros, backspace) use this; scenarios that
+ just want to charge a price use `enter_amount`.
+ """
+ screen = self.dev.wait_for(MARK_AMOUNT, timeout=45)
+ for char in digits:
+ if char in "cC":
+ self.tap_button(r"^Clear$")
+ screen = self.dev.dump()
+ continue
+ if char in "<b":
+ node = screen.find(r"^Backspace$")
+ if node is None:
+ raise PosError("no backspace key on the keypad")
+ self.dev.tap_node(node, screen)
+ time.sleep(0.25)
+ continue
+ node = screen.find(rf"^{re.escape(char)}$")
+ if node is None:
+ raise PosError(f"no keypad key for {char!r}; "
+ f"keys: {sorted(set(screen.texts()))}")
+ self.dev.tap_node(node, screen)
+ time.sleep(0.25)
+ return self.dev.dump()
+
+ # The keypad groups thousands once the amount is long enough, so the
+ # display reads "999,999,999,999.99" rather than a bare run of digits.
+ # Matching only the ungrouped shape reported the terminal's largest
+ # amount as no amount at all.
+ AMOUNT_SHOWN = re.compile(r"\d{1,3}(?:[.,\u00a0\u202f ]\d{3})*[.,]\d{2}|\d+[.,]\d+")
+
+ def displayed_amount(self, screen: Optional[Screen] = None) -> Optional[str]:
+ """The amount the keypad is showing, as the terminal renders it."""
+ screen = screen or self.dev.dump()
+ keys = {str(d) for d in range(10)}
+ for node in screen.nodes:
+ text = node.label.strip()
+ if text in keys:
+ continue
+ if self.AMOUNT_SHOWN.fullmatch(text):
+ return text
+ return None
+
+ def enter_amount(self, amount: str, verify: bool = True) -> Screen:
+ """Type a price on the keypad of the "order by amount" screen.
+
+ `amount` is written the way it is displayed -- "1.00", "0.05" -- and
+ translated into the keystrokes that produce it, because the keypad has
+ no separator key and fills from the right. With `verify`, what the
+ screen ends up showing is compared against what was asked for, which is
+ the cheapest check there is on the keypad's own arithmetic.
+
+ The keypad is used rather than the text field above it: the field is
+ editable, but the keypad is what a cashier touches, and the two do not
+ share their input filtering.
+ """
+ if not re.fullmatch(r"\d+(?:[.,]\d+)?", amount):
+ raise ValueError(f"{amount!r} is not a plain decimal amount")
+ digits = amount.replace(".", "").replace(",", "").lstrip("0") or "0"
+ self.tap_button(r"^Clear$")
+ screen = self.enter_digits(digits)
+ if verify:
+ shown = self.displayed_amount(screen)
+ if shown is None:
+ raise PosError(f"the keypad shows no amount after typing {digits!r}; "
+ f"screen: {screen.texts()}")
+ if _as_minor(shown) != _as_minor(amount):
+ raise PosError(
+ f"typing {digits!r} on the keypad was meant to give "
+ f"{amount} and gave {shown}")
+ return screen
+
+ def charge(self, timeout: int = 90) -> Screen:
+ """Press Charge and wait for the payment screen."""
+ self.tap_button(r"Create order \(charge amount\)|^Charge$")
+ return self.dev.wait_for(MARK_PAYMENT, timeout=timeout)
+
+ def add_products(self, count: int = 1) -> list[str]:
+ """Tap the first sellable products in the order grid.
+
+ Which products exist depends on the instance, so this picks them off
+ the grid rather than by name, and skips the ones the terminal has
+ marked unsellable -- tapping "Out of stock" is a scenario of its own,
+ not a way to build an order.
+ """
+ screen = self.dev.wait_for(MARK_ORDER, timeout=60)
+ blocked = {"Unavailable", "Out of stock", "Wrong currency"}
+ added: list[str] = []
+ for _ in range(count):
+ screen = self.dev.dump()
+ cards = self._product_cards(screen, blocked)
+ if not cards:
+ raise PosError(f"no sellable product in the grid; "
+ f"screen: {screen.texts()[:40]}")
+ card = cards[len(added) % len(cards)]
+ self.dev.tap_node(card, screen)
+ added.append(card.label.strip())
+ time.sleep(1.0)
+ return added
+
+ def _product_cards(self, screen: Screen, blocked: set[str]) -> list[Node]:
+ """The tappable product tiles, with the unsellable ones left out."""
+ width, height = self.dev.size()
+ out = []
+ for node in screen.nodes:
+ label = node.label.strip()
+ if not label or label in blocked:
+ continue
+ if node.bounds[0] < width // 5:
+ continue # the category column, not the grid
+ if node.bounds[1] < height // 6:
+ continue # the top bar
+ target = screen.tap_target(node)
+ if not (target.clickable and target.enabled):
+ continue
+ # A price is what tells a product tile from a section label.
+ near = [n.label for n in screen.nodes
+ if abs(n.bounds[1] - node.bounds[1]) < 240
+ and abs(n.bounds[0] - node.bounds[0]) < 240]
+ if not any(re.search(r"\d+[.,]\d\d", t or "") for t in near):
+ continue
+ out.append(node)
+ return out
+
+ def add_custom_product(self, name: str, amount: str) -> Screen:
+ """Use the order screen's "Add custom product" dialog."""
+ self.tap_button(r"Add custom product")
+ self.dev.wait_for(r"Custom product name", timeout=20)
+ screen = self.dev.dump()
+ self.fill_field(r"Custom product name", name, screen)
+ screen = self.dev.dump()
+ fields = screen.editable()
+ if len(fields) < 2:
+ raise PosError(f"the custom product dialog has {len(fields)} fields, "
+ f"expected a name and an amount")
+ amount_field = max(fields, key=lambda n: (n.bounds[1], n.bounds[0]))
+ self.dev.clear_field(amount_field, screen)
+ self.dev.type_text(amount)
+ time.sleep(0.4)
+ self.tap_button(r"^Add$")
+ return self.dev.dump()
+
+ def open_custom_product_dialog(self) -> Screen:
+ """Open the custom-product dialog and leave it open."""
+ self.tap_button(r"Add custom product")
+ self.dev.wait_for(r"Custom product name", timeout=20)
+ return self._stable_dump()
+
+ def fill_custom_amount(self, amount: str) -> None:
+ """Type into the dialog's price field.
+
+ The two fields have the same kind of label from the driver's point of
+ view -- the second one's label is the currency -- so it is taken by
+ position: the lower of the two editables.
+ """
+ screen = self._stable_dump()
+ fields = screen.editable()
+ if len(fields) < 2:
+ raise PosError(f"the custom product dialog has {len(fields)} "
+ f"fields, expected a name and an amount")
+ amount_field = max(fields, key=lambda n: (n.bounds[1], n.bounds[0]))
+ self.dev.clear_field(amount_field, screen)
+ self.dev.type_text(amount)
+ time.sleep(0.4)
+
+ def select_order_line(self, name: str) -> Screen:
+ """Tap a product where it appears in the order, not in the grid.
+
+ Both show the same text, and the grid's card is the one higher up the
+ screen on a tablet and on a different pane on a phone -- so the line
+ is the *lowest* node carrying the name, which is the one inside the
+ order pane in both layouts.
+ """
+ screen = self._stable_dump()
+ matches = [n for n in screen.nodes
+ if n.label and re.search(re.escape(name), n.label)]
+ if not matches:
+ raise PosError(f"{name!r} is not in the order")
+ line = max(matches, key=lambda n: n.bounds[1])
+ self.dev.tap_node(line, screen)
+ time.sleep(1)
+ return self._stable_dump()
+
+ def login_form_values(self) -> tuple[Optional[str], Optional[str]]:
+ """What the login form's host and username fields hold."""
+ screen = self._stable_dump()
+ host = username = None
+ try:
+ host = self.field_for(r"Merchant portal URL", screen).label or None
+ except PosError:
+ pass
+ try:
+ username = self.field_for(r"^Username$", screen).label or None
+ except PosError:
+ pass
+ return host, username
+
+ def bill(self, timeout: int = 90) -> Screen:
+ """Press Bill on the inventory order screen."""
+ self.tap_button(BILL_BUTTON)
+ return self.dev.wait_for(MARK_PAYMENT, timeout=timeout)
+
+ # -- the payment screen -----------------------------------------------
+
+ def copy_displayed_uri(self, scheme: str = "taler",
+ tries: int = 3) -> Optional[str]:
+ """Read the URI behind the QR code, through the screen's copy button.
+
+ The payment and refund screens render their URI only as a QR code, and
+ a view-hierarchy dump cannot read an image -- but both screens offer a
+ copy button, and the sim hooks can read the clipboard back from inside
+ the app. So the harness sees exactly the string the customer's wallet
+ would get, and the copy button gets exercised on the way.
+
+ Three things are retried, because each of them fails occasionally and
+ each failure otherwise reads as "the terminal is offering no code at
+ all": a dump that comes back empty, a tap that lands while the screen
+ is still settling, and a clipboard that still holds the previous
+ value. The expected scheme is what tells the last case apart -- which
+ is why it is checked here rather than by the caller.
+ """
+ for attempt in range(tries):
+ screen = self._stable_dump()
+ node = screen.find(r"^Copy$|Copy payment URI")
+ if node is None:
+ if not screen.find(MARK_PAYMENT) and not screen.find(MARK_REFUND_URI):
+ return None # not a screen with a code on it
+ time.sleep(1.5)
+ continue
+ self.dev.tap_node(node, screen)
+ time.sleep(1.2 + attempt)
+ value = self.dev.read_clipboard()
+ if value and value.startswith(scheme):
+ return value
+ return None
+
+ def displayed_pay_uri(self) -> Optional[str]:
+ """The pay URI the terminal is currently showing."""
+ return self.copy_displayed_uri(scheme="taler")
+
+ def published_nfc_uri(self) -> Optional[str]:
+ """The pay URI the terminal is offering over NFC, if any.
+
+ Always absent on an emulator -- there is no NFC adapter for the
+ service to publish through -- so this exists to confirm the terminal
+ does not claim an NFC payment is possible when it is not.
+ """
+ payload = self.dev.report_nfc_payload()
+ return None if payload in (None, "none", "empty-message") else payload
+
+ def wait_for_claimed(self, timeout: int = 90) -> Screen:
+ return self.dev.wait_for(r"confirm payment", timeout=timeout)
+
+ def wait_for_success(self, timeout: int = 180) -> Screen:
+ return self.dev.wait_for(MARK_SUCCESS, timeout=timeout)
+
+ def cancel_payment(self) -> Screen:
+ self.tap_button(r"Cancel payment")
+ time.sleep(2)
+ return self.dev.dump()
+
+ def continue_from_success(self) -> Screen:
+ self.tap_button(r"^Continue$")
+ time.sleep(2)
+ return self.dev.dump()
+
+ # -- history and refunds ----------------------------------------------
+
+ def refresh_history(self, timeout: int = 90) -> Screen:
+ self.tap_button(r"Refresh history")
+ # The list keeps its old contents while reloading, so there is nothing
+ # to wait for on screen except the toast; a short settle is honest.
+ time.sleep(4)
+ return self.dev.wait_for(MARK_HISTORY, timeout=timeout)
+
+ def history_rows(self, screen: Optional[Screen] = None) -> list[str]:
+ """The order references the history list is showing."""
+ screen = screen or self.dev.dump()
+ return [n.label.strip() for n in screen.nodes
+ if re.match(r"(?i)^(Ref|Receipt)\s*#", n.label.strip() or "")]
+
+ def open_order_details(self, row: int = 0, timeout: int = 45) -> Screen:
+ """Open the order-details page for the nth history row, newest first.
+
+ `tap_button` cannot be used: every row carries an identical "Order
+ details" label and it picks the *lowest* match on screen, which is the
+ oldest order rather than the one a scenario just created. The rows
+ are therefore sorted by their own position and indexed.
+ """
+ screen = self.dev.wait_for(r"^Order details$", timeout=timeout)
+ rows = sorted((n for n in screen.labelled()
+ if n.label.strip() == "Order details"),
+ key=lambda n: n.bounds[1])
+ if row >= len(rows):
+ raise PosError(f"the history has {len(rows)} row(s) with details, "
+ f"not {row + 1}")
+ self.dev.tap_node(rows[row], screen)
+ time.sleep(3)
+ return self.dev.wait_for(r"Order reference|Payment breakdown",
+ timeout=timeout)
+
+ def start_refund(self, row_pattern: str = r"^Refund$",
+ timeout: int = 45) -> Screen:
+ self.tap_button(row_pattern, timeout=timeout)
+ # The refund form focuses its amount field as it opens, so the keyboard
+ # is up before anything has been tapped -- and on a short screen the
+ # form's buttons are then not in the hierarchy at all, so waiting for
+ # "Approve refund" waits for something that is not there. Putting the
+ # keyboard away first is what a person would have to do too.
+ time.sleep(1)
+ if self.dev.keyboard_shown():
+ self.dev.hide_keyboard()
+ time.sleep(1)
+ try:
+ return self.dev.wait_for(MARK_REFUND_FORM, timeout=timeout)
+ except TimeoutError:
+ # The form is open and its controls are not in the hierarchy; that
+ # is worth a picture, because the difference between "the terminal
+ # clipped them" and "the driver is looking in the wrong place" is
+ # not visible in a list of labels.
+ shot = Path(os.environ.get("POS_SIM_ROOT", "/tmp/taler-pos-sim"))
+ shot = shot / "out" / "refund-form-without-its-buttons.png"
+ shot.parent.mkdir(parents=True, exist_ok=True)
+ self.dev.screenshot(str(shot))
+ raise
+
+ def submit_refund(self, amount: str, reason: str = "pos-simulator",
+ expect_success: bool = True) -> Screen:
+ screen = self.dev.wait_for(MARK_REFUND_FORM, timeout=45)
+ self.fill_field(r"^Amount$", amount, screen)
+ screen = self.dev.dump()
+ if screen.find(r"Refund reason"):
+ self.fill_field(r"Refund reason", reason, screen)
+ self._reach_approve_refund()
+ self.tap_button(APPROVE_REFUND)
+ if not expect_success:
+ time.sleep(5)
+ return self.dev.dump()
+ return self.dev.wait_for(MARK_REFUND_URI, timeout=90)
+
+ def _reach_approve_refund(self) -> None:
+ """Make sure the refund form's buttons are on screen before tapping.
+
+ Filling the amount raises the keyboard, and on a short screen the form
+ -- a Column with no `verticalScroll` -- then has no room for its two
+ buttons and drops them from the hierarchy entirely. `start_refund`
+ sees them because it puts the keyboard away first; by the time the
+ amount has been typed they are gone again, which is why the failure
+ lands on the tap and not on opening the form.
+
+ The screen is photographed in that state before the keyboard is put
+ away, because the picture is the evidence for whether this is the
+ terminal clipping its controls or the driver looking in the wrong
+ place.
+ """
+ screen = self._stable_dump()
+ if screen.find(APPROVE_REFUND):
+ return
+ shot = Path(os.environ.get("POS_SIM_ROOT", "/tmp/taler-pos-sim"))
+ shot = shot / "out" / "refund-form-without-its-buttons.png"
+ shot.parent.mkdir(parents=True, exist_ok=True)
+ self.dev.screenshot(str(shot))
+ if self.dev.keyboard_shown():
+ self.dev.hide_keyboard()
+ time.sleep(1.5)
+
+ def refund_uri_for(self, merchant_host: str, instance: str,
+ order_id: str) -> str:
+ """The refund URI the terminal is showing, by construction.
+
+ The payment screen offers Copy and Share; the refund screen offers
+ neither -- only Abort -- so the URI behind its QR code cannot be read
+ off the device at all. It is derived from the order instead, which is
+ what the backend put in the code.
+ """
+ # The trailing slash is load-bearing: the backend's own builder writes
+ # an empty final path component (`GNUNET_buffer_write_path (&buf, "")`
+ # in make_taler_refund_uri), and a wallet rejects the URI without it
+ # as malformed rather than as an unknown order.
+ return f"taler://refund/{merchant_host}/instances/{instance}/{order_id}/"
+
+ # -- settings ---------------------------------------------------------
+
+ def settings_logout(self, confirm: bool = True) -> Screen:
+ """Log out, through both of the dialogs that stand in the way."""
+ self.goto("settings")
+ self.tap_button(r"^Log out$")
+ time.sleep(1.5)
+ if not confirm:
+ self.tap_button(r"^Cancel$")
+ return self.dev.dump()
+ # The first dialog warns what logging out removes and its positive
+ # button is labelled "Continue"; the second asks "are you sure".
+ for label in (r"^Continue$", r"^Log out$"):
+ try:
+ self.tap_button(label, timeout=15)
+ except TimeoutError:
+ break
+ time.sleep(1.5)
+ return self.dev.wait_for(MARK_CONFIG, timeout=60)
+
+ def about_rows(self) -> dict[str, str]:
+ """The Settings screen's About block, as label -> value.
+
+ It is where the terminal says which instance and URL it is bound to,
+ which is the only place a scenario can confirm that provisioning
+ landed where it meant to -- and the backend version it negotiated,
+ which it appends to the URL in brackets.
+
+ The block renders each row as a single `"Label: value"` node, so the
+ pair is split out of one label rather than matched across two; the
+ two-node shape is kept as a fallback because a long value wraps.
+ """
+ # The keyboard survives the move from the login form to Settings, and
+ # it takes two thirds of the list with it -- so the About card's rows
+ # cannot be scrolled to while it is up, and a reader that did not put
+ # it away reported an unbound terminal on a terminal that was bound.
+ if self.dev.keyboard_shown():
+ self.dev.hide_keyboard()
+ time.sleep(0.8)
+ screen = self.goto("settings")
+ # The About card is the last item of a lazy list, so finding its
+ # *title* is not enough -- the rows under it are still off screen, and
+ # a reader that stopped there reported an unbound terminal on a
+ # terminal that was bound. Scroll until a row appears, or until the
+ # screen stops changing.
+ for _ in range(8):
+ if screen.find(r"^(?:Taler POS|Username|Merchant portal URL):"):
+ break
+ before = screen.texts()
+ self.dev.scroll(down=True, screen=screen)
+ time.sleep(1)
+ screen = self._stable_dump()
+ if screen.texts() == before:
+ break
+ wanted = ("Taler POS", "Username", "Merchant portal URL")
+ rows: dict[str, str] = {}
+ labels = [n for n in screen.nodes if n.label.strip()]
+ for node in labels:
+ text = node.label.strip()
+ for key in wanted:
+ if text.startswith(f"{key}:"):
+ rows[key] = text[len(key) + 1:].strip()
+ for key in wanted:
+ if key in rows:
+ continue
+ anchor = next((n for n in labels if n.label.strip() == key), None)
+ if anchor is None:
+ continue
+ same_row = [n for n in labels
+ if n is not anchor
+ and abs(n.center[1] - anchor.center[1]) < 60
+ and n.bounds[0] > anchor.bounds[0]]
+ if same_row:
+ rows[key] = min(same_row, key=lambda n: n.bounds[0]).label.strip()
+ return rows
+
+ # -- payment options and the mixed-payment checkout -------------------
+ #
+ # Turning on a second payment option changes what Charge does: instead of
+ # going straight to the Taler QR code, the terminal opens a checkout that
+ # collects cash or card first and leaves Taler to pay whatever is still
+ # open. Everything below drives that, and none of it is reachable while
+ # Taler is the only option -- which is the terminal's own default, so a
+ # scenario has to turn one on before it can test any of it.
+
+ def goto_payment_options(self, timeout: int = 45) -> Screen:
+ """Settings -> Manage payment options."""
+ screen = self.goto("settings")
+ if screen.find(MARK_PAYMENT_OPTIONS):
+ return screen
+ # "Payment options" is also the Settings card's own heading, which is
+ # not clickable; the button under it says "Manage payment options" and
+ # on a phone it is below the fold, so the tap has to scroll to it.
+ self.tap_button(r"^Manage payment options$")
+ return self.dev.wait_for(MARK_PAYMENT_OPTIONS, timeout=timeout)
+
+ def payment_option_rows(self, screen: Optional[Screen] = None
+ ) -> dict[str, bool]:
+ """Each payment option and whether its switch is on.
+
+ The switch is a separate, unlabelled node beside the option's name --
+ Compose puts the name in the card and the `Switch` next to it -- so it
+ is found by row rather than by label, the same way the About block is
+ read.
+ """
+ screen = screen or self._stable_dump()
+ names = [n for n in screen.labelled()
+ if n.label.strip() in ("GNU Taler", "Cash", "SumUp")]
+ switches = [n for n in screen.nodes if n.checkable]
+ out: dict[str, bool] = {}
+ for name in names:
+ same_row = [sw for sw in switches
+ if abs(sw.center[1] - name.center[1]) < 120]
+ if same_row:
+ nearest = min(same_row,
+ key=lambda sw: abs(sw.center[1] - name.center[1]))
+ out[name.label.strip()] = nearest.checked
+ return out
+
+ def set_payment_option(self, name: str, on: bool = True,
+ timeout: int = 20) -> dict[str, bool]:
+ """Turn a payment option on or off, and confirm it took.
+
+ An option with an activation notice (SumUp has one) puts a dialog in
+ the way, so the confirm button is pressed if it appears. Tapping the
+ card itself opens the option's own screen instead of toggling it, so
+ the switch is what gets tapped.
+ """
+ screen = self.goto_payment_options()
+ rows = self.payment_option_rows(screen)
+ if name not in rows:
+ raise PosError(f"no payment option named {name!r}; "
+ f"options: {sorted(rows)}")
+ if rows[name] == on:
+ return rows
+ anchor = next(n for n in screen.labelled() if n.label.strip() == name)
+ switches = [n for n in screen.nodes if n.checkable
+ and abs(n.center[1] - anchor.center[1]) < 120]
+ if not switches:
+ raise PosError(f"no switch beside {name!r}")
+ self.dev.tap_node(min(switches,
+ key=lambda sw: abs(sw.center[1] - anchor.center[1])),
+ screen)
+ time.sleep(1.0)
+ # "Before you turn this on" -- only some options have it.
+ notice = self._stable_dump()
+ if notice.find(r"^Turn on$"):
+ self.tap_button(r"^Turn on$")
+ time.sleep(1.0)
+ deadline = time.monotonic() + timeout
+ while time.monotonic() < deadline:
+ rows = self.payment_option_rows()
+ if rows.get(name) == on:
+ return rows
+ time.sleep(1.0)
+ raise PosError(f"{name!r} is still {rows.get(name)!r} after asking for {on}")
+
+ def charge_to_checkout(self, timeout: int = 90) -> Screen:
+ """Press Charge and wait for the checkout rather than the QR code."""
+ self.tap_button(r"Create order \(charge amount\)|^Charge$")
+ return self.dev.wait_for(MARK_CHECKOUT, timeout=timeout)
+
+ def bill_to_checkout(self, timeout: int = 90) -> Screen:
+ """Complete an inventory order into the checkout."""
+ self.tap_button(BILL_BUTTON)
+ return self.dev.wait_for(MARK_CHECKOUT, timeout=timeout)
+
+ # "Total: X", "Paid: X", "To pay: X" on the compact layout; "Order total"
+ # with the amount underneath, "Paid: X" and "Remaining: X" on the wide one.
+ CHECKOUT_ROW = re.compile(
+ r"^(Total|Paid|To pay|Remaining|Still to pay)\s*:\s*(.+)$", re.I)
+
+ def checkout_amounts(self, screen: Optional[Screen] = None
+ ) -> dict[str, str]:
+ """What the checkout says the order comes to, and what is left.
+
+ Returned as the terminal renders them -- symbol, grouping and all --
+ because the point of reading them is to compare the screen against the
+ backend, and reformatting first would hide a formatting bug.
+ """
+ screen = screen or self._stable_dump()
+ out: dict[str, str] = {}
+ for node in screen.labelled():
+ m = self.CHECKOUT_ROW.match(node.label.strip())
+ if m:
+ key = m.group(1).lower()
+ key = {"still to pay": "to pay", "remaining": "to pay"}.get(key, key)
+ out.setdefault(key, m.group(2).strip())
+ # The compact layout writes the open amount as a "Remaining" heading
+ # with the figure underneath rather than as "Remaining: X".
+ if "to pay" not in out:
+ heading = next((n for n in screen.labelled()
+ if n.label.strip() in ("Remaining", "Still to pay")),
+ None)
+ if heading is not None:
+ below = [n for n in screen.labelled()
+ if n is not heading
+ and abs(n.center[0] - heading.center[0]) < 260
+ and n.bounds[1] >= heading.bounds[1]
+ and self.AMOUNT_SHOWN.search(n.label.strip())]
+ if below:
+ out["to pay"] = min(below,
+ key=lambda n: n.bounds[1]).label.strip()
+ if "total" not in out:
+ # The wide layout puts "Order total" on its own line with the
+ # amount underneath, rather than as "Total: X".
+ heading = next((n for n in screen.labelled()
+ if n.label.strip() == "Order total"), None)
+ if heading is not None:
+ below = [n for n in screen.labelled()
+ if n.bounds[1] >= heading.bounds[1]
+ and self.AMOUNT_SHOWN.search(n.label.strip())]
+ if below:
+ nearest = min(below, key=lambda n: n.bounds[1])
+ out["total"] = nearest.label.strip()
+ return out
+
+ def displayed_order_id(self, screen: Optional[Screen] = None
+ ) -> Optional[str]:
+ """The backend order id the terminal is showing, without its "#"."""
+ screen = screen or self._stable_dump()
+ for node in screen.labelled():
+ m = re.fullmatch(r"#(\S+)", node.label.strip())
+ if m:
+ return m.group(1)
+ return None
+
+ def checkout_tile(self, pattern: str, timeout: int = 30) -> Screen:
+ """Tap one of the checkout's payment-method tiles."""
+ screen = self.dev.wait_for(MARK_CHECKOUT, timeout=timeout)
+ self._scroll_into_view(pattern, screen)
+ return self.tap_button(pattern)
+
+ def checkout_pad_digits(self, digits: str) -> Screen:
+ """Press the checkout keypad's keys, in order.
+
+ The same till behaviour as the order keypad -- digits fill from the
+ right and there is no separator key -- but a keypad of its own, in a
+ full-screen dialog, so it cannot wait for the order screen's marker.
+ """
+ screen = self._stable_dump()
+ for char in digits:
+ if char in "cC":
+ self.tap_button(r"^Clear$")
+ screen = self._stable_dump()
+ continue
+ if char in "<b":
+ node = screen.find(r"^Backspace$")
+ if node is None:
+ raise PosError("no backspace key in the checkout keypad")
+ self.dev.tap_node(node, screen)
+ time.sleep(0.25)
+ continue
+ node = screen.find(rf"^{re.escape(char)}$")
+ if node is None:
+ raise PosError(f"no checkout keypad key for {char!r}; "
+ f"keys: {sorted(set(screen.texts()))}")
+ self.dev.tap_node(node, screen)
+ time.sleep(0.25)
+ return self._stable_dump()
+
+ def checkout_entry_amount(self, screen: Optional[Screen] = None
+ ) -> Optional[str]:
+ """The amount the checkout's keypad is showing.
+
+ The submit button spells it out -- "Record ク7.00 cash" -- which is the
+ one place it appears unambiguously; the big display above the keypad is
+ a bare number that the "Remaining to pay" line also matches.
+ """
+ screen = screen or self._stable_dump()
+ for node in screen.labelled():
+ m = re.match(r"^(?:Record|Charge)\s+(.+?)\s+(?:cash|on card)$",
+ node.label.strip())
+ if m:
+ return m.group(1).strip()
+ return None
+
+ def record_cash(self, amount: str, verify: bool = True) -> Optional[Dialog]:
+ """Take a cash payment of `amount` in the checkout.
+
+ Returns the "Give change" dialog if one opens, which is how a scenario
+ reads what the terminal worked out the change to be.
+ """
+ if not re.fullmatch(r"\d+(?:[.,]\d+)?", amount):
+ raise ValueError(f"{amount!r} is not a plain decimal amount")
+ self.checkout_tile(r"^Cash$")
+ self.dev.wait_for(MARK_CHECKOUT_PAD, timeout=30)
+ digits = amount.replace(".", "").replace(",", "").lstrip("0") or "0"
+ screen = self.checkout_pad_digits(digits)
+ if verify:
+ shown = self.checkout_entry_amount(screen)
+ if shown is None:
+ raise PosError("the checkout keypad shows no amount; "
+ f"screen: {screen.texts()}")
+ # The submit label carries the currency symbol as well, so the
+ # number is picked out of it before the two are compared.
+ number = self.AMOUNT_SHOWN.search(shown)
+ if number is None or _as_minor(number.group(0)) != _as_minor(amount):
+ raise PosError(f"typing {digits!r} in the checkout keypad was "
+ f"meant to give {amount} and gave {shown!r}")
+ self.tap_button(r"^Record .* cash$")
+ time.sleep(1.5)
+ dialog = self.read_dialog()
+ if dialog is not None and re.search(r"Give change|Hand .* back", str(dialog)):
+ self.dismiss_dialog()
+ return dialog
+ return dialog
+
+ def checkout_finish_with_taler(self, timeout: int = 120) -> Screen:
+ """Tap the Taler tile and wait for the payment screen."""
+ self.checkout_tile(r"^Charge with Taler$|^Charge remaining with Taler$"
+ r"|^Complete payment$")
+ return self.dev.wait_for(MARK_PAYMENT, timeout=timeout)
+
+ def checkout_cancel(self, confirm: bool = True) -> Screen:
+ """Cancel the checkout, through the warning if money has been taken."""
+ screen = self._stable_dump()
+ if screen.find(r"^About this checkout$"):
+ self.tap_button(r"^About this checkout$")
+ time.sleep(1.2)
+ # Tapped straight at the node rather than through `tap_button`:
+ # the dialog's buttons are inside a Compose AlertDialog, and
+ # `tap_button` may press Back on the way (to put a keyboard away,
+ # or to undo a scroll), which dismisses the dialog instead of
+ # answering it -- reported as "vanished before the tap".
+ screen = self.dev.wait_for(r"^Cancel payment anyway$", timeout=20)
+ want = r"^Cancel payment anyway$" if confirm else r"^Close$"
+ node = screen.find(want)
+ if node is None:
+ raise PosError(f"no {want!r} in the checkout's warning: "
+ f"{screen.texts()}")
+ self.dev.tap_node(node, screen)
+ else:
+ self.tap_button(r"^Cancel payment$")
+ time.sleep(2.0)
+ return self._stable_dump()
+
+ def bound_instance(self) -> tuple[Optional[str], Optional[str]]:
+ """Which instance and merchant URL the terminal believes it is using."""
+ rows = self.about_rows()
+ url = rows.get("Merchant portal URL", "")
+ return rows.get("Username"), re.sub(r"\s*\([^)]*\)\s*$", "", url) or None
+
+
+def _as_minor(amount: str) -> int:
+ """A displayed amount as an integer number of its smallest units."""
+ whole, _, frac = amount.replace(",", ".").partition(".")
+ frac = (frac + "00")[:2]
+ return int(whole or 0) * 100 + int(frac)
diff --git a/pos-simulator/driver/probe.py b/pos-simulator/driver/probe.py
@@ -0,0 +1,112 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""One action, then a dump. This is how labels get discovered.
+
+ python3 probe.py just dump
+ python3 probe.py tap 'Connect' tap a label and dump
+ python3 probe.py goto history open a drawer destination
+ python3 probe.py drawer open the navigation drawer
+ python3 probe.py uri 'taler-pos://.' deliver a setup URI
+ python3 probe.py nfc what is published over NFC
+ python3 probe.py dialog read the modal on screen
+ python3 probe.py shot /tmp/a.png screenshot
+ python3 probe.py log 80 the terminal's own log lines
+
+An ad-hoc probe must name its serial, or it interferes with a running round:
+`POS_WORKER=4 python3 probe.py ...`, or POS_SERIAL for the serial itself.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+from device import Device, serial_for
+from pos import Pos
+
+
+def serial() -> str:
+ return serial_for()
+
+
+def main(argv: list[str]) -> int:
+ dev = Device(serial())
+ app = Pos(dev)
+ cmd = argv[0] if argv else "dump"
+ arg = argv[1] if len(argv) > 1 else None
+
+ if cmd == "tap" and arg:
+ app.tap_button(arg)
+ elif cmd == "goto" and arg:
+ app.goto(arg)
+ elif cmd == "drawer":
+ app.open_drawer()
+ elif cmd == "uri" and arg:
+ dev.setup_uri(arg)
+ time.sleep(4)
+ elif cmd == "back":
+ dev.back()
+ time.sleep(1.5)
+ elif cmd == "scroll":
+ dev.scroll(down=(arg != "up"), screen=dev.dump())
+ time.sleep(1.5)
+ elif cmd == "type" and arg:
+ screen = dev.dump()
+ fields = screen.editable()
+ if not fields:
+ print("no editable field on screen")
+ return 1
+ dev.clear_field(fields[0], screen)
+ dev.type_text(arg)
+ time.sleep(1)
+ elif cmd == "nfc":
+ print(f"nfc payload: {dev.report_nfc_payload()}")
+ return 0
+ elif cmd == "dialog":
+ print(f"dialog: {app.read_dialog()}")
+ return 0
+ elif cmd == "shot":
+ dev.screenshot(arg or "/tmp/pos-probe.png")
+ print(f"wrote {arg or '/tmp/pos-probe.png'}")
+ return 0
+ elif cmd == "log":
+ log = dev.logcat(lines=int(arg or 120))
+ for line in log.splitlines():
+ if any(t in line for t in ("taler-pos", "ConfigManager", "ConfigFragment",
+ "PaymentManager", "HistoryManager",
+ "RefundManager", "OrderManager", "PosSimHooks",
+ "AndroidRuntime", "taler-wallet-hce")):
+ print(line)
+ return 0
+ elif cmd != "dump":
+ print(__doc__)
+ return 2
+
+ screen = dev.dump()
+ print(f"activity: {screen.activity}")
+ print(f"window: {dev.size()}")
+ print(f"nodes: {len(screen.nodes)} labelled: {len(screen.labelled())} "
+ f"tappable: {len(screen.tappable())} editable: {len(screen.editable())}")
+ print(screen)
+ anonymous = screen.unnamed_clickables()
+ if anonymous:
+ print(f"-- {len(anonymous)} clickable(s) with no accessible name:")
+ for node in anonymous:
+ print(f" {node}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/pos-simulator/driver/qrposter.py b/pos-simulator/driver/qrposter.py
@@ -0,0 +1,124 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Show the terminal a QR code through its camera, for real.
+
+The emulator's virtual scene can hang a PNG on its wall, and the back camera
+sees it. That is the only way to exercise the scan path end to end -- the
+analyzer, the stride handling, the rotation, the decode and the parse -- rather
+than synthesising the URI the scanner would have produced.
+
+The poster can only be set when the emulator launches, so there is one boot per
+code.
+
+ python3 qrposter.py --uri 'taler-pos://host/instances/x#token' --worker 2
+ python3 qrposter.py --demo --worker 2 # a setup URI for the demo instance
+
+It prints whether the terminal provisioned itself from what it saw.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import merchant
+from device import Device, serial_for
+from pos import Pos, PosError
+
+SIM_ROOT = Path(os.environ.get("POS_SIM_ROOT", "/tmp/taler-pos-sim"))
+EMU = Path(__file__).resolve().parent.parent / "emu" / "emu.sh"
+
+
+def render(uri: str, path: Path) -> Path:
+ """A QR code the virtual scene will actually hang on its wall.
+
+ Two things matter and neither is obvious from a failure, because the
+ emulator says nothing and shows its default poster instead.
+
+ The image has to be a true-colour PNG. `qrencode` writes a 1-bit
+ palette PNG, which the scene's texture loader ignores -- the wall keeps
+ its default checkerboard and the terminal spends its whole run looking at
+ a calibration pattern. So it is converted to 24-bit RGB.
+
+ And it has to have room around it. The wall is two metres square and the
+ camera sees it at an angle, so a code that fills the poster edge to edge
+ loses its quiet zone to the frame; `-s 12 -m 6` leaves enough.
+ """
+ path.parent.mkdir(parents=True, exist_ok=True)
+ raw = path.with_suffix(".raw.png")
+ subprocess.run(["qrencode", "-o", str(raw), "-s", "12", "-m", "6",
+ "-l", "M", uri], check=True)
+ subprocess.run(["convert", str(raw), "-type", "TrueColor",
+ "PNG24:" + str(path)], check=True)
+ raw.unlink(missing_ok=True)
+ return path
+
+
+def main(argv: list[str]) -> int:
+ ap = argparse.ArgumentParser(description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--uri", default=None)
+ ap.add_argument("--demo", action="store_true",
+ help="render a setup URI for the demo sandbox instance")
+ ap.add_argument("--worker", type=int,
+ default=int(os.environ.get("POS_WORKER", "0")))
+ ap.add_argument("--apk", default=None)
+ ap.add_argument("--keep-up", action="store_true",
+ help="do not reboot; the poster is already on the wall")
+ args = ap.parse_args(argv)
+
+ uri = args.uri
+ if args.demo or not uri:
+ inst = merchant.demo()
+ uri = inst.setup_uri()
+ print(f"setup URI for {inst.label}: {uri[:80]}...")
+ poster = render(uri, SIM_ROOT / "run" / f"poster-w{args.worker}.png")
+ print(f"poster: {poster} ({poster.stat().st_size} bytes)")
+
+ env = dict(os.environ)
+ env["POS_SIM_ROOT"] = str(SIM_ROOT)
+ if not args.keep_up:
+ subprocess.run([str(EMU), "kill", str(args.worker)], env=env, check=False)
+ subprocess.run([str(EMU), "boot", str(args.worker), str(poster)],
+ env=env, check=True)
+ prepare = [str(EMU), "prepare", str(args.worker)]
+ if args.apk:
+ prepare += [args.apk]
+ subprocess.run(prepare, env=env, check=True)
+
+ dev = Device(serial_for(args.worker))
+ app = Pos(dev)
+ app.fresh_start()
+ print("selecting the QR tab and waiting for the camera to read the wall")
+ try:
+ app.provision_by_qr(timeout=180)
+ except (PosError, TimeoutError) as e:
+ screen = dev.dump()
+ print(f"NOT PROVISIONED: {e}")
+ print(f"activity: {screen.activity}")
+ print(f"screen: {screen.texts()[:12]}")
+ return 1
+ bound, url = app.bound_instance()
+ print(f"PROVISIONED from the camera: instance {bound!r}, url {url!r}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/pos-simulator/driver/report.py b/pos-simulator/driver/report.py
@@ -0,0 +1,131 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Summarise episode directories and the findings in them.
+
+ python3 report.py the newest run
+ python3 report.py 'suite-2026*' every run matching
+ python3 report.py --notes with what each scenario arranged
+ python3 report.py --kinds findings grouped by kind
+ python3 report.py --unreached only the scenarios that failed to
+ reach their feature
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from collections import Counter, defaultdict
+from pathlib import Path
+
+SIM_ROOT = Path(os.environ.get("POS_SIM_ROOT", "/tmp/taler-pos-sim"))
+OUT = SIM_ROOT / "out"
+
+# Kinds that only describe the terminal refusing or waiting; see oracles.py.
+INFORMATIONAL = {"error-dialog", "harness-crash", "slow-screen",
+ "logged-backend-error", "empty-hierarchy"}
+
+
+def episodes(patterns: list[str]) -> list[Path]:
+ roots: list[Path] = []
+ if not patterns:
+ runs = sorted((p for p in OUT.iterdir() if p.is_dir()),
+ key=lambda p: p.stat().st_mtime)
+ roots = runs[-1:]
+ else:
+ for pattern in patterns:
+ roots += sorted(OUT.glob(pattern))
+ out = []
+ for root in roots:
+ for path in sorted(root.iterdir()):
+ if path.is_dir() and (path / "summary.json").exists():
+ out.append(path)
+ return out
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("patterns", nargs="*")
+ ap.add_argument("--notes", action="store_true")
+ ap.add_argument("--kinds", action="store_true")
+ ap.add_argument("--unreached", action="store_true")
+ ap.add_argument("--evidence", action="store_true",
+ help="print each finding's evidence, not just its claim")
+ args = ap.parse_args()
+
+ paths = episodes(args.patterns)
+ if not paths:
+ print(f"no episodes under {OUT}")
+ return 1
+
+ by_kind: dict[str, list[tuple[str, dict]]] = defaultdict(list)
+ outcomes: Counter[str] = Counter()
+ total_serious = 0
+
+ for path in paths:
+ summary = json.loads((path / "summary.json").read_text())
+ outcome = summary.get("outcome", "?")
+ outcomes[outcome] += 1
+ findings = summary.get("findings", [])
+ serious = [f for f in findings if f["kind"] not in INFORMATIONAL]
+ total_serious += len(serious)
+ for f in findings:
+ by_kind[f["kind"]].append((summary["name"], f))
+ if args.unreached and outcome == "unreached":
+ print(f"{summary['name']} ({summary.get('seconds', 0):.0f}s)")
+ print(f" {summary.get('error', '')}")
+ for check in summary.get("checks", [])[-3:]:
+ print(f" reached: {check}")
+ continue
+ if args.unreached or args.kinds:
+ continue
+ print(f"{outcome:<14} {summary['name']:<38} "
+ f"{summary.get('seconds', 0):>6.0f}s "
+ f"{len(summary.get('checks', []))} check(s), "
+ f"{len(serious)}/{len(findings)} serious")
+ if summary.get("error"):
+ print(f" ! {summary['error'][:200]}")
+ for f in findings:
+ mark = "*" if f["kind"] not in INFORMATIONAL else "-"
+ print(f" {mark} [{f['kind']}] {f['detail'][:220]}")
+ if args.evidence and f.get("evidence"):
+ for line in f["evidence"].splitlines()[:8]:
+ print(f" {line[:200]}")
+ if args.notes:
+ for note in summary.get("notes", []):
+ print(f" . {note[:220]}")
+ print()
+
+ if args.kinds:
+ for kind, rows in sorted(by_kind.items(), key=lambda kv: -len(kv[1])):
+ mark = "*" if kind not in INFORMATIONAL else "-"
+ print(f"{mark} {kind} ({len(rows)})")
+ seen = set()
+ for name, f in rows:
+ key = f["detail"][:120]
+ if key in seen:
+ continue
+ seen.add(key)
+ print(f" {name}: {f['detail'][:200]}")
+ print()
+
+ print(f"{len(paths)} episode(s): "
+ + ", ".join(f"{n} {k}" for k, n in outcomes.most_common())
+ + f"; {total_serious} serious finding(s)")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/pos-simulator/driver/smoke.py b/pos-simulator/driver/smoke.py
@@ -0,0 +1,127 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Does any of this work at all?
+
+Six checks, in the order in which a failure stops being the harness's fault
+and starts being the terminal's. Run this after every deploy; a scenario
+failing on a harness that never passed its smoke test says nothing.
+
+ python3 smoke.py all of it
+ python3 smoke.py provision pay just those
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+import counterparty
+import merchant
+from device import Device, serial_for
+from pos import Pos
+
+WORKER = int(os.environ.get("POS_WORKER", "0"))
+SERIAL = serial_for(WORKER)
+
+
+def check_device(dev: Device, app: Pos) -> None:
+ screen = dev.dump()
+ assert screen.nodes, "no view hierarchy at all -- is the emulator up?"
+ w, h = dev.size()
+ assert w > h, f"the window is {w}x{h}; the terminal is landscape-locked"
+ print(f" ok device {dev.serial}, API {dev.sdk_int}, window {w}x{h}")
+
+
+def check_hooks(dev: Device) -> None:
+ import coverage
+ dev.paste_text("pos-simulator smoke")
+ path = coverage.dump(dev, f"/tmp/pos-smoke-{dev.serial}.ec", name="smoke.ec")
+ size = path.stat().st_size
+ assert size > 1000, f"coverage dump is only {size} bytes"
+ print(f" ok sim hooks: clipboard, and {size} bytes of coverage")
+
+
+def check_backend() -> merchant.Instance:
+ inst = merchant.demo()
+ pos = inst.merchant.pos_config(inst.token.value)
+ products = len(pos.get("products", []))
+ assert products, "the instance has no products; the inventory screen has nothing to show"
+ print(f" ok backend {inst.label}: {inst.currency}, {products} products, "
+ f"{len(inst.merchant.accounts(inst.token.value))} bank accounts")
+ return inst
+
+
+def check_provision(dev: Device, app: Pos, inst: merchant.Instance) -> None:
+ app.fresh_start()
+ app.provision_by_uri(inst.setup_uri())
+ rows = app.about_rows()
+ assert rows.get("Username") == inst.merchant.instance, \
+ f"the terminal says it is bound to {rows.get('Username')!r}"
+ print(f" ok provisioned by setup URI: {rows}")
+
+
+def check_order(dev: Device, app: Pos, inst: merchant.Instance) -> str:
+ app.goto("amount")
+ app.enter_amount("1.00")
+ app.charge()
+ uri = app.displayed_pay_uri()
+ assert uri, "the payment screen offers no pay URI over NFC"
+ print(f" ok order billed, terminal offers {uri[:70]}...")
+ return uri
+
+
+def check_pay(dev: Device, app: Pos, inst: merchant.Instance, uri: str) -> None:
+ wallet, account = counterparty.customer(
+ db_dir=os.environ.get("POS_WALLET_DIR", "/tmp/pos-sim-wallets"))
+ if not wallet.has_at_least(f"{inst.currency}:2"):
+ print(f" funding the customer wallet ({wallet.available(inst.currency)})")
+ wallet.withdraw(account, f"{inst.currency}:20")
+ wallet.pay(uri)
+ app.wait_for_success()
+ print(f" ok the customer paid and the terminal said so")
+
+
+def main(argv: list[str]) -> int:
+ want = set(argv) or {"device", "hooks", "backend", "provision", "order", "pay"}
+ dev = Device(SERIAL)
+ app = Pos(dev)
+ inst = None
+ uri = None
+ try:
+ if "device" in want:
+ check_device(dev, app)
+ if "hooks" in want:
+ check_hooks(dev)
+ if "backend" in want or {"provision", "order", "pay"} & want:
+ inst = check_backend()
+ if "provision" in want:
+ check_provision(dev, app, inst)
+ if "order" in want or "pay" in want:
+ uri = check_order(dev, app, inst)
+ if "pay" in want:
+ check_pay(dev, app, inst, uri)
+ except Exception as e:
+ print(f" FAIL {type(e).__name__}: {e}")
+ try:
+ print(f" screen: {dev.dump().texts()}")
+ except Exception:
+ pass
+ return 1
+ print("smoke test passed")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/pos-simulator/driver/suite.py b/pos-simulator/driver/suite.py
@@ -0,0 +1,4581 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""The scenarios: one feature each, walked deliberately.
+
+A scenario that cannot reach its feature fails loudly (`Ctx.require`) rather
+than reporting a green row for having done nothing. That is the whole
+discipline here: a passing row has to mean the terminal was actually put
+through the thing the row is named after.
+
+ python3 suite.py --list
+ python3 suite.py login_demo_credentials order_amount_pay
+ python3 suite.py --all
+ python3 suite.py --tag mock only the ones that need the mock
+ python3 suite.py --all --skip-tag pay leave the slow ones out
+
+Tags say what a scenario needs:
+
+ demo the public demo backend and its `sandbox` instance
+ mock a merchant backend of the harness's own, on TLS (backend/mockd.py)
+ pay a funded customer wallet, so the scenario can settle a payment
+ fault `taler-twister` in front of a real backend, breaking its replies
+ slow minutes rather than seconds
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import threading
+import time
+import urllib.parse
+import traceback
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Iterable, Optional
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "backend"))
+
+import counterparty
+import faults
+import merchant
+import mockd
+import oracles
+from device import Device, serial_for
+from episode import Action, Episode
+from pos import (
+ MARK_AMOUNT, MARK_CHECKOUT, MARK_CHECKOUT_PAD, MARK_CONFIG, MARK_FETCHING,
+ MARK_HISTORY, MARK_ORDER, MARK_PAYMENT, MARK_REFUND_FORM, MARK_REFUND_URI,
+ MARK_SUCCESS, APPROVE_REFUND, BILL_BUTTON,
+ Dialog, Pos, PosError,
+)
+
+# "Merchant portal URL" is the login form's field label -- and also a row in
+# the Settings screen's About block, which reads "Merchant portal URL:
+# https://...". So it cannot stand for "the terminal is back on the login
+# form": Settings matches it too, and a scenario checking that logging out was
+# cancelled reported that it had not been. The Connect button is only on the
+# login form.
+AT_LOGIN = r"^Connect$|^Manual config$"
+
+SIM_ROOT = Path(os.environ.get("POS_SIM_ROOT", "/tmp/taler-pos-sim"))
+WORKER = int(os.environ.get("POS_WORKER", "0"))
+SERIAL = serial_for(WORKER)
+MOCK_PORT = int(os.environ.get("POS_MOCK_PORT", str(19443 + WORKER)))
+# twister's own HTTP port is never reached from the device: the terminal talks
+# to the TLS front, which relays to it. Only the front is reversed into the
+# emulator.
+TWISTER_PORT = int(os.environ.get("POS_TWISTER_PORT", str(18880 + WORKER)))
+FRONT_PORT = int(os.environ.get("POS_FRONT_PORT", str(19473 + WORKER)))
+# Whether this process is the only one using the shared `sandbox` instance.
+# Two workers on it at once each see the other's orders, which is harmless for
+# most scenarios and fatal for the few that count what the backend gained
+# while they ran: those say so and skip the count rather than report the other
+# worker's orders as the app's fault. The campaign sets it.
+EXCLUSIVE_DEMO = os.environ.get("POS_EXCLUSIVE_DEMO", "1") != "0"
+
+
+class ScenarioFailure(AssertionError):
+ """The scenario could not establish what it set out to test."""
+
+
+@dataclass
+class Mock:
+ """A mock merchant backend running for one scenario."""
+
+ state: mockd.MockState
+ port: int
+ instance: str
+
+ @property
+ def host(self) -> str:
+ return f"localhost:{self.port}"
+
+ @property
+ def merchant_url(self) -> str:
+ return f"https://{self.host}/instances/{self.instance}"
+
+
+@dataclass
+class Ctx:
+ """Everything a scenario is handed."""
+
+ dev: Device
+ app: Pos
+ ep: Episode
+ name: str
+ _demo: Optional[merchant.Instance] = None
+ _customer: Optional[tuple[counterparty.Wallet, counterparty.BankAccount]] = None
+ mock: Optional[Mock] = None
+ tw: Optional[faults.Twister] = None
+ checks: list[str] = field(default_factory=list)
+
+ # -- assertions -------------------------------------------------------
+
+ def require(self, condition: bool, message: str) -> None:
+ """What the scenario needed to be true to have tested anything."""
+ if not condition:
+ raise ScenarioFailure(message)
+ self.checks.append(message)
+
+ def expect(self, condition: bool, kind: str, detail: str,
+ evidence: str = "") -> bool:
+ """What the terminal was supposed to do. A failure is a finding.
+
+ The difference from `require` matters: `require` guards the harness
+ ("I could not get to the payment screen, so I have tested nothing"),
+ `expect` judges the app ("I got there and it was wrong").
+ """
+ if condition:
+ self.checks.append(f"{kind}: ok")
+ return True
+ self.ep.judge([oracles.Finding(kind, detail, evidence)])
+ return False
+
+ # -- lazily acquired counterparties -----------------------------------
+
+ def demo(self, seconds: Optional[int] = None) -> merchant.Instance:
+ """The demo backend, with a token of the requested lifetime."""
+ if seconds is not None or self._demo is None:
+ self._demo = merchant.demo(seconds=seconds)
+ self.ep.note(f"demo token: {self._demo.token}")
+ return self._demo
+
+ def customer(self) -> tuple[counterparty.Wallet, counterparty.BankAccount]:
+ """This worker's customer: one wallet and one bank account per worker.
+
+ Not one shared between them. Three workers paying from the same
+ `taler-wallet-cli` database take turns at an sqlite file none of them
+ locks, and they spend each other's coins: the symptom is one worker
+ topping the wallet up to 60 and another failing the next payment with
+ "insufficient balance", reported as a harness error in whichever
+ scenario happened to be next.
+ """
+ if self._customer is None:
+ # "possim1" is already somebody else's account on the public
+ # demo bank, and the password derived from the name does not open
+ # it; the per-worker names are spelt out so they do not collide
+ # with whatever short name a passer-by has taken.
+ self._customer = counterparty.customer(
+ name="possim" if not WORKER else f"possim-w{WORKER}",
+ db_dir=str(SIM_ROOT / "run" / f"wallets-w{WORKER}"))
+ return self._customer
+
+ def funded_customer(self, currency: str, amount: str = "60"
+ ) -> counterparty.Wallet:
+ """A wallet with money in it, topped up before it runs dry.
+
+ The threshold is generous on purpose. A wallet that still holds
+ slightly more than the next order costs a withdrawal every scenario,
+ and a wallet that holds slightly less fails the payment with
+ "insufficient balance" -- which is reported as a harness error several
+ steps after the scenario it actually spoils.
+ """
+ wallet, account = self.customer()
+ want = f"{currency}:15"
+ if not wallet.has_at_least(want):
+ self.ep.note(f"topping the customer wallet up to {currency}:{amount}")
+ wallet.withdraw(account, f"{currency}:{amount}")
+ self.require(wallet.has_at_least(want),
+ f"the customer has at least {want} to spend")
+ return wallet
+
+ # -- convenience ------------------------------------------------------
+
+ def observe(self) -> None:
+ self.ep.observe()
+
+ def provision_demo(self, style: str = "path",
+ seconds: Optional[int] = None) -> merchant.Instance:
+ """A terminal bound to the demo instance, ready to take an order."""
+ inst = self.demo(seconds=seconds)
+ self.app.fresh_start()
+ self.app.provision_by_uri(inst.setup_uri(style=style))
+ self.ep.observe()
+ return inst
+
+ def provision_mock(self, profile: str, instance: str = "mockshop",
+ expect_success: bool = True, need_form: bool = False):
+ """Start a mock backend with the given profile and point the terminal at it.
+
+ `need_form` is for the scenarios that are *about* the login form --
+ the two-factor challenges and the token-prefix retry both live in
+ `POST /private/token`, which a setup URI never sends. Those cannot be
+ routed around the broken phone form, so on a phone they say so and
+ stop rather than quietly testing a different code path and reporting
+ the difference as the app's fault.
+ """
+ self.mock = start_mock(profile, MOCK_PORT, instance)
+ self.dev.adb("reverse", f"tcp:{self.mock.port}", f"tcp:{self.mock.port}",
+ check=False)
+ self.ep.note(f"mock backend profile {profile!r} on {self.mock.merchant_url}")
+ self.app.fresh_start()
+ # On a phone the login form is unusable -- the keyboard takes the
+ # whole form with it, fields and Connect and all, and nothing
+ # scrolls (see findings/login-form-collapses-under-the-keyboard.md).
+ # A setup URI carries the port now that master preserves it, so the
+ # rest of the mock set is testable there; the form itself is judged
+ # by a scenario of its own rather than quietly worked around.
+ if self.dev.is_phone_layout() and need_form:
+ raise ScenarioFailure(
+ "this scenario needs the login form, and the form is unusable "
+ "on a phone -- see findings/login-form-collapses-under-the-"
+ "keyboard.md; run it on a tablet-sized worker")
+ if self.dev.is_phone_layout():
+ uri = (f"taler-pos://{self.mock.host}/instances/{instance}"
+ f"#mock-secret")
+ self.ep.note(f"provisioning by setup URI instead: {uri}")
+ return self.app.provision_by_uri(
+ uri, expect_success=expect_success)
+ return self.app.provision_by_form(
+ self.mock.host, instance, "mock-secret",
+ expect_success=expect_success)
+
+ def provision_twister(self, chaos: int = 0, expect_success: bool = True,
+ arm_during_login: tuple = ()) -> faults.Twister:
+ """A terminal bound to the demo instance *through* twister.
+
+ The login form rather than a setup URI, for two reasons: the form is
+ the only path that mints the terminal's own token through
+ `POST /private/token`, and a `taler-pos://` URI loses the port (round
+ one, finding 7) which a proxy on a non-default port cannot survive.
+
+ `arm_during_login` is for faults that have to be in place before the
+ terminal has a session at all; everything after login is better armed
+ one request at a time, because a post-login action makes exactly one
+ request and the mutation lands on it.
+ """
+ if not faults.available():
+ raise ScenarioFailure(
+ f"no taler-twister at {faults.SERVICE}; see README (it is built "
+ f"on the emulator host against the system GNUnet)")
+ self.tw = start_twister(merchant.DEMO_BASE.rstrip("/"), TWISTER_PORT, FRONT_PORT,
+ chaos=chaos, run_dir=SIM_ROOT / "run")
+ self.dev.adb("reverse", f"tcp:{FRONT_PORT}", f"tcp:{FRONT_PORT}", check=False)
+ self.ep.note(f"twister in front of {merchant.DEMO_BASE} on {self.tw.host}"
+ + (f", chaos {chaos}%" if chaos else ""))
+ self.app.fresh_start()
+ if arm_during_login:
+ with self.tw.sustain(*arm_during_login):
+ self.app.provision_by_form(
+ self.tw.host, merchant.DEMO_INSTANCE, merchant.DEMO_SECRET,
+ expect_success=expect_success)
+ else:
+ self.app.provision_by_form(
+ self.tw.host, merchant.DEMO_INSTANCE, merchant.DEMO_SECRET,
+ expect_success=expect_success)
+ return self.tw
+
+ @property
+ def front(self) -> faults.TlsFront:
+ """The TLS front, for faults that happen below HTTP."""
+ assert self.tw is not None, "no twister in this scenario"
+ return faults.front_of(self.tw)
+
+
+# -- the mock, started in-process ----------------------------------------
+
+_running_mocks: list[tuple[object, threading.Thread]] = []
+
+
+def start_mock(profile: str, port: int, instance: str) -> Mock:
+ """Run a mock backend in a thread for the duration of one scenario.
+
+ The previous one is shut down first. A suite process runs several mock
+ scenarios in a row and each wants its own profile, so leaving the last
+ server listening would take the port with it and the next scenario would
+ talk to the wrong backend -- or fail to bind and look like a harness
+ error.
+ """
+ stop_mocks()
+ server, state = mockd.build_server(profile, port, instance,
+ f"localhost:{port}")
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
+ thread.start()
+ _running_mocks.append((server, thread))
+ # Wait for it to actually answer, rather than for the thread to exist.
+ import socket
+ import ssl as _ssl
+ deadline = time.monotonic() + 20
+ while time.monotonic() < deadline:
+ try:
+ ctx = _ssl.create_default_context(
+ cafile=str(Path(__file__).resolve().parent.parent / "tls" / "ca.crt"))
+ with socket.create_connection(("127.0.0.1", port), timeout=2) as raw:
+ with ctx.wrap_socket(raw, server_hostname="localhost"):
+ return Mock(state=state, port=port, instance=instance)
+ except OSError:
+ time.sleep(0.5)
+ raise ScenarioFailure(f"the mock backend did not come up on port {port}")
+
+
+_running_twisters: list[faults.Twister] = []
+
+
+def start_twister(destination: str, port: int, front_port: int, chaos: int,
+ run_dir: Path) -> faults.Twister:
+ """Run twister and its TLS front for the duration of one scenario."""
+ stop_twisters()
+ tw = faults.Twister(destination=destination, port=port, front_port=front_port,
+ run_dir=run_dir, chaos=chaos)
+ tw.start()
+ _running_twisters.append(tw)
+ return tw
+
+
+def stop_twisters() -> None:
+ while _running_twisters:
+ try:
+ _running_twisters.pop().stop()
+ except Exception:
+ pass
+
+
+def stop_mocks() -> None:
+ while _running_mocks:
+ server, thread = _running_mocks.pop()
+ try:
+ server.shutdown() # type: ignore[attr-defined]
+ server.server_close() # type: ignore[attr-defined]
+ except Exception:
+ pass
+ thread.join(timeout=5)
+
+
+# -- the registry ---------------------------------------------------------
+
+SCENARIOS: dict[str, tuple[Callable[[Ctx], None], tuple[str, ...], str]] = {}
+
+
+def scenario(*tags: str):
+ def wrap(fn: Callable[[Ctx], None]):
+ doc = (fn.__doc__ or "").strip().splitlines()[0] if fn.__doc__ else ""
+ SCENARIOS[fn.__name__] = (fn, tags, doc)
+ return fn
+ return wrap
+
+
+# =========================================================================
+# provisioning
+# =========================================================================
+
+
+@scenario("demo")
+def login_demo_credentials(c: Ctx) -> None:
+ """The terminal's own "Fill demo credentials" button, end to end."""
+ c.app.fresh_start()
+ screen = c.app.fill_demo_credentials()
+ c.require(screen.find(r"backend\.demo\.taler\.net"),
+ "the demo button filled in the demo host")
+ c.observe()
+ c.app.tap_button(r"^Connect$")
+ screen = c.app.wait_for_order_entry()
+ c.observe()
+ instance, url = c.app.bound_instance()
+ c.expect(instance == "sandbox",
+ "demo-credentials-wrong-instance",
+ f"the demo credentials button bound the terminal to {instance!r}")
+ c.require(bool(url and "backend.demo.taler.net" in url),
+ f"the terminal is bound to the demo backend ({url})")
+
+
+@scenario("demo")
+def login_manual_form(c: Ctx) -> None:
+ """Typing the merchant URL, instance and password into the login form."""
+ inst = c.demo()
+ c.app.fresh_start()
+ c.app.provision_by_form("backend.demo.taler.net", inst.merchant.instance,
+ merchant.DEMO_SECRET)
+ c.observe()
+ instance, url = c.app.bound_instance()
+ c.require(instance == inst.merchant.instance,
+ f"the form bound the terminal to {instance!r}")
+
+
+@scenario("demo")
+def login_wrong_password(c: Ctx) -> None:
+ """A wrong password has to be refused, and say which thing was wrong."""
+ c.app.fresh_start()
+ screen = c.app.provision_by_form(
+ "backend.demo.taler.net", "sandbox", "definitely-not-the-password",
+ expect_success=False)
+ c.observe()
+ dialog = c.app.read_dialog(screen)
+ c.require(dialog is not None,
+ "the terminal said something about the wrong password")
+ c.ep.note(f"dialog: {dialog}")
+ c.expect(bool(re.search(r"(?i)username or password|invalid", dialog.message
+ or dialog.title)),
+ "wrong-password-message-unhelpful",
+ f"a wrong password produced {dialog}",
+ str(dialog))
+ c.app.dismiss_dialog()
+ c.observe()
+ screen = c.dev.dump()
+ c.expect(bool(screen.find(AT_LOGIN)),
+ "stuck-after-auth-error",
+ "after refusing the password the terminal is not back on the "
+ "login form",
+ " | ".join(screen.texts()))
+
+
+@scenario("demo")
+def login_unknown_host(c: Ctx) -> None:
+ """A host that does not resolve: the terminal must not leak the exception."""
+ c.app.fresh_start()
+ screen = c.app.provision_by_form(
+ "not-a-real-merchant.invalid", "sandbox", "sandbox",
+ expect_success=False)
+ time.sleep(6)
+ c.observe()
+ dialog = c.app.read_dialog()
+ c.require(dialog is not None, "the terminal reported the unreachable host")
+ c.ep.note(f"dialog: {dialog}")
+ c.expect(not re.search(r"(?i)exception|java\.|ktor|unknownhost",
+ f"{dialog.title} {dialog.message}"),
+ "exception-in-dialog",
+ f"the unreachable-host dialog quotes an exception: {dialog}",
+ str(dialog))
+
+
+@scenario("demo")
+def login_url_shapes(c: Ctx) -> None:
+ """URLs a merchant might plausibly paste, and what the terminal makes of them.
+
+ The form normalises what it is given -- it prepends https, strips a path,
+ keeps a port and lifts an instance out of `/instances/<id>` -- so each
+ shape should end up at the same place. What is checked is that it does,
+ and that nothing in between is shown to the user raw.
+ """
+ shapes = [
+ ("backend.demo.taler.net", "sandbox"),
+ ("https://backend.demo.taler.net", "sandbox"),
+ ("backend.demo.taler.net/", "sandbox"),
+ ("https://backend.demo.taler.net/instances/sandbox", None),
+ ("BACKEND.DEMO.TALER.NET", "sandbox"),
+ (" backend.demo.taler.net ", "sandbox"),
+ ]
+ reached = 0
+ for host, instance in shapes:
+ c.app.fresh_start()
+ c.ep.note(f"url shape {host!r}, instance {instance!r}")
+ try:
+ c.app.provision_by_form(host, instance or "", merchant.DEMO_SECRET)
+ except (PosError, TimeoutError) as e:
+ screen = c.dev.dump()
+ dialog = c.app.read_dialog(screen)
+ c.ep.judge([oracles.Finding(
+ "url-shape-rejected",
+ f"the form could not log in with the merchant URL {host!r} "
+ f"(instance {instance!r}): {dialog or str(e)[:200]}",
+ " | ".join(screen.texts())[:600])])
+ continue
+ reached += 1
+ bound_instance, url = c.app.bound_instance()
+ c.expect(bound_instance == "sandbox",
+ "url-shape-wrong-instance",
+ f"{host!r} bound the terminal to instance {bound_instance!r}")
+ c.observe()
+ c.require(reached > 0, "at least one URL shape logged in")
+
+
+@scenario("demo")
+def provision_setup_uri_styles(c: Ctx) -> None:
+ """Both shapes of `taler-pos://` setup URI, which are parsed by different code."""
+ inst = c.demo()
+ for style in ("path", "params"):
+ c.app.fresh_start()
+ uri = inst.setup_uri(style=style)
+ c.ep.note(f"{style} style: {uri[:80]}...")
+ c.app.provision_by_uri(uri)
+ c.observe()
+ bound, url = c.app.bound_instance()
+ c.expect(bound == inst.merchant.instance,
+ "setup-uri-wrong-instance",
+ f"the {style}-style setup URI bound the terminal to {bound!r}")
+ c.require(bool(url), f"the {style}-style setup URI configured the terminal")
+
+
+@scenario("demo")
+def provision_setup_uri_malformed(c: Ctx) -> None:
+ """Setup URIs that are wrong in one way each.
+
+ None of them should configure anything, and none should crash: the parser
+ returns early on a missing piece, so what is being checked is that every
+ early return leaves a usable screen behind.
+ """
+ inst = c.demo()
+ host = "backend.demo.taler.net"
+ token = inst.token.value
+ cases = {
+ "no token": f"taler-pos://{host}/instances/sandbox",
+ "no instance": f"taler-pos://{host}#{token}",
+ "empty instance": f"taler-pos://{host}/instances/#{token}",
+ "blank token": f"taler-pos://{host}/instances/sandbox#",
+ "no host": f"taler-pos:///instances/sandbox#{token}",
+ "wrong scheme": f"taler-pos-x://{host}/instances/sandbox#{token}",
+ "params, no password": f"taler-pos://{host}#username=sandbox",
+ "params, no username": f"taler-pos://{host}#password={token}",
+ "path but no segments": f"taler-pos://{host}/#{token}",
+ }
+ c.app.fresh_start()
+ for label, uri in cases.items():
+ c.ep.note(f"malformed setup URI ({label}): {uri[:90]}")
+ c.ep.perform(Action("setup_uri", uri))
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ if not screen.activity.startswith("net.taler.merchantpos"):
+ c.ep.judge([oracles.Finding(
+ "setup-uri-left-the-app",
+ f"a setup URI with {label} left the terminal showing "
+ f"{screen.activity}",
+ uri)])
+ c.dev.launch()
+ time.sleep(3)
+ continue
+ # A dialog is its own window and dumps alone, so the login form behind
+ # it is not in the hierarchy: read the dialog, close it, and judge
+ # what is left rather than what the dialog hid.
+ dialog = c.app.read_dialog(screen)
+ if dialog is not None:
+ c.ep.note(f"{label}: {dialog}")
+ c.app.dismiss_dialog()
+ screen, _ = c.ep.observe()
+ c.expect(bool(screen.find(AT_LOGIN)) or
+ bool(screen.find(r"Fetching configuration")),
+ "setup-uri-dead-end",
+ f"a setup URI with {label} left the terminal on a screen with "
+ f"no way back: {screen.texts()[:10]}",
+ uri)
+ if screen.find(r"Fetching configuration"):
+ # A URI that got as far as fetching with half a credential; give it
+ # time to fail and make sure it says so rather than spinning.
+ time.sleep(12)
+ screen, _ = c.ep.observe()
+ c.expect(not screen.find(r"Fetching configuration"),
+ "stuck-fetching-after-bad-uri",
+ f"a setup URI with {label} left the terminal fetching "
+ f"configuration forever",
+ uri)
+ c.app.dismiss_dialog()
+ c.require(True, "every malformed setup URI was delivered")
+
+
+@scenario("demo", "slow")
+def provision_port_is_dropped(c: Ctx) -> None:
+ """A setup URI for a backend on a non-default port.
+
+ `MainActivity.handleSetupIntent` rebuilds the merchant URL from
+ `data.host`, which is the host *without* the port, so a merchant whose
+ backend does not listen on 443 cannot be provisioned by QR code at all.
+ The login form keeps the port, so the two paths disagree -- which is what
+ this checks.
+ """
+ uri = f"taler-pos://backend.demo.taler.net:443/instances/sandbox#{c.demo().token.value}"
+ c.app.fresh_start()
+ c.ep.note(f"setup URI with an explicit port: {uri[:90]}")
+ try:
+ c.app.provision_by_uri(uri)
+ _, url = c.app.bound_instance()
+ c.ep.note(f"bound to {url}")
+ c.expect(bool(url and ":443" in url),
+ "setup-uri-drops-the-port",
+ f"a setup URI naming port 443 configured the terminal as "
+ f"{url}, with the port dropped; a backend on any other port "
+ f"cannot be provisioned this way at all",
+ uri)
+ except (PosError, TimeoutError):
+ screen = c.dev.dump()
+ c.ep.judge([oracles.Finding(
+ "setup-uri-drops-the-port",
+ "a setup URI naming a port did not configure the terminal at all",
+ " | ".join(screen.texts())[:400])])
+ c.require(True, "a setup URI with a port was delivered")
+
+
+@scenario("demo", "phone")
+def config_qr_tab(c: Ctx) -> None:
+ """Selecting the QR tab on the login screen, which starts the camera."""
+ c.app.fresh_start()
+ screen = c.app.wait_for_config_screen()
+ c.require(bool(screen.find(r"^QR config$")), "the login screen offers a QR tab")
+ c.ep.perform(Action("tap_label", "QR config"))
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ alive = screen.activity.startswith("net.taler.merchantpos")
+ c.expect(alive, "qr-tab-crash",
+ f"selecting the QR configuration tab left the terminal showing "
+ f"{screen.activity or 'nothing'}: {screen.texts()[:8]}",
+ " | ".join(screen.texts())[:600])
+ c.require(True, "the QR tab was selected")
+ if alive:
+ c.expect(bool(screen.find(r"Scan the QR code|Camera permission")),
+ "qr-tab-blank",
+ f"the QR tab shows neither a hint nor a permission message: "
+ f"{screen.texts()[:8]}")
+
+
+@scenario("demo")
+def config_qr_without_camera_permission(c: Ctx) -> None:
+ """The QR tab with the camera permission denied."""
+ c.app.fresh_start(grant_camera=False)
+ c.dev.revoke_camera()
+ c.app.relaunch()
+ c.app.wait_for_config_screen()
+ c.ep.perform(Action("tap_label", "QR config"))
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ # Asking for the permission is the right thing to do, and the system's
+ # permission dialog is its own activity -- so being there is not a crash.
+ asking = "permissioncontroller" in screen.activity.lower()
+ if asking:
+ c.ep.note(f"the terminal asked for the camera permission: "
+ f"{screen.texts()[:6]}")
+ deny = screen.find(r"(?i)^Don.t allow$|^Deny$")
+ if deny is not None:
+ c.dev.tap_node(deny, screen)
+ time.sleep(4)
+ screen, _ = c.ep.observe()
+ c.expect(screen.activity.startswith("net.taler.merchantpos") or asking,
+ "qr-tab-crash-without-permission",
+ f"the QR tab with no camera permission left the terminal showing "
+ f"{screen.activity or 'nothing'}",
+ " | ".join(screen.texts())[:500])
+ c.require(True, "the QR tab was selected without the camera permission")
+
+
+# =========================================================================
+# sessions and credentials
+# =========================================================================
+
+
+@scenario("demo", "slow")
+def token_expires_while_idle(c: Ctx) -> None:
+ """A session that ends while the terminal is sitting on the order screen.
+
+ The login form can only ask for a token that never expires, so the only
+ way to see this is to mint a short-lived one outside and provision with
+ it. What should happen is the "session expired" toast and a return to the
+ login screen; what must not happen is an unexplained failure on the next
+ thing the cashier touches.
+ """
+ inst = c.provision_demo(seconds=75)
+ left = inst.token.seconds_left or 0
+ c.require(left > 20, f"the token has {left:.0f}s left to run")
+ c.ep.note(f"waiting out a token with {left:.0f}s left")
+ time.sleep(max(0, left) + 10)
+ c.ep.note("the token has now expired")
+ # Something has to talk to the backend for the terminal to notice.
+ c.app.goto("history")
+ c.app.tap_button(r"Refresh history")
+ time.sleep(12)
+ screen, _ = c.ep.observe()
+ back_at_login = bool(screen.find(AT_LOGIN))
+ c.expect(back_at_login,
+ "expired-session-not-noticed",
+ f"the terminal kept working after its token expired instead of "
+ f"asking for credentials: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:600])
+ c.require(True, "the terminal was used after its token expired")
+
+
+@scenario("demo", "slow")
+def token_revoked_mid_payment(c: Ctx) -> None:
+ """The session ends while the payment screen is polling.
+
+ This is the sharpest version of the question, because `PaymentManager`
+ asserts its configuration: `configManager.merchantConfig!!` appears in
+ five of its methods, and the 401 interceptor sets that field to null the
+ moment a request comes back unauthorised. Cancelling the payment after
+ that is a null dereference on a non-null type.
+ """
+ inst = c.provision_demo()
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.app.charge()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"scan QR Code|Cancel payment")),
+ "the terminal is on the payment screen, polling")
+ inst.merchant.revoke_token(inst.token.value)
+ c.ep.note("the terminal's token has been revoked server side")
+ # The payment screen polls once a second, so the next poll gets a 401.
+ time.sleep(8)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"after revocation the screen shows: {screen.texts()[:8]}")
+ if screen.find(r"Cancel payment"):
+ c.ep.perform(Action("tap_label", "Cancel payment"))
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ crashed = not screen.activity.startswith("net.taler.merchantpos")
+ c.expect(not crashed,
+ "crash-after-session-lost",
+ f"cancelling a payment after the session was revoked left the "
+ f"terminal showing {screen.activity or 'nothing'}",
+ " | ".join(screen.texts())[:500])
+ c.require(True, "the session was revoked while a payment was in flight")
+
+
+@scenario("mock")
+def token_expires_mid_session_mock(c: Ctx) -> None:
+ """A backend that stops accepting the token after a few requests.
+
+ The same question as `token_expires_while_idle`, but without the waiting
+ and at a moment the harness picks exactly: the mock answers 401 from the
+ fourth authorised request on.
+ """
+ screen = c.provision_mock("expire-after-3", expect_success=False)
+ time.sleep(8)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"after provisioning: {screen.texts()[:10]}")
+ for _ in range(3):
+ if screen.find(r"Charge|Bill|Create order"):
+ break
+ time.sleep(4)
+ screen, _ = c.ep.observe()
+ if screen.find(r"Charge|Bill|Create order"):
+ c.app.goto("history")
+ c.app.tap_button(r"Refresh history")
+ time.sleep(8)
+ screen, _ = c.ep.observe()
+ c.require(bool(c.mock.state.paths()), "the terminal talked to the mock backend")
+ dialog = c.app.read_dialog(screen)
+ c.ep.note(f"screen: {screen.texts()[:10]}; dialog: {dialog}")
+ c.expect(bool(screen.find(AT_LOGIN) or dialog),
+ "expired-token-silent",
+ f"the token stopped working and the terminal neither said so nor "
+ f"went back to the login screen: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:600])
+
+
+@scenario("demo")
+def settings_logout_and_back(c: Ctx) -> None:
+ """Logging out, and logging in again afterwards."""
+ inst = c.provision_demo()
+ c.app.settings_logout()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(AT_LOGIN)),
+ "logging out returned the terminal to the login screen")
+ c.app.provision_by_uri(inst.setup_uri())
+ c.observe()
+ bound, _ = c.app.bound_instance()
+ c.require(bound == inst.merchant.instance,
+ "the terminal could be provisioned again after a logout")
+
+
+@scenario("demo")
+def settings_logout_cancelled(c: Ctx) -> None:
+ """Backing out of the logout confirmation must not log out."""
+ inst = c.provision_demo()
+ c.app.goto("settings")
+ c.app.tap_button(r"^Log out$")
+ time.sleep(1.5)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.require(dialog is not None, "logging out asks for confirmation")
+ c.ep.note(f"first logout dialog: {dialog}")
+ c.app.tap_button(r"^Cancel$")
+ time.sleep(2)
+ screen, _ = c.ep.observe()
+ c.expect(not screen.find(AT_LOGIN),
+ "cancelled-logout-logged-out",
+ "cancelling the logout dialog logged the terminal out anyway",
+ " | ".join(screen.texts())[:400])
+ bound, _ = c.app.bound_instance()
+ c.require(bound == inst.merchant.instance,
+ "the terminal is still bound to its instance")
+
+
+# =========================================================================
+# taking payment
+# =========================================================================
+
+
+@scenario("demo", "pay", "slow")
+def order_amount_pay(c: Ctx) -> None:
+ """Charge an amount on the keypad and have a real wallet pay it."""
+ inst = c.provision_demo()
+ wallet = c.funded_customer(inst.currency)
+ before = inst.merchant.history(inst.token.value, limit=-5)
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.ep.observe()
+ c.app.charge()
+ screen, _ = c.ep.observe()
+ uri = c.app.displayed_pay_uri()
+ c.require(bool(uri), "the terminal showed a pay URI the customer can use")
+ c.ep.note(f"pay URI: {uri}")
+ order_id = _order_id_from(uri)
+ c.require(bool(order_id), f"the pay URI names an order ({uri})")
+ backend_uri = inst.merchant.pay_uri(inst.token.value, order_id)
+ c.ep.judge(oracles.payment_code_usable(screen, uri, backend_uri))
+ c.expect(bool(c.app.published_nfc_uri()) is False,
+ "nfc-claimed-without-hardware",
+ "the terminal published an NFC payload on a device with no NFC "
+ "adapter")
+ wallet.pay(uri)
+ c.app.wait_for_success()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(MARK_SUCCESS)),
+ "the terminal showed the payment as received")
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.expect(status.get("order_status") == "paid",
+ "success-without-payment",
+ f"the terminal showed 'Payment received' while the backend says "
+ f"the order is {status.get('order_status')!r}",
+ json.dumps(status)[:600])
+ c.app.continue_from_success()
+ c.ep.observe()
+ after = inst.merchant.history(inst.token.value, limit=-5)
+ # Only when this process has the instance to itself: another worker's
+ # orders appear in this window as orders nobody collected, and the oracle
+ # would report them as the terminal's doing.
+ if EXCLUSIVE_DEMO:
+ c.ep.judge(oracles.orphaned_orders(before, after, allowed=[order_id]))
+ else:
+ c.ep.note("another worker shares this instance; not counting what it "
+ "gained")
+
+
+@scenario("demo", "pay", "slow")
+def order_inventory_pay(c: Ctx) -> None:
+ """Build an order from the product grid and have it paid."""
+ inst = c.provision_demo()
+ wallet = c.funded_customer(inst.currency)
+ screen = c.app.goto("inventory")
+ c.ep.observe()
+ c.require(bool(screen.find(r"^Bill( .*)?$")),
+ "the inventory screen offers a Bill button")
+ added = c.app.add_products(2)
+ c.ep.note(f"added products: {added}")
+ screen, _ = c.ep.observe()
+ c.app.bill()
+ screen, _ = c.ep.observe()
+ uri = c.app.displayed_pay_uri()
+ c.require(bool(uri), "the terminal showed a pay URI for the inventory order")
+ order_id = _order_id_from(uri)
+ wallet.pay(uri)
+ c.app.wait_for_success()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(MARK_SUCCESS)),
+ "an inventory order was paid and acknowledged")
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.expect(status.get("order_status") == "paid",
+ "success-without-payment",
+ f"the inventory order shows as received while the backend says "
+ f"{status.get('order_status')!r}")
+
+
+@scenario("demo")
+def order_custom_product(c: Ctx) -> None:
+ """The inventory screen's "Add custom product" dialog."""
+ inst = c.provision_demo()
+ c.app.goto("inventory")
+ c.ep.observe()
+ c.app.add_custom_product("Tip", "2.00")
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"Tip")),
+ "the custom product appears in the order")
+ c.app.bill()
+ screen, _ = c.ep.observe()
+ uri = c.app.displayed_pay_uri()
+ c.require(bool(uri), "an order with a custom product reached the payment screen")
+ order_id = _order_id_from(uri)
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.ep.note(f"backend order: {json.dumps(status)[:300]}")
+ c.app.cancel_payment()
+ c.ep.observe()
+
+
+@scenario("demo", "phone")
+def amount_keypad_edges(c: Ctx) -> None:
+ """What the keypad does with nothing, with too much, and with corrections."""
+ c.provision_demo()
+ c.app.goto("amount")
+ # Charging nothing has to be refused. Saying so in a dialog is one way;
+ # disabling the button is a better one, and it is what the terminal does
+ # -- so a scenario that insists on a message reports a nicer design as a
+ # defect. What matters is that no order is opened.
+ c.app.tap_button(r"^Clear$")
+ screen = c.app._stable_dump()
+ charge = screen.find(r"Create order \(charge amount\)")
+ charge_enabled = charge is None or screen.tap_target(charge).enabled
+ c.ep.note(f"at 0.00 the charge button is "
+ f"{'enabled' if charge_enabled else 'disabled'}")
+ c.ep.perform(Action("tap_label", "Create order (charge amount)"))
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.expect(not charge_enabled or dialog is not None
+ or bool(screen.find(r"Enter an amount")),
+ "zero-amount-accepted-silently",
+ f"the charge button was live at 0.00 and charging neither opened "
+ f"an order nor said why not: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:400])
+ c.expect(not bool(screen.find(MARK_PAYMENT)),
+ "zero-amount-order-opened",
+ "charging 0.00 opened a payment screen",
+ " | ".join(screen.texts())[:400])
+ if dialog:
+ c.ep.note(f"zero amount: {dialog}")
+ c.app.dismiss_dialog()
+ # Backspace and clear.
+ c.app.enter_digits("C12345")
+ before = c.app.displayed_amount()
+ c.app.enter_digits("<<")
+ after = c.app.displayed_amount()
+ c.ep.note(f"after 12345 the keypad shows {before}, after two backspaces {after}")
+ c.require(before != after, "backspace changed the amount on the keypad")
+ # Far more digits than any price: the keypad must not render nonsense.
+ c.app.enter_digits("C" + "9" * 14)
+ screen, _ = c.ep.observe()
+ shown = c.app.displayed_amount(screen)
+ c.ep.note(f"fourteen nines gives {shown}")
+ c.expect(shown is not None,
+ "keypad-overflow-blank",
+ "typing fourteen digits left the keypad showing no amount at all",
+ " | ".join(screen.texts())[:400])
+ c.app.tap_button(r"^Clear$")
+ c.require(True, "the keypad's edges were exercised")
+
+
+@scenario("demo", "pay", "slow")
+def payment_cancel_after_claim(c: Ctx) -> None:
+ """A customer who looks at the contract and does not pay.
+
+ An order that has been claimed cannot be deleted the ordinary way, and the
+ terminal has a force-delete dialog for exactly that -- so this is the only
+ route to it.
+ """
+ inst = c.provision_demo()
+ # Claiming without paying still makes wallet-core choose a
+ # contract choice, and choosing one needs the balance to cover
+ # it -- so this wants a funded wallet even though it never pays.
+ wallet = c.funded_customer(inst.currency)
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.app.charge()
+ uri = c.app.displayed_pay_uri()
+ c.require(bool(uri), "the payment screen offered a pay URI")
+ order_id = _order_id_from(uri)
+ wallet.claim_only(uri)
+ c.ep.note(f"the customer claimed order {order_id} without paying")
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.require(status.get("order_status") == "claimed",
+ f"the backend considers the order claimed ({status.get('order_status')})")
+ screen = c.app.wait_for_claimed(timeout=60)
+ c.ep.observe()
+ c.require(bool(screen.find(r"confirm payment")),
+ "the terminal switched to 'waiting for the customer to confirm'")
+ c.ep.perform(Action("tap_label", "Cancel payment"))
+ time.sleep(5)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.ep.note(f"after cancelling a claimed order: {dialog or screen.texts()[:10]}")
+ c.expect(bool(screen.find(r"Force delete") or (dialog and "Force" in str(dialog))),
+ "no-force-delete-prompt",
+ f"cancelling a claimed payment offered no way to force the "
+ f"delete: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:500])
+ if screen.find(r"Force delete"):
+ c.ep.perform(Action("tap_label", "Force delete"))
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ remaining = [o for o in inst.merchant.history(inst.token.value, limit=-10)
+ if o.get("order_id") == order_id]
+ c.expect(not remaining,
+ "force-delete-left-the-order",
+ f"force-deleting order {order_id} left it in the backend's "
+ f"order list",
+ str(remaining)[:400])
+
+
+@scenario("demo", "slow")
+def payment_deadline_passes(c: Ctx) -> None:
+ """An order nobody pays, past its pay deadline.
+
+ The terminal's own timeout is `Long.MAX_VALUE`, so the countdown never
+ fires; what ends the wait is the backend refusing the order. Either way
+ the cashier must not be left looking at a code that can no longer be used.
+ """
+ inst = c.provision_demo()
+ order = inst.merchant.create_order(
+ inst.token.value, f"{inst.currency}:1", "pos-simulator deadline",
+ pay_deadline_s=25)
+ order_id = order["order_id"]
+ c.ep.note(f"created order {order_id} with a 25s pay deadline")
+ c.app.goto("history")
+ c.app.tap_button(r"Refresh history")
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(re.escape(order_id))) or
+ bool(c.app.history_rows(screen)),
+ "the history list shows orders")
+ time.sleep(30)
+ c.ep.note("the pay deadline has passed")
+ c.app.tap_button(r"Refresh history")
+ time.sleep(8)
+ screen, _ = c.ep.observe()
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.ep.note(f"backend says {status.get('order_status')!r}")
+ c.require(True, "an order was left to expire and the list was refreshed")
+
+
+@scenario("mock")
+def payment_order_creation_fails(c: Ctx) -> None:
+ """A merchant with no bank account: the order cannot be created.
+
+ The backend refuses with a specific reason. The terminal has a string for
+ this -- "Error: Could not create order" -- plus a detail line, so what is
+ being checked is that the detail is the backend's reason rather than
+ nothing or a stack trace.
+ """
+ c.provision_mock("no-bank-account")
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.ep.perform(Action("tap_label", "Create order (charge amount)"))
+ time.sleep(8)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.require(dialog is not None or bool(screen.find(r"(?i)could not create")),
+ f"the terminal reported the refused order "
+ f"(screen: {screen.texts()[:10]})")
+ c.ep.note(f"refused order: {dialog}")
+ body = f"{dialog.title} {dialog.message}" if dialog else " ".join(screen.texts())
+ c.expect(bool(re.search(r"(?i)wire|account|bank", body)),
+ "order-refusal-loses-the-reason",
+ f"the backend refused the order because the instance has no bank "
+ f"account, and the terminal said only: {body[:200]!r}",
+ body[:600])
+ c.expect(not re.search(r"(?i)exception|java\.|ktor", body),
+ "exception-in-dialog",
+ f"the refused-order dialog quotes an exception: {body[:200]!r}",
+ body[:600])
+
+
+# =========================================================================
+# history and refunds
+# =========================================================================
+
+
+@scenario("demo", "slow")
+def history_browse_and_paginate(c: Ctx) -> None:
+ """The history list on an instance with a long history behind it.
+
+ The sandbox instance is what makes this worth running: it has enough
+ orders for the list's pagination to run several pages deep, which a stack
+ the harness builds itself never would.
+ """
+ inst = c.provision_demo()
+ backend_orders = inst.merchant.history(inst.token.value, limit=-40)
+ c.require(len(backend_orders) > 5,
+ f"the instance has a history to browse ({len(backend_orders)} orders)")
+ screen = c.app.goto("history")
+ c.ep.observe()
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ rows = c.app.history_rows(screen)
+ c.require(bool(rows), f"the history list shows rows (screen: {screen.texts()[:10]})")
+ c.ep.note(f"first page shows {len(rows)} rows")
+ # The snapshot is taken once and judged against for the whole walk, which
+ # is only sound while nothing else is paying these orders: another worker
+ # settling one would make a correct "paid" chip disagree with a snapshot
+ # that still says unpaid.
+ if EXCLUSIVE_DEMO:
+ c.ep.judge(oracles.history_matches_backend(screen, backend_orders))
+ seen = set(rows)
+ for page in range(8):
+ c.ep.perform(Action("scroll_down"), screen)
+ screen, _ = c.ep.observe()
+ rows = c.app.history_rows(screen)
+ if EXCLUSIVE_DEMO:
+ c.ep.judge(oracles.history_matches_backend(screen, backend_orders))
+ new = set(rows) - seen
+ seen |= set(rows)
+ if not new and page > 2:
+ break
+ c.ep.note(f"scrolled through {len(seen)} distinct order references")
+ c.require(len(seen) >= len(set(c.app.history_rows())),
+ "the list kept its rows while scrolling")
+
+
+@scenario("demo", "pay", "slow")
+def refund_full(c: Ctx) -> None:
+ """Pay an order, then refund all of it, and have the customer accept."""
+ inst = c.provision_demo()
+ wallet = c.funded_customer(inst.currency)
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.app.charge()
+ uri = c.app.displayed_pay_uri()
+ c.require(bool(uri), "the payment screen offered a pay URI")
+ order_id = _order_id_from(uri)
+ wallet.pay(uri)
+ c.app.wait_for_success()
+ c.app.continue_from_success()
+ c.ep.observe()
+ screen = c.app.goto("history")
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"^Refund$")),
+ f"a paid order offers a Refund action "
+ f"(screen: {screen.texts()[:12]})")
+ c.app.start_refund()
+ c.ep.observe()
+ c.app.submit_refund("1.00", "pos-simulator full refund")
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(MARK_REFUND_URI)),
+ f"the terminal is showing the refund code "
+ f"(screen: {screen.texts()[:10]})")
+ host = urllib.parse.urlsplit(inst.merchant.base).netloc
+ refund_uri = c.app.refund_uri_for(host, inst.merchant.instance, order_id)
+ c.ep.note(f"refund URI: {refund_uri}")
+ wallet.accept_refund(refund_uri)
+ time.sleep(6)
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.expect(bool(status.get("refunded")),
+ "refund-not-recorded",
+ f"the customer accepted the refund and the backend still reports "
+ f"refunded={status.get('refunded')!r}",
+ json.dumps(status)[:500])
+ screen, _ = c.ep.observe()
+ c.ep.note(f"refund screen now: {screen.texts()[:10]}")
+
+
+@scenario("demo", "pay", "slow")
+def refund_amount_edges(c: Ctx) -> None:
+ """Refund amounts the terminal has to refuse, and the reason it gives."""
+ inst = c.provision_demo()
+ wallet = c.funded_customer(inst.currency)
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.app.charge()
+ uri = c.app.displayed_pay_uri()
+ c.require(bool(uri), "the payment screen offered a pay URI")
+ wallet.pay(uri)
+ c.app.wait_for_success()
+ c.app.continue_from_success()
+ c.app.goto("history")
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"^Refund$")), "a paid order offers a Refund action")
+ c.app.start_refund()
+ cases = {
+ "more than the order": "99.00",
+ "zero": "0.00",
+ "not a number": "abc",
+ "two separators": "1.0.0",
+ "negative": "-1.00",
+ }
+ submitted = 0
+ for label, amount in cases.items():
+ c.ep.note(f"refund amount ({label}): {amount!r}")
+ try:
+ c.app.fill_field(r"^Amount$", amount, verify=False)
+ except PosError as e:
+ c.ep.note(f"the field would not take {amount!r}: {e}")
+ continue
+ # Master renamed this button to "Refund Taler"; a raw tap_label on the
+ # old wording pressed nothing at all, so the form never validated and
+ # every bad amount looked like it had been refused in silence.
+ c.app.tap_button(APPROVE_REFUND)
+ time.sleep(4)
+ screen, _ = c.ep.observe()
+ submitted += 1
+ if screen.find(r"offer refund"):
+ c.ep.judge([oracles.Finding(
+ "bad-refund-accepted",
+ f"a refund of {amount!r} ({label}) was accepted",
+ " | ".join(screen.texts())[:400])])
+ # An accepted refund leaves the refund-code screen, so the form
+ # has to be reached again from the history list for the next case.
+ # That walk can fail -- the terminal lands on whichever order
+ # screen it was last on -- and when it does, the cases already
+ # submitted still count: the scenario reports what it reached
+ # rather than discarding it.
+ try:
+ c.app.tap_button(r"^Abort$")
+ time.sleep(2)
+ c.app.goto("history")
+ c.app.refresh_history()
+ c.app.start_refund()
+ except (PosError, TimeoutError) as e:
+ c.ep.note(f"could not reopen the refund form after {label}: {e}")
+ break
+ continue
+ dialog = c.app.read_dialog(screen)
+ said_something = bool(dialog) or bool(screen.find(
+ r"(?i)invalid amount|positive amount|Greater than order amount"))
+ c.expect(said_something,
+ "bad-refund-refused-silently",
+ f"a refund of {amount!r} ({label}) was neither accepted nor "
+ f"explained: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:500])
+ if dialog:
+ c.ep.note(f"{label}: {dialog}")
+ c.app.dismiss_dialog()
+ c.require(submitted >= 3,
+ f"{submitted} of {len(cases)} bad refund amounts were submitted")
+
+
+@scenario("demo", "pay", "slow")
+def refund_amount_swallows_extra_dots(c: Ctx) -> None:
+ """A refund amount with two decimal points refunds a different number.
+
+ `Amount.fromString` splits on "." and reads only the first two pieces, so
+ "1.000.50" is one unit and no fraction. The refund form parses the
+ cashier's input with it and never calls `isValidAmountStr`, which does
+ reject a second point -- so the terminal accepts the input, says nothing,
+ and refunds an amount nobody typed.
+ """
+ inst = c.provision_demo()
+ wallet = c.funded_customer(inst.currency)
+ c.app.goto("amount")
+ c.app.enter_amount("10.00")
+ c.app.charge()
+ uri = c.app.displayed_pay_uri()
+ c.require(bool(uri), "the payment screen offered a pay URI")
+ order_id = _order_id_from(uri)
+ wallet.pay(uri)
+ c.app.wait_for_success()
+ c.app.continue_from_success()
+ c.app.goto("history")
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"^Refund$")), "the paid order offers a Refund action")
+ c.app.start_refund()
+ typed = "1.000.50"
+ c.ep.note(f"typing {typed!r} as the refund amount on a "
+ f"{inst.currency}:10.00 order")
+ c.app.fill_field(r"^Amount$", typed, verify=False)
+ c.app.tap_button(APPROVE_REFUND)
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ accepted = bool(screen.find(MARK_REFUND_URI))
+ c.ep.note(f"after approving: accepted={accepted}, dialog={dialog}")
+ c.require(accepted or dialog is not None,
+ "the terminal either accepted the refund or explained itself")
+ if not accepted:
+ c.ep.note("the terminal refused the malformed amount, which is correct")
+ return
+ time.sleep(6)
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ refunded = status.get("refund_amount") or status.get("refund_taken") or ""
+ c.ep.note(f"the backend recorded a refund of {refunded!r}")
+ c.ep.judge([oracles.Finding(
+ "refund-amount-silently-reinterpreted",
+ f"a refund typed as {typed!r} was accepted without comment and the "
+ f"backend recorded {refunded or 'an amount the harness could not read'}"
+ f"; everything after the second decimal point is discarded by "
+ f"Amount.fromString, so the merchant refunds a number nobody typed",
+ json.dumps(status)[:700])])
+
+
+@scenario("demo", "slow")
+def refund_past_deadline(c: Ctx) -> None:
+ """Refunding an order whose refund deadline has gone.
+
+ The backend refuses; the terminal has a string for it
+ ("Refund deadline has passed"). Reaching this needs an order whose refund
+ deadline has passed -- and the backend will not *create* one that is
+ already in the past, so it has to be created a little ahead and waited
+ out.
+ """
+ inst = c.provision_demo()
+ order = inst.merchant.create_order(
+ inst.token.value, f"{inst.currency}:1",
+ "pos-simulator refund deadline", refund_deadline_s=20)
+ order_id = order["order_id"]
+ c.ep.note(f"created order {order_id} with a refund deadline 20s out")
+ time.sleep(25)
+ c.ep.note("the refund deadline has passed")
+ try:
+ inst.merchant.refund(inst.token.value, order_id, f"{inst.currency}:1")
+ c.ep.note("the backend accepted a refund on an unpaid order")
+ except merchant.MerchantError as e:
+ c.ep.note(f"the backend refuses to refund it: {e}")
+ c.app.goto("history")
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ c.require(bool(c.app.history_rows(screen)),
+ "the history list came up with rows in it")
+
+
+@scenario("demo")
+def history_delete_unpaid_order(c: Ctx) -> None:
+ """Deleting an unpaid order from the history list."""
+ inst = c.provision_demo()
+ order = inst.merchant.create_order(
+ inst.token.value, f"{inst.currency}:1", "pos-simulator to delete")
+ order_id = order["order_id"]
+ c.ep.note(f"created order {order_id} to delete through the UI")
+ c.app.goto("history")
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"Delete order")),
+ f"the history list offers a delete action "
+ f"(screen: {screen.texts()[:12]})")
+ c.ep.perform(Action("tap_label", "Delete order"))
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ if dialog and "Force" in str(dialog):
+ c.ep.note(f"delete needed force: {dialog}")
+ c.ep.perform(Action("tap_label", "Force delete"))
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ remaining = [o for o in inst.merchant.history(inst.token.value, limit=-20)
+ if o.get("order_id") == order_id]
+ c.ep.note(f"after the delete the order is {'gone' if not remaining else 'still there'}")
+ c.require(True, "a delete was attempted from the history list")
+
+
+# =========================================================================
+# settings
+# =========================================================================
+
+
+@scenario("demo")
+def settings_initial_order_screen(c: Ctx) -> None:
+ """Switching which order screen the terminal starts on."""
+ inst = c.provision_demo()
+ screen = c.app.goto("settings")
+ c.ep.observe()
+ c.require(bool(screen.find(r"Default order mode|Initial order screen")),
+ f"the settings screen offers the initial-order-screen choice "
+ f"(screen: {screen.texts()[:12]})")
+ c.ep.perform(Action("tap_label", "Default order mode"))
+ time.sleep(2)
+ screen, _ = c.ep.observe()
+ options = [t for t in screen.texts()
+ if t in ("Order by amount", "Order by inventory")]
+ c.require(len(options) >= 2,
+ f"both order modes are offered ({options})")
+ c.ep.perform(Action("tap_label", "Order by inventory"))
+ time.sleep(2)
+ c.ep.observe()
+ c.app.relaunch()
+ time.sleep(4)
+ screen, _ = c.ep.observe()
+ c.expect(bool(screen.find(r"^Bill( .*)?$|Everything")),
+ "initial-order-screen-not-applied",
+ f"the terminal was set to start on the inventory screen and came "
+ f"up on {screen.texts()[:8]}",
+ " | ".join(screen.texts())[:400])
+ c.require(True, "the initial order screen was changed and the app restarted")
+
+
+@scenario("demo")
+def settings_language_sweep(c: Ctx) -> None:
+ """Every language the terminal offers, looked at for rendering defects.
+
+ Not a translation review: what the oracles are looking for is an
+ unsubstituted format string, a resource name leaking as a label and text
+ that overflows into nothing -- defects that are invisible in English
+ because English is what the layout was built around.
+ """
+ c.provision_demo()
+ if c.dev.sdk_int < 33:
+ raise ScenarioFailure(
+ f"per-app languages need API 33, this device is {c.dev.sdk_int}")
+ locales = ["de", "fr", "es", "it", "ru", "sv", "tr", "uk", "fi", "iw"]
+ swept = 0
+ for tag in locales:
+ c.dev.set_app_locale(tag)
+ c.app.relaunch()
+ time.sleep(4)
+ screen, _ = c.ep.observe()
+ if not screen.activity.startswith("net.taler.merchantpos"):
+ c.ep.judge([oracles.Finding(
+ "locale-crash",
+ f"the terminal does not come up in {tag!r}",
+ " | ".join(screen.texts())[:400])])
+ c.dev.launch()
+ time.sleep(4)
+ continue
+ swept += 1
+ c.ep.note(f"{tag}: {screen.texts()[:8]}")
+ for destination in ("history", "settings"):
+ try:
+ c.app.goto(destination)
+ except (PosError, TimeoutError):
+ # The drawer rows are translated, so `goto` cannot find them;
+ # that is expected, not a finding, and the screens seen so far
+ # have already been judged.
+ break
+ c.ep.observe()
+ c.dev.set_app_locale("en")
+ c.app.relaunch()
+ time.sleep(4)
+ c.ep.observe()
+ c.require(swept >= len(locales) // 2,
+ f"the terminal came up in {swept} of {len(locales)} languages")
+
+
+# =========================================================================
+# a merchant who is not set up
+# =========================================================================
+
+
+@scenario("mock")
+def fresh_instance_no_inventory(c: Ctx) -> None:
+ """A merchant who has provisioned an instance and stocked nothing.
+
+ This is what a new user sees, and it is the case the terminal handles
+ worst: `OrderManager.onConfigurationReceived` returns
+ `config_error_category` when the instance has no categories, and
+ `ConfigManager` treats any receiver error as a configuration failure --
+ so the terminal refuses the instance outright rather than coming up on a
+ screen that needs no inventory. The amount-entry screen needs none: a
+ cashier who only ever charges amounts cannot use the terminal until
+ somebody adds a product they will never sell.
+ """
+ screen = c.provision_mock("fresh", expect_success=False)
+ deadline = time.monotonic() + 60
+ dialog = None
+ while time.monotonic() < deadline:
+ screen, _ = c.ep.observe()
+ if screen.find(r"Charge|Create order|Bill|Everything"):
+ break
+ dialog = c.app.read_dialog(screen)
+ if dialog:
+ break
+ time.sleep(2)
+ c.require(bool(c.mock.state.paths()),
+ "the terminal fetched the empty instance's configuration")
+ if dialog:
+ c.ep.note(f"empty instance refused with: {dialog}")
+ body = f"{dialog.title} {dialog.message}"
+ c.ep.judge([oracles.Finding(
+ "fresh-instance-refused",
+ f"an instance with no products and no categories is refused with "
+ f"{body.strip()!r}, so a freshly provisioned terminal cannot be "
+ f"used at all -- not even for charging an amount, which needs no "
+ f"inventory",
+ body[:600])])
+ c.app.dismiss_dialog()
+ screen, _ = c.ep.observe()
+ c.expect(bool(screen.find(AT_LOGIN)),
+ "stuck-after-empty-instance",
+ f"after refusing an empty instance the terminal is not back "
+ f"on the login form: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:400])
+ return
+
+ c.require(bool(screen.find(r"Charge|Create order|Bill|Everything")),
+ f"a terminal on an empty instance reached an order screen "
+ f"(screen: {screen.texts()[:10]})")
+ c.app.goto("amount")
+ c.app.enter_amount("1.50")
+ screen, _ = c.ep.observe()
+ c.require(c.app.displayed_amount(screen) is not None,
+ "the keypad works on an instance with no products")
+ try:
+ screen = c.app.goto("inventory")
+ except (PosError, TimeoutError) as e:
+ c.ep.judge([oracles.Finding(
+ "empty-inventory-unreachable",
+ f"the inventory screen cannot be opened on an instance with no "
+ f"products: {e}",
+ " | ".join(c.dev.dump().texts())[:400])])
+ return
+ screen, _ = c.ep.observe()
+ c.ep.note(f"empty inventory screen: {screen.texts()[:12]}")
+ c.expect(bool(screen.find(r"(?i)no products|nothing|empty|add")),
+ "empty-inventory-unexplained",
+ f"the inventory screen on an instance with no products says "
+ f"nothing about why it is empty: {screen.texts()[:12]}",
+ " | ".join(screen.texts())[:500])
+
+
+@scenario("mock")
+def instance_wrong_currency(c: Ctx) -> None:
+ """Products priced in a currency the instance does not use.
+
+ The terminal has a badge for this ("Wrong currency") and a configuration
+ error for it, so one of the two should appear -- and whichever it is, the
+ terminal should not offer such a product for sale.
+ """
+ c.provision_mock("wrong-currency", expect_success=False)
+ time.sleep(10)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.ep.note(f"screen: {screen.texts()[:12]}; dialog: {dialog}")
+ if dialog:
+ body = f"{dialog.title} {dialog.message}"
+ c.expect(bool(re.search(r"(?i)currency", body)),
+ "wrong-currency-not-named",
+ f"products in the wrong currency produced {body[:200]!r}, "
+ f"which does not mention the currency",
+ body[:500])
+ c.require(True, "the terminal refused the badly priced inventory")
+ return
+ c.require(bool(screen.find(r"Charge|Bill|Everything|Create order")),
+ f"the terminal came up on an order screen "
+ f"(screen: {screen.texts()[:10]})")
+ try:
+ screen = c.app.goto("inventory")
+ except (PosError, TimeoutError):
+ c.require(True, "the inventory screen is not reachable")
+ return
+ screen, _ = c.ep.observe()
+ c.expect(bool(screen.find(r"Wrong currency")) or
+ not screen.find(r"Coffee|Tea"),
+ "wrong-currency-offered-for-sale",
+ f"a product priced in another currency is offered without a "
+ f"warning: {screen.texts()[:12]}",
+ " | ".join(screen.texts())[:500])
+
+
+@scenario("mock")
+def instance_bad_category_reference(c: Ctx) -> None:
+ """A product in a category that does not exist.
+
+ `OrderManager` has a configuration error for exactly this
+ ("Product %1$s references unknown category ID %2$d"), which makes it a
+ good test of whether that message survives the trip to the screen with
+ its arguments substituted.
+ """
+ c.provision_mock("bad-category", expect_success=False)
+ time.sleep(10)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.ep.note(f"screen: {screen.texts()[:12]}; dialog: {dialog}")
+ body = f"{dialog.title} {dialog.message}" if dialog else " ".join(screen.texts())
+ c.expect(not re.search(r"%\d*\$?[sd]", body),
+ "placeholder-leak",
+ f"the unknown-category message reached the screen with its "
+ f"placeholders unsubstituted: {body[:200]!r}",
+ body[:500])
+ c.require(bool(dialog) or bool(screen.find(r"Charge|Bill|Everything")),
+ f"the terminal either refused the inventory or came up anyway "
+ f"(screen: {screen.texts()[:10]})")
+
+
+@scenario("mock")
+def instance_malformed_pos_config(c: Ctx) -> None:
+ """`/private/pos` that is not the shape the terminal expects."""
+ c.provision_mock("malformed", expect_success=False)
+ time.sleep(10)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.ep.note(f"screen: {screen.texts()[:12]}; dialog: {dialog}")
+ c.require(dialog is not None or bool(screen.find(r"Merchant portal URL")),
+ f"the terminal reported the malformed configuration "
+ f"(screen: {screen.texts()[:10]})")
+ if dialog:
+ body = f"{dialog.title} {dialog.message}"
+ c.expect(not re.search(r"(?i)exception|kotlinx\.serialization|java\.",
+ body),
+ "exception-in-dialog",
+ f"the malformed-config dialog quotes an exception: "
+ f"{body[:200]!r}",
+ body[:500])
+ c.app.dismiss_dialog()
+ screen, _ = c.ep.observe()
+ c.expect(bool(screen.find(AT_LOGIN)),
+ "stuck-after-malformed-config",
+ f"after a malformed configuration the terminal is not back on "
+ f"the login form: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:400])
+
+
+@scenario("mock")
+def instance_empty_pos_reply(c: Ctx) -> None:
+ """`/private/pos` that answers 200 with an empty body."""
+ c.provision_mock("empty-reply", expect_success=False)
+ time.sleep(10)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"screen: {screen.texts()[:12]}")
+ dialog = c.app.read_dialog(screen)
+ c.require(dialog is not None or bool(screen.find(r"Merchant portal URL")),
+ f"the terminal reported the empty reply "
+ f"(screen: {screen.texts()[:10]})")
+ if dialog:
+ c.ep.note(f"dialog: {dialog}")
+ c.app.dismiss_dialog()
+
+
+@scenario("mock")
+def backend_version_mismatch(c: Ctx) -> None:
+ """Backends too old and too new for the terminal to talk to."""
+ for profile in ("version-old", "version-new"):
+ c.ep.note(f"backend version profile {profile}")
+ screen = c.provision_mock(profile, instance=f"mock-{profile}",
+ expect_success=False)
+ time.sleep(10)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.ep.note(f"{profile}: {dialog or screen.texts()[:10]}")
+ body = f"{dialog.title} {dialog.message}" if dialog else " ".join(screen.texts())
+ c.expect(bool(dialog) or bool(screen.find(r"Merchant portal URL")),
+ "version-mismatch-silent",
+ f"a backend with an incompatible version ({profile}) was "
+ f"accepted without comment: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:500])
+ c.expect(not re.search(r"%\d*\$?[sd]", body),
+ "placeholder-leak",
+ f"the version-mismatch message has unsubstituted "
+ f"placeholders: {body[:200]!r}",
+ body[:400])
+ if dialog:
+ c.app.dismiss_dialog()
+ c.require(True, "both version mismatches were presented to the terminal")
+
+
+@scenario("mock", "slow")
+def backend_too_slow(c: Ctx) -> None:
+ """A backend that never answers in time.
+
+ `ConfigFetcherFragment` shows a spinner and waits for a result; the
+ question is whether anything ever ends that wait.
+ """
+ c.provision_mock("slow", expect_success=False)
+ for _ in range(9):
+ time.sleep(10)
+ screen, _ = c.ep.observe()
+ if not screen.find(r"Fetching configuration"):
+ break
+ screen, _ = c.ep.observe()
+ c.require(bool(c.mock.state.paths()),
+ "the terminal did reach the slow backend")
+ c.expect(not screen.find(r"Fetching configuration"),
+ "stuck-progress",
+ "the terminal was still fetching configuration after 90 seconds "
+ "against a backend that does not answer, with no way out",
+ " | ".join(screen.texts())[:400])
+
+
+@scenario("mock", "slow")
+def backend_never_answers(c: Ctx) -> None:
+ """A backend that accepts the connection and then says nothing, ever.
+
+ The terminal's HTTP client is built with `requestTimeoutMillis`,
+ `socketTimeoutMillis` and `connectTimeoutMillis` all set to
+ `INFINITE_TIMEOUT_MS` (`taler-kotlin-android`'s `createDefaultHttpClient`),
+ so nothing on the client side ever gives up -- and the login form covers
+ itself with a modal spinner while `isSubmitting` is true. The question is
+ whether the cashier is ever offered a way out.
+ """
+ c.provision_mock("hang", expect_success=False)
+ c.require(True, "the login form was submitted against a backend that hangs")
+ waited = 0
+ for _ in range(12):
+ time.sleep(15)
+ waited += 15
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ if dialog or screen.find(r"Charge|Bill|Create order"):
+ c.ep.note(f"the terminal gave up after about {waited}s: "
+ f"{dialog or screen.texts()[:8]}")
+ break
+ else:
+ screen, _ = c.ep.observe()
+ c.ep.judge([oracles.Finding(
+ "hung-request-never-gives-up",
+ f"the login form was still covered by its modal spinner {waited}s "
+ f"after submitting to a backend that never answers, with nothing "
+ f"to cancel and nothing to read; the HTTP client is configured "
+ f"with infinite request, socket and connect timeouts",
+ " | ".join(screen.texts())[:400] or
+ f"{len(screen.nodes)} nodes, none labelled or tappable")])
+ c.require(bool(c.mock.state.paths()),
+ "the terminal did reach the backend that hangs")
+ # Back must not get out of it either, or there would be a way out.
+ c.ep.perform(Action("back"))
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"after a back press: {screen.texts()[:8] or 'nothing readable'}")
+
+
+@scenario("mock")
+def pos_config_url_encodes_the_separator(c: Ctx) -> None:
+ """The path the terminal asks for its configuration on.
+
+ `ConfigManager` builds it with `Uri.Builder.appendPath("private/pos")`,
+ which percent-encodes the separator because a path segment may contain
+ one -- so the request goes to `/instances/<id>/private%2Fpos`. The GNU
+ Taler backend decodes the path before routing and answers anyway, which is
+ why this has never shown up; a reverse proxy need not, and Apache with its
+ default `AllowEncodedSlashes Off` rejects such a request outright.
+ """
+ c.provision_mock("healthy", expect_success=False)
+ deadline = time.monotonic() + 40
+ while time.monotonic() < deadline:
+ if any("private" in p for p in c.mock.state.paths()):
+ break
+ time.sleep(2)
+ c.ep.observe()
+ asked = [p for p in c.mock.state.paths() if "private" in p]
+ c.require(bool(asked),
+ f"the terminal asked the mock backend for its configuration "
+ f"(paths seen: {c.mock.state.paths()[:8]})")
+ c.ep.note(f"configuration paths requested: {asked[:5]}")
+ encoded = c.mock.state.encoded_slash_requests()
+ c.expect(not encoded,
+ "encoded-path-separator",
+ f"the terminal asks for its configuration at "
+ f"{encoded[0] if encoded else ''!r}, with the path separator "
+ f"percent-encoded; a backend behind a proxy that does not decode "
+ f"encoded slashes answers 404 and the terminal cannot be "
+ f"configured at all",
+ "\n".join(encoded[:5]))
+
+
+@scenario("mock", "slow")
+def huge_inventory(c: Ctx) -> None:
+ """Four hundred products in the grid."""
+ c.provision_mock("huge-inventory")
+ screen, _ = c.ep.observe()
+ try:
+ screen = c.app.goto("inventory")
+ except (PosError, TimeoutError) as e:
+ raise ScenarioFailure(f"the inventory screen never came up: {e}")
+ c.ep.observe()
+ c.require(bool(screen.find(r"Product \d|Everything")),
+ f"the grid is showing products (screen: {screen.texts()[:10]})")
+ for _ in range(6):
+ c.ep.perform(Action("scroll_down"), screen)
+ screen, _ = c.ep.observe()
+ added = c.app.add_products(3)
+ c.ep.note(f"added {added} from a 400-product grid")
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"^Bill( .*)?$")),
+ "an order can still be billed from a large grid")
+
+
+@scenario("mock")
+def unicode_product_names(c: Ctx) -> None:
+ """Product names in scripts the layout was not designed around."""
+ c.provision_mock("unicode")
+ c.ep.observe()
+ try:
+ screen = c.app.goto("inventory")
+ except (PosError, TimeoutError) as e:
+ raise ScenarioFailure(f"the inventory screen never came up: {e}")
+ screen, _ = c.ep.observe()
+ c.ep.note(f"grid shows: {screen.texts()[:16]}")
+ c.require(len(screen.texts()) > 3,
+ "the grid rendered something for the unicode products")
+ added = c.app.add_products(2)
+ c.ep.note(f"added: {added}")
+ screen, _ = c.ep.observe()
+ c.app.bill()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"scan QR Code|Cancel payment")),
+ "an order of unicode-named products reached the payment screen")
+ c.app.cancel_payment()
+ c.ep.observe()
+
+
+# =========================================================================
+# the environment turning against it
+# =========================================================================
+
+
+@scenario("demo", "slow")
+def offline_during_payment(c: Ctx) -> None:
+ """The network goes away while the payment screen is polling."""
+ inst = c.provision_demo()
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.app.charge()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"scan QR Code|Cancel payment")),
+ "the terminal is on the payment screen")
+ uri = c.app.displayed_pay_uri()
+ c.ep.note(f"pay URI before going offline: {uri}")
+ c.ep.perform(Action("offline", True))
+ time.sleep(15)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"offline, the payment screen shows: {screen.texts()[:10]}")
+ c.ep.perform(Action("offline", False))
+ time.sleep(15)
+ screen, _ = c.ep.observe()
+ c.expect(screen.activity.startswith("net.taler.merchantpos"),
+ "crash-when-network-returns",
+ f"the terminal did not survive the network coming back: "
+ f"{screen.activity}",
+ " | ".join(screen.texts())[:400])
+ c.require(True, "the network was taken away and given back mid-payment")
+
+
+@scenario("demo")
+def offline_at_startup(c: Ctx) -> None:
+ """Starting a configured terminal with no network at all."""
+ inst = c.provision_demo()
+ c.ep.perform(Action("offline", True))
+ c.app.relaunch()
+ time.sleep(12)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"offline start shows: {screen.texts()[:12]}")
+ dialog = c.app.read_dialog(screen)
+ if dialog:
+ c.ep.note(f"dialog: {dialog}")
+ c.expect(not screen.find(r"Fetching configuration"),
+ "stuck-progress",
+ "a terminal started with no network is still fetching "
+ "configuration",
+ " | ".join(screen.texts())[:400])
+ c.expect(bool(screen.find(r"Charge|Bill|Create order|Everything")) or
+ bool(dialog) or bool(screen.find(r"Merchant portal URL")),
+ "offline-start-dead-end",
+ f"a terminal started with no network shows neither its cached "
+ f"configuration nor an explanation: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:500])
+ c.ep.perform(Action("offline", False))
+ time.sleep(8)
+ c.ep.observe()
+ c.require(True, "the terminal was started offline")
+
+
+@scenario("demo")
+def process_death_mid_payment(c: Ctx) -> None:
+ """The process is killed while an order is waiting to be paid."""
+ inst = c.provision_demo()
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.app.charge()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"scan QR Code|Cancel payment")),
+ "the terminal is on the payment screen")
+ uri = c.app.displayed_pay_uri()
+ order_id = _order_id_from(uri) if uri else None
+ c.ep.note(f"order {order_id} was open when the process was killed")
+ c.ep.perform(Action("process_death"))
+ time.sleep(10)
+ screen, _ = c.ep.observe()
+ c.require(screen.activity.startswith("net.taler.merchantpos"),
+ f"the terminal came back after being killed "
+ f"(showing {screen.activity})")
+ c.ep.note(f"after process death: {screen.texts()[:12]}")
+ if order_id:
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.ep.note(f"the open order is now {status.get('order_status')!r} at the backend")
+ remaining = [o for o in inst.merchant.history(inst.token.value, limit=-10)
+ if o.get("order_id") == order_id and not o.get("paid")]
+ if remaining:
+ c.ep.judge([oracles.Finding(
+ "orphaned-order",
+ f"killing the terminal mid-payment left unpaid order "
+ f"{order_id} behind at the backend",
+ str(remaining)[:400])])
+
+
+@scenario("demo")
+def back_button_sweep(c: Ctx) -> None:
+ """Pressing back from every screen, which is the cheapest way out of each.
+
+ The terminal's back handling is hand-written: two presses to exit from an
+ order screen, home from the login screen, pop otherwise. What is checked
+ is that none of those paths ends somewhere with nothing on it.
+ """
+ c.provision_demo()
+ for destination in ("amount", "inventory", "history", "settings"):
+ try:
+ c.app.goto(destination)
+ except (PosError, TimeoutError) as e:
+ c.ep.note(f"could not reach {destination}: {e}")
+ continue
+ screen, _ = c.ep.observe()
+ c.ep.perform(Action("back"))
+ time.sleep(2)
+ screen, _ = c.ep.observe()
+ if not screen.activity.startswith("net.taler.merchantpos"):
+ c.ep.note(f"back from {destination} left the app")
+ c.dev.launch()
+ time.sleep(4)
+ continue
+ c.expect(bool(screen.labelled()),
+ "blank-after-back",
+ f"pressing back from the {destination} screen left a screen "
+ f"with no labels on it",
+ screen.signature()[:400])
+ c.require(True, "back was pressed from every destination")
+
+
+@scenario("demo")
+def drawer_locked_without_config(c: Ctx) -> None:
+ """The navigation drawer must stay shut while there is no configuration.
+
+ `gesturesEnabled` is switched off and the hamburger replaced by a spacer
+ while the config is invalid, so an unconfigured terminal cannot be
+ navigated away from its login screen -- which is deliberate, and worth
+ confirming rather than assuming.
+ """
+ c.app.fresh_start()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"Merchant portal URL")),
+ "the terminal is unconfigured and on the login screen")
+ c.ep.perform(Action("drawer_gesture"))
+ time.sleep(2)
+ screen, _ = c.ep.observe()
+ c.expect(not (screen.find(r"^History$") and screen.find(r"^Settings$")),
+ "drawer-opens-without-config",
+ "the navigation drawer opens on an unconfigured terminal, which "
+ "leads to screens that have no backend to talk to",
+ " | ".join(screen.texts())[:400])
+ c.require(True, "the drawer gesture was tried without a configuration")
+
+
+@scenario("demo")
+def accessibility_names(c: Ctx) -> None:
+ """Every screen, checked for controls a screen reader cannot announce."""
+ c.provision_demo()
+ screens = ["amount", "inventory", "history", "settings"]
+ for destination in screens:
+ try:
+ c.app.goto(destination)
+ except (PosError, TimeoutError) as e:
+ c.ep.note(f"could not reach {destination}: {e}")
+ continue
+ screen, _ = c.ep.observe()
+ anonymous = screen.unnamed_clickables()
+ c.ep.note(f"{destination}: {len(anonymous)} unnamed control(s)")
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.app.charge()
+ c.ep.observe()
+ c.app.cancel_payment()
+ c.ep.observe()
+ c.require(True, "every screen was inspected for accessible names")
+
+
+@scenario("mock")
+def order_sold_out_between_taps(c: Ctx) -> None:
+ """The product sells out between ringing it up and billing it.
+
+ A 410 carrying `product_id`, `requested_quantity` and
+ `available_quantity` is the one backend error the terminal translates
+ rather than quotes: `Response.parseInventoryAvailabilityError` builds a
+ sentence from it and `PaymentManager.looksLikeInventoryError` recognises
+ that sentence and reloads the inventory. Neither can be reached by
+ anything a healthy backend says.
+ """
+ c.provision_mock("inventory-gone")
+ c.app.goto("inventory")
+ added = c.app.add_products(1)
+ c.require(bool(added), f"a product was added to the order ({added})")
+ c.ep.observe()
+ c.ep.perform(Action("tap_label", "Bill"))
+ time.sleep(8)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ body = (f"{dialog.title} {dialog.message}" if dialog
+ else " ".join(screen.texts()))
+ c.ep.note(f"sold-out order: {body[:300]}")
+ c.require(dialog is not None or bool(screen.find(r"(?i)stock|inventory|unavailable")),
+ f"the terminal reported the sold-out product "
+ f"(screen: {screen.texts()[:12]})")
+ c.expect(bool(re.search(r"(?i)stock|inventor|unavailable|sold", body)),
+ "sold-out-reported-as-a-generic-error",
+ f"a product that had sold out produced: {body[:200]!r} -- the "
+ f"backend said which product and how many were left",
+ body[:600])
+ c.expect(not re.search(r"(?i)exception|io\.ktor|kotlinx\.", body),
+ "exception-in-dialog",
+ f"the sold-out dialog quotes an exception: {body[:200]!r}",
+ body[:600])
+
+
+@scenario("mock")
+def insecure_pay_uri_offered_upgrade(c: Ctx) -> None:
+ """A backend behind plain HTTP hands out a taler+http:// pay URI.
+
+ The twister scenarios reach the same dialog on the real backend; this one
+ is here because the mock can hold the URI insecure for as long as the
+ terminal keeps polling, with no re-arming and no race -- so it is the
+ scenario that tells a broken dialog from a flaky one.
+ """
+ c.provision_mock("insecure-pay-uri")
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ # Not `Pos.charge`: that waits for the payment screen, and the whole point
+ # here is that a dialog comes up over it instead.
+ c.ep.perform(Action("tap_label", "Create order (charge amount)"))
+ deadline = time.monotonic() + 60
+ screen = c.app._stable_dump()
+ while time.monotonic() < deadline:
+ screen = c.app._stable_dump()
+ if _insecure_dialog_on(screen):
+ break
+ time.sleep(1.5)
+ c.ep.observe()
+ c.require(_insecure_dialog_on(screen),
+ f"the terminal objected to the taler+http:// pay URI "
+ f"(screen: {screen.texts()[:12]})")
+ dialog = c.app.read_dialog(screen)
+ c.ep.note(f"insecure-URI dialog: {dialog or screen.texts()[:6]}")
+ body = (f"{dialog.title} {dialog.message}" if dialog
+ else " ".join(screen.texts()))
+ # Not "does it say http": the terminal deliberately says "payment link"
+ # rather than naming a scheme, which is better wording for a cashier and
+ # which an oracle looking for the jargon called a defect. What has to be
+ # true is that the problem is named and all three ways out are offered.
+ c.expect(bool(re.search(r"(?i)payment link|link", body)),
+ "insecure-uri-dialog-says-nothing",
+ f"the dialog about an insecure pay URI does not mention the "
+ f"payment link at all: {body[:200]!r}",
+ body[:600])
+ offered = [label for label in ("Try fixed link", "Continue as is",
+ "Cancel order")
+ if screen.find(f"^{re.escape(label)}$")]
+ c.expect(len(offered) == 3,
+ "insecure-uri-dialog-missing-a-way-out",
+ f"the dialog offered {offered} and not all three of upgrading, "
+ f"continuing and cancelling",
+ " | ".join(screen.texts())[:400])
+ c.ep.perform(Action("tap_label", "Try fixed link"))
+ time.sleep(5)
+ screen, _ = c.ep.observe()
+ uri = c.app.displayed_pay_uri()
+ c.ep.note(f"after the upgrade the terminal shows {uri!r}")
+ c.expect(uri is None or uri.startswith("taler://"),
+ "https-upgrade-did-not-upgrade",
+ f"upgrading a taler+http:// URI left the terminal showing {uri!r}",
+ " | ".join(screen.texts())[:500])
+
+
+@scenario("demo", "pay", "slow")
+def history_force_delete_claimed_order(c: Ctx) -> None:
+ """Deleting, from the history list, an order a customer has claimed.
+
+ An ordinary delete is refused once an order is claimed, and the history
+ list has its own force-delete confirmation for that -- separate code from
+ the payment screen's, and the one path to `HistoryManager.forceDeleteOrder`.
+ """
+ inst = c.provision_demo()
+ # Claiming without paying still makes wallet-core choose a
+ # contract choice, and choosing one needs the balance to cover
+ # it -- so this wants a funded wallet even though it never pays.
+ wallet = c.funded_customer(inst.currency)
+ order = inst.merchant.create_order(
+ inst.token.value, f"{inst.currency}:1", "pos-simulator to force-delete")
+ order_id = order["order_id"]
+ uri = inst.merchant.pay_uri(inst.token.value, order_id)
+ c.require(bool(uri), f"the backend gave a pay URI for order {order_id}")
+ wallet.claim_only(uri)
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.require(status.get("order_status") == "claimed",
+ f"the order is claimed and so cannot be deleted the ordinary way "
+ f"({status.get('order_status')})")
+ c.app.goto("history")
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"Delete order")),
+ f"the history list offers a delete action "
+ f"(screen: {screen.texts()[:12]})")
+ c.ep.perform(Action("tap_label", "Delete order"))
+ time.sleep(7)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.ep.note(f"deleting a claimed order from the history list: {dialog}")
+ c.expect(dialog is not None and
+ bool(re.search(r"(?i)force|anyway|claimed", str(dialog))),
+ "no-force-delete-prompt-in-history",
+ f"deleting a claimed order from the history list offered no way "
+ f"to force it: {dialog or screen.texts()[:12]}",
+ " | ".join(screen.texts())[:500])
+ if dialog is not None and re.search(r"(?i)force", str(dialog)):
+ c.ep.perform(Action("tap_label", "Force delete"))
+ time.sleep(8)
+ c.ep.observe()
+ remaining = [o for o in inst.merchant.history(inst.token.value, limit=-20)
+ if o.get("order_id") == order_id]
+ c.expect(not remaining,
+ "force-delete-left-the-order",
+ f"force-deleting claimed order {order_id} from the history "
+ f"list left it in the backend's order list",
+ str(remaining)[:400])
+
+
+@scenario("demo")
+def history_show_payment_again(c: Ctx) -> None:
+ """Pick an unpaid order out of the history and go back to its code.
+
+ The row for an order nobody has paid offers "Show payment", which resumes
+ a payment the terminal may never have started -- `PaymentManager.
+ resumePayment` rebuilds one from the history entry alone. Every other
+ route to the payment screen comes from having just created the order.
+ """
+ inst = c.provision_demo()
+ order = inst.merchant.create_order(
+ inst.token.value, f"{inst.currency}:2", "pos-simulator to resume")
+ order_id = order["order_id"]
+ c.ep.note(f"created unpaid order {order_id} outside the terminal")
+ c.app.goto("history")
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"^Show payment$")),
+ f"an unpaid order offers 'Show payment' "
+ f"({screen.texts()[:14]})")
+ c.ep.perform(Action("tap_label", "Show payment"))
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ uri = c.app.displayed_pay_uri()
+ c.ep.note(f"resumed payment shows {uri}")
+ c.require(bool(screen.find(MARK_PAYMENT)) or bool(uri),
+ f"the terminal went back to a payment screen "
+ f"({screen.texts()[:14]})")
+ shown = _order_id_from(uri)
+ c.expect(uri is None or shown is not None,
+ "resumed-payment-has-no-order",
+ f"resuming a payment showed a URI naming no order: {uri!r}",
+ " | ".join(screen.texts())[:400])
+ if shown is not None:
+ c.expect(shown == order_id,
+ "resumed-the-wrong-order",
+ f"'Show payment' on order {order_id} showed a code for "
+ f"{shown}",
+ " | ".join(screen.texts())[:400])
+
+
+@scenario("demo", "pay", "slow")
+def history_show_refund_after_restart(c: Ctx) -> None:
+ """"Show refund" on an order whose refund the terminal has forgotten.
+
+ `onShowRefundClicked` asks the refund manager to resume, and when it
+ cannot -- which is what a restart leaves behind, since the pending refund
+ lives in memory -- it has to say so rather than open an empty screen.
+ Both arms are here: the refund is made, then the terminal is restarted.
+ """
+ inst = c.provision_demo()
+ wallet = c.funded_customer(inst.currency)
+ c.app.goto("amount")
+ c.app.enter_amount("2.00")
+ c.app.charge()
+ uri = c.app.displayed_pay_uri()
+ c.require(bool(uri), "the payment screen offered a pay URI")
+ order_id = _order_id_from(uri)
+ wallet.pay(uri)
+ c.app.wait_for_success()
+ c.app.continue_from_success()
+ c.app.goto("history")
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"^Refund$")),
+ f"the paid order offers a refund ({screen.texts()[:14]})")
+ c.app.start_refund()
+ c.app.submit_refund("1.00", "pos-simulator resume")
+ screen, _ = c.ep.observe()
+ c.ep.note(f"refund made: {screen.texts()[:10]}")
+ # Before the restart the terminal still holds the refund.
+ c.app.goto("history")
+ c.app.refresh_history()
+ screen, _ = c.ep.observe()
+ if screen.find(r"^Show refund$"):
+ c.ep.perform(Action("tap_label", "Show refund"))
+ time.sleep(5)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"show refund, still in memory: {screen.texts()[:12]}")
+ c.expect(bool(screen.find(MARK_REFUND_URI)),
+ "show-refund-opened-nothing",
+ "'Show refund' on a refund the terminal still holds did not "
+ "open the refund code",
+ " | ".join(screen.texts())[:400])
+ # And after it, the manager has nothing to resume from.
+ c.app.relaunch()
+ c.app.wait_for_order_entry(timeout=120)
+ # The demo backend answers the odd 502, and the history screen fetches as
+ # it opens -- so the dialog can be up before `goto` has anything to look
+ # for. Clearing and retrying is the difference between a scenario that
+ # reports the app and one that reports the weather.
+ _clear_dialog(c)
+ c.app.goto("history")
+ _tap_through_dialogs(c, r"Refresh history")
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ if not screen.find(r"^Show refund$"):
+ c.ep.note("after the restart the row no longer offers 'Show refund'")
+ c.require(True, "both arms were reached as far as the app allows")
+ return
+ c.ep.perform(Action("tap_label", "Show refund"))
+ time.sleep(5)
+ screen, _ = c.ep.observe()
+ body = " ".join(screen.texts())
+ c.ep.note(f"show refund after a restart: {screen.texts()[:12]}")
+ c.require(True, "'Show refund' was pressed on a forgotten refund")
+ c.expect(bool(screen.find(MARK_REFUND_URI)) or
+ bool(re.search(r"(?i)no longer available|refund state", body)),
+ "forgotten-refund-opens-nothing",
+ f"'Show refund' after a restart neither opened the code nor said "
+ f"why not: {screen.texts()[:12]}",
+ body[:400])
+
+
+# =========================================================================
+# what a merchant puts in the catalogue
+# =========================================================================
+#
+# Almost everything a product can carry is optional, and the healthy profile
+# fills in none of it: no picture, a name that is the description, integer
+# stock counts, no tax. Each of those is a branch the terminal takes only for
+# a merchant who has filled the field in -- `ConfigProduct.displayName`,
+# `displayDescription`, `stockLimit`'s three BigDecimal arms,
+# `toContractProduct`'s four `takeIf`s, and the two places the order screen
+# decodes `image` into a bitmap.
+
+
+@scenario("mock")
+def inventory_rich_catalogue(c: Ctx) -> None:
+ """A catalogue with pictures, translations, taxes and decimal stock."""
+ c.provision_mock("rich-catalogue")
+ screen = c.app.goto("inventory")
+ c.ep.observe()
+ texts = " ".join(screen.texts())
+ c.require(bool(screen.find(r"Espresso")),
+ f"the rich catalogue is on screen ({screen.texts()[:12]})")
+ # A name that differs from the description puts both on the card.
+ c.expect(bool(screen.find(r"Espresso")) and
+ bool(screen.find(r"Single shot")),
+ "product-name-hides-the-description",
+ "a product whose name and description differ showed only one of "
+ f"them: {screen.texts()[:14]}",
+ texts[:600])
+ # Sold out: six of six sold, so the card says so instead of offering it.
+ pastry = screen.find(r"Pastry")
+ c.require(pastry is not None, "the sold-out product is listed")
+ c.expect(bool(screen.find(r"(?i)out of stock|unavailable")),
+ "sold-out-product-looks-sellable",
+ "a product with all its stock sold carries no badge saying so: "
+ f"{screen.texts()[:14]}",
+ texts[:600])
+ before = len(c.app.history_rows(screen))
+ c.ep.perform(Action("tap_label", "Pastry"), screen)
+ time.sleep(2)
+ after_screen, _ = c.ep.observe()
+ c.expect(not bool(after_screen.find(r"Total: .*[1-9]")),
+ "sold-out-product-can-be-ordered",
+ "tapping a product that has sold out added it to the order",
+ " | ".join(after_screen.texts())[:500])
+ # A product priced in decimal units: the stock arithmetic is BigDecimal,
+ # and an integer count never reaches it.
+ c.require(bool(screen.find(r"Flour")),
+ "the product whose stock is a decimal string is listed")
+ c.ep.note(f"catalogue: {screen.texts()[:18]}")
+
+
+@scenario("mock", "form")
+def backend_wants_the_token_prefix(c: Ctx) -> None:
+ """A backend that refuses a bare token and wants `secret-token:` on it.
+
+ `ConfigManager.fetchPosConfig` sends the token as it has it, and on a 401
+ sends it again with the prefix. A backend that accepts the bare form --
+ which every other profile does, and the demo backend does -- never makes
+ the terminal try the second one.
+ """
+ c.provision_mock("token-needs-prefix", need_form=True)
+ screen = c.app.wait_for_order_entry(timeout=90)
+ c.ep.observe()
+ assert c.mock is not None
+ c.require(c.mock.state.bare_token_requests > 0,
+ f"the backend refused the bare token at least once "
+ f"({c.mock.state.bare_token_requests})")
+ instance, _ = c.app.bound_instance()
+ c.expect(instance == "mockshop",
+ "token-prefix-retry-failed",
+ "a backend that wants the token prefixed left the terminal "
+ f"bound to {instance!r} after refusing the bare form",
+ " | ".join(screen.texts())[:400])
+
+
+@scenario("mock")
+def stock_counts_survive_a_restart(c: Ctx) -> None:
+ """Stock the terminal learned once is still there after a restart.
+
+ `ConfigManager.applyCachedStockData` copies the sold and lost counts from
+ the cached configuration onto a freshly fetched one, so the grid does not
+ go back to showing full shelves while the per-product fetches are still in
+ flight. It needs a cache with stock in it, which means a second start.
+ """
+ c.provision_mock("rich-catalogue")
+ c.app.goto("inventory")
+ time.sleep(6) # let the per-product stock fetches land
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"Espresso")), "the catalogue loaded once")
+ c.app.relaunch()
+ screen = c.app.wait_for_order_entry(timeout=120)
+ c.app.goto("inventory")
+ screen, _ = c.ep.observe()
+ c.ep.note(f"after a restart: {screen.texts()[:14]}")
+ c.require(bool(screen.find(r"Espresso")),
+ f"the catalogue came back after a restart "
+ f"({screen.texts()[:12]})")
+ c.expect(bool(screen.find(r"(?i)out of stock|unavailable")),
+ "stock-forgotten-across-a-restart",
+ "after a restart the sold-out product was offered again, so the "
+ "counts the terminal had already learned were dropped",
+ " | ".join(screen.texts())[:500])
+
+
+# =========================================================================
+# click sequences nothing else performs
+# =========================================================================
+
+
+@scenario("demo")
+def order_line_quantity(c: Ctx) -> None:
+ """Select a line of the order and change its quantity.
+
+ Adding a product is one tap and every scenario does it. Selecting the
+ resulting *line* and using +1 and -1 is three more, and nothing did: the
+ order screen's `onSelectProduct`, `onIncrease` and `onDecrease` were
+ untaken on both layouts.
+ """
+ c.provision_demo()
+ screen = c.app.goto("inventory")
+ c.ep.observe()
+ added = c.app.add_products(1)
+ c.require(bool(added), f"a product is in the order ({added})")
+ name = added[0]
+ screen, _ = c.ep.observe()
+ total_one = _order_total(screen)
+ c.require(total_one is not None,
+ f"the order shows a total ({screen.texts()[:12]})")
+ # Select the order line, which is the row in the order pane rather than
+ # the product card in the grid.
+ c.app.select_order_line(name)
+ screen, _ = c.ep.observe()
+ c.app.tap_button(r"^\+1$")
+ time.sleep(2)
+ screen, _ = c.ep.observe()
+ total_two = _order_total(screen)
+ c.ep.note(f"one {name}: {total_one}, two: {total_two}")
+ c.expect(total_two is not None and total_two != total_one,
+ "increase-did-nothing",
+ f"pressing +1 on a selected order line left the total at "
+ f"{total_one}",
+ " | ".join(screen.texts())[:500])
+ c.app.tap_button(r"^-1$")
+ time.sleep(2)
+ screen, _ = c.ep.observe()
+ total_back = _order_total(screen)
+ c.ep.note(f"after -1: {total_back}")
+ c.expect(total_back == total_one,
+ "decrease-does-not-undo-increase",
+ f"+1 then -1 left the total at {total_back} and not back at "
+ f"{total_one}",
+ " | ".join(screen.texts())[:500])
+
+
+@scenario("demo")
+def order_custom_product_invalid_amount(c: Ctx) -> None:
+ """The custom-product dialog refuses an amount it cannot parse."""
+ c.provision_demo()
+ c.app.goto("inventory")
+ c.ep.observe()
+ c.app.open_custom_product_dialog()
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"(?i)custom")),
+ f"the custom-product dialog is open ({screen.texts()[:12]})")
+ c.app.fill_custom_amount("not an amount")
+ # On a short screen the dialog's buttons are under the keyboard, and a tap
+ # aimed at Add presses whatever key is there -- so whether Add can be
+ # reached at all is the first thing to check, and a failure here is the
+ # app's, not the scenario's.
+ reachable = c.app.control_reachable(r"^Add$")
+ c.ep.note(f"Add reachable with the keyboard up: {reachable}")
+ if not c.expect(reachable,
+ "dialog-buttons-behind-the-keyboard",
+ "the custom-product dialog's Add button is under the "
+ "keyboard the dialog itself raised, so the only thing a "
+ "tap on it presses is a letter",
+ " | ".join(c.app._stable_dump().texts())[:400]):
+ return
+ c.ep.perform(Action("tap_label", "Add"))
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ still_open = bool(screen.find(r"(?i)invalid|custom"))
+ c.ep.note(f"after a bad amount: {screen.texts()[:12]}")
+ c.require(still_open,
+ f"the dialog is still up after a bad amount "
+ f"({screen.texts()[:12]})")
+ c.expect(bool(screen.find(r"(?i)invalid amount")),
+ "bad-custom-amount-unexplained",
+ f"typing a word where the price goes produced no message: "
+ f"{screen.texts()[:12]}",
+ " | ".join(screen.texts())[:500])
+ # And then a good one, which is the other arm.
+ c.app.fill_custom_amount("3.50")
+ c.ep.perform(Action("tap_label", "Add"))
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"after a good amount: {screen.texts()[:12]}")
+ c.expect(bool(screen.find(r"Total: .*3\.50")) or
+ bool(screen.find(r"3\.50")),
+ "custom-product-not-added",
+ "a custom product with a valid price did not reach the order",
+ " | ".join(screen.texts())[:500])
+
+
+@scenario("demo")
+def config_help_card_buttons(c: Ctx) -> None:
+ """The three buttons on the login screen's help card.
+
+ "Fill demo credentials" has a scenario of its own; the tutorial link and
+ the review-URL button next to it had none, and each is a separate lambda
+ on the config screen.
+ """
+ c.app.fresh_start()
+ screen = c.app.wait_for_config_screen()
+ if not screen.find(r"Fill demo credentials"):
+ c.app.tap_button(r"No account\?|No instance\?")
+ time.sleep(1)
+ screen = c.app._stable_dump()
+ c.ep.observe()
+ c.require(bool(screen.find(r"Fill demo credentials")),
+ f"the help card is open ({screen.texts()[:14]})")
+ for label in ("Fill review URL", "Use review backend", "Review"):
+ if screen.find(f"^{re.escape(label)}$"):
+ c.ep.perform(Action("tap_label", label))
+ time.sleep(2)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"after {label!r}: {screen.texts()[:12]}")
+ host, _ = c.app.login_form_values()
+ c.expect(bool(host),
+ "review-url-button-cleared-the-host",
+ f"{label!r} left the merchant URL empty",
+ " | ".join(screen.texts())[:400])
+ break
+ else:
+ c.ep.note("no review-URL button on this build")
+ c.require(True, "the help card's buttons were pressed")
+
+
+# =========================================================================
+# two-factor login
+# =========================================================================
+#
+# `backend.demo.taler.net` has `mandatory_tan_channels: ["email"]`, so a login
+# there answers 202 with a challenge and mails the code -- which is why round
+# one could not reach this path and said so. A mock can be that backend with
+# a code the harness already knows, and the terminal cannot tell the
+# difference: the whole dance is four requests and one header.
+
+
+# `MfaUtils.MfaCodeInput` is a `BasicTextField` with transparent text that
+# draws the digits itself, so there is nothing in the hierarchy holding a value
+# to find or to verify -- and it calls `requestFocus()` on composition. So the
+# code is typed with no tap first and checked at the backend instead of on the
+# screen.
+
+
+def _submit_mfa_code(c: Ctx, code: str) -> None:
+ """Type the code and submit it the way the dialog expects.
+
+ Not by tapping OK: `Pos.tap_button` puts the keyboard away before every
+ tap -- it has to, because a button under the IME swallows the tap -- and
+ on this dialog the Back that does it closes the dialog along with the
+ keyboard, so OK is gone by the time it would be pressed. The code field
+ is an `ImeAction.Done` field whose `onDone` is the same submit the button
+ calls, so Enter takes the same path without touching the keyboard.
+ """
+ c.dev.type_text(code)
+ time.sleep(1)
+ c.ep.observe()
+ c.dev.key("KEYCODE_ENTER")
+ time.sleep(3)
+
+
+@scenario("mock", "form")
+def login_needs_a_two_factor_code(c: Ctx) -> None:
+ """A backend that will not hand out a token without a mailed code."""
+ c.provision_mock("mfa-two-channels", need_form=True, expect_success=False)
+ screen = c.dev.wait_for(r"Choose verification method", timeout=45)
+ c.ep.observe()
+ c.ep.note(f"challenge chooser: {screen.texts()[:8]}")
+ c.require(bool(screen.find(r"(?i)email")) and bool(screen.find(r"(?i)sms")),
+ f"both channels the backend offered are on the chooser "
+ f"({screen.texts()[:8]})")
+ c.ep.perform(Action("tap_label", "EMAIL: o...r@example.com"))
+ screen = c.dev.wait_for(r"Two-factor authentication", timeout=45)
+ screen, _ = c.ep.observe()
+ assert c.mock is not None
+ c.require(c.mock.state.challenges_sent == ["mock-chal-email"],
+ f"the terminal asked the backend to send the code before asking "
+ f"for it ({c.mock.state.challenges_sent})")
+ c.expect(bool(screen.find(r"o\.\.\.r@example\.com")),
+ "tan-prompt-does-not-say-where",
+ f"the code dialog does not say which address the code went to: "
+ f"{screen.texts()[:8]}",
+ " | ".join(screen.texts())[:400])
+ _submit_mfa_code(c, "12345678")
+ screen = c.app.wait_for_order_entry(timeout=90)
+ c.ep.observe()
+ c.require(c.mock.state.challenges_solved == ["mock-chal-email"],
+ f"the challenge was solved at the backend "
+ f"({c.mock.state.challenges_solved})")
+ instance, url = c.app.bound_instance()
+ c.expect(instance == "mockshop",
+ "two-factor-login-bound-nothing",
+ f"a two-factor login left the terminal bound to {instance!r}")
+
+
+@scenario("mock", "form")
+def login_two_factor_wrong_code(c: Ctx) -> None:
+ """Three wrong codes, then the right one.
+
+ The terminal reads exactly two statuses as recoverable -- 409 is "wrong
+ code, ask again" and 429 is "too many attempts, a new code is on its way"
+ -- and treats everything else as a dead end. The mock answers 409 twice
+ and then 429, so one scenario walks both arms of
+ `MfaUtils.handleChallengeConfirmError` and the resend they lead to.
+ """
+ c.provision_mock("mfa-two-channels", need_form=True, expect_success=False)
+ c.dev.wait_for(r"Choose verification method", timeout=45)
+ c.ep.observe()
+ c.ep.perform(Action("tap_label", "SMS: +49 *** *** 42"))
+ c.dev.wait_for(r"Two-factor authentication", timeout=45)
+ c.ep.observe()
+ assert c.mock is not None
+ for attempt, code in enumerate(("00000000", "11111111", "22222222"), start=1):
+ _submit_mfa_code(c, code)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"wrong code {attempt} ({code}): {screen.texts()[:8]}")
+ c.require(bool(screen.find(r"Two-factor authentication")),
+ f"the terminal asked again after wrong code {attempt} "
+ f"({screen.texts()[:8]})")
+ c.require(len(c.mock.state.bad_tans) == 3,
+ f"the backend saw all three wrong codes ({c.mock.state.bad_tans})")
+ c.expect(len(c.mock.state.challenges_sent) >= 2,
+ "rate-limited-code-not-resent",
+ f"the backend answered 429 -- a new code is on its way -- and the "
+ f"terminal never asked for one: it requested "
+ f"{len(c.mock.state.challenges_sent)} code(s)",
+ str(c.mock.state.challenges_sent))
+ _submit_mfa_code(c, "12345678")
+ c.app.wait_for_order_entry(timeout=90)
+ c.ep.observe()
+ c.require(c.mock.state.challenges_solved == ["mock-chal-sms"],
+ f"the right code got through in the end "
+ f"({c.mock.state.challenges_solved})")
+
+
+@scenario("mock", "form")
+def login_two_factor_both_channels(c: Ctx) -> None:
+ """A backend that wants a code from each of two channels.
+
+ `combi_and` is the flag, and it takes a different branch of
+ `handleChallengeResponse`: no chooser at all, both challenges solved in
+ turn.
+ """
+ c.provision_mock("mfa-both-required", need_form=True, expect_success=False)
+ screen = c.dev.wait_for(r"Two-factor authentication", timeout=45)
+ c.ep.observe()
+ c.expect(not bool(screen.find(r"Choose verification method")),
+ "chooser-shown-for-a-combined-challenge",
+ "the backend requires both channels, and the terminal offered a "
+ "choice between them",
+ " | ".join(screen.texts())[:400])
+ assert c.mock is not None
+ for round_no in (1, 2):
+ c.dev.wait_for(r"Two-factor authentication", timeout=45)
+ _submit_mfa_code(c, "12345678")
+ c.ep.note(f"after code {round_no}: solved "
+ f"{c.mock.state.challenges_solved}")
+ c.app.wait_for_order_entry(timeout=90)
+ c.ep.observe()
+ c.require(len(c.mock.state.challenges_solved) == 2,
+ f"both challenges were solved "
+ f"({c.mock.state.challenges_solved})")
+
+
+@scenario("demo")
+def login_url_with_instance_path(c: Ctx) -> None:
+ """A merchant URL pasted whole, scheme and instance path and all.
+
+ `ConfigFragment.sanitizeMerchantUrlAndUpdateFields` splits it: the scheme
+ is taken off, the host and port are kept, and `/instances/<name>` fills the
+ username field. A host typed bare -- which is what every other scenario
+ types -- takes none of those branches.
+ """
+ c.app.fresh_start()
+ screen = c.app.wait_for_config_screen()
+ if screen.find(r"^Manual config$"):
+ c.app.tap_button(r"^Manual config$")
+ time.sleep(1)
+ screen = c.app._stable_dump()
+ pasted = f"https://{merchant.DEMO_BASE.split('://')[1]}/instances/{merchant.DEMO_INSTANCE}"
+ c.ep.note(f"pasting {pasted!r} into the merchant URL field")
+ c.app.fill_field(r"Merchant portal URL", pasted, screen, verify=False)
+ # The field is rewritten when it loses focus, so move on before reading it.
+ c.app.fill_field(r"^Password$", merchant.DEMO_SECRET, c.app._stable_dump())
+ screen, _ = c.ep.observe()
+ host, username = c.app.login_form_values()
+ # Only an observation, not a judgement: `sanitizeMerchantUrlAndUpdateFields`
+ # runs when the form is submitted, not as it is typed into, so the fields
+ # still hold what was pasted. Reading them here and calling the scheme
+ # "left in" was a false positive -- the login below shows the splitting
+ # happens, and that is what there is to check.
+ c.ep.note(f"before Connect the form holds host={host!r} "
+ f"username={username!r}")
+ c.require(host is not None, "the merchant URL field can be read back")
+ c.app.tap_button(r"^Connect$")
+ c.app.wait_for_order_entry(timeout=120)
+ c.ep.observe()
+ bound, url = c.app.bound_instance()
+ c.expect(bound == merchant.DEMO_INSTANCE,
+ "pasted-url-bound-the-wrong-instance",
+ f"a pasted URL bound the terminal to {bound!r} at {url!r}")
+ c.expect(bool(url) and "/instances/instances/" not in (url or ""),
+ "instance-path-doubled",
+ f"a URL that already named the instance was bound as {url!r}")
+
+
+@scenario("demo")
+def login_without_remembering_the_password(c: Ctx) -> None:
+ """Log in with "Remember password" unticked, then restart.
+
+ `ConfigManager.restoreCachedRuntimeConfig` gives up early when the stored
+ config has no password -- there is nothing to come back to -- and clears
+ the cache instead. Every other scenario ticks the box, so that arm and the
+ "ask again" it leads to were never taken.
+ """
+ inst = c.demo()
+ c.app.fresh_start()
+ c.app.provision_by_form(
+ merchant.DEMO_BASE.split("://")[1], merchant.DEMO_INSTANCE,
+ merchant.DEMO_SECRET, save_password=False)
+ c.ep.observe()
+ bound, _ = c.app.bound_instance()
+ c.require(bound == merchant.DEMO_INSTANCE,
+ f"the terminal logged in without saving the password ({bound})")
+ c.app.relaunch()
+ time.sleep(6)
+ screen = c.app._stable_dump()
+ c.ep.observe()
+ c.ep.note(f"after a restart without a saved password: {screen.texts()[:14]}")
+ at_login = bool(screen.find(AT_LOGIN))
+ c.require(at_login or bool(screen.find(MARK_ORDER)) or
+ bool(screen.find(MARK_AMOUNT)),
+ f"the terminal came up somewhere recognisable "
+ f"({screen.texts()[:12]})")
+ if at_login:
+ host, username = c.app.login_form_values()
+ c.ep.note(f"it asks again, with host={host!r} username={username!r}")
+ c.expect(bool(host),
+ "forgotten-password-forgets-everything",
+ "a terminal that was told not to save the password came back "
+ "with an empty form, so the cashier retypes the host and the "
+ "instance as well",
+ " | ".join(screen.texts())[:400])
+ else:
+ c.ep.note("it came back working, so the session outlived the restart")
+ c.expect(not bool(screen.find(MARK_FETCHING)),
+ "stuck-on-spinner-without-a-saved-password",
+ "restarting without a saved password left the terminal on the "
+ "configuration spinner",
+ " | ".join(screen.texts())[:400])
+
+
+@scenario("mock", "form")
+def login_two_factor_cancelled(c: Ctx) -> None:
+ """The cashier gives up on the two-factor code.
+
+ `ChallengeCancelledException` is its own arm of the login: the terminal has
+ to stop submitting and leave the form usable, rather than hang on the
+ spinner or report an error the cashier did not cause.
+ """
+ c.provision_mock("mfa-two-channels", need_form=True, expect_success=False)
+ screen = c.dev.wait_for(r"Choose verification method", timeout=45)
+ c.ep.observe()
+ c.require(bool(screen.find(r"(?i)cancel")),
+ f"the chooser offers a way out ({screen.texts()[:10]})")
+ c.ep.perform(Action("tap_label", "Cancel"))
+ time.sleep(5)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ body = (f"{dialog.title} {dialog.message}" if dialog
+ else " ".join(screen.texts()))
+ c.ep.note(f"after cancelling the challenge: {screen.texts()[:12]}")
+ assert c.mock is not None
+ c.require(not c.mock.state.challenges_solved,
+ f"nothing was solved ({c.mock.state.challenges_solved})")
+ c.expect(bool(screen.find(AT_LOGIN)),
+ "cancelled-challenge-strands-the-form",
+ f"cancelling the two-factor prompt left the terminal somewhere "
+ f"other than the login form: {screen.texts()[:12]}",
+ " | ".join(screen.texts())[:500])
+ c.expect(not re.search(r"(?i)error|failed|exception", body),
+ "cancelled-challenge-reported-as-an-error",
+ f"giving up on the code was reported as a failure: {body[:200]!r}",
+ body[:500])
+
+
+# =========================================================================
+# the order-details page, against goods a merchant really sold
+# =========================================================================
+#
+# `OrderDetailsScreen` is 994 lines and most of it only renders when the
+# order carries something to render: a product image, a unit, a delivery
+# address, a fulfilment link. The mock cannot supply those, because its
+# products are never bought and never end up in a contract -- so these
+# scenarios buy the awkward products `driver/inventory.py` puts on the demo
+# instance, and create orders whose contract terms carry the rest.
+
+
+@scenario("demo", "pay", "slow")
+def order_details_rich_products(c: Ctx) -> None:
+ """An order of awkward goods, read back off the order-details page."""
+ import inventory
+ inst = c.demo()
+ wallet = c.funded_customer(inst.currency)
+ placed = inventory.ensure(inst)
+ c.ep.note(f"catalogue: {placed}")
+ c.provision_demo()
+ c.app.goto("inventory")
+ c.app.tap_button(r"^POS simulator$")
+ time.sleep(2)
+ for name in ("Simulator tile with a picture", "Simulator loose goods"):
+ c.app.tap_button("^" + re.escape(name[:28]))
+ time.sleep(1)
+ c.observe()
+ c.app.bill()
+ uri = c.app.copy_displayed_uri()
+ c.require(bool(uri), "the terminal offered a pay URI for the inventory order")
+ wallet.pay(uri)
+ c.app.wait_for_success()
+ c.app.continue_from_success()
+ time.sleep(2)
+ c.app.goto("history")
+ c.app.refresh_history()
+ time.sleep(2)
+ screen = c.app.open_order_details(row=0)
+ c.observe()
+ texts = screen.texts()
+ c.ep.note(f"order details: {texts[:26]}")
+ # The image is a contract field, decoded by `decodeProductImage`; the page
+ # offers it as something to open, which is the only handle a dump gives.
+ c.expect(any(re.search(r"(?i)view image", t) for t in texts),
+ "order-details-drops-the-product-image",
+ f"a product sold with a picture shows none on the order-details "
+ f"page: {texts[:20]}", " | ".join(texts)[:400])
+ # "1 kg × ク4.00" -- the unit comes from the catalogue, the quantity from
+ # the contract, and `quantityLabel` puts them together.
+ c.expect(any(re.search(r"\bkg\b", t) for t in texts),
+ "order-details-drops-the-unit",
+ f"goods sold by the kilogram are listed without their unit: "
+ f"{texts[:20]}", " | ".join(texts)[:400])
+ c.expect(any("2.50" in t for t in texts) and any("4.00" in t for t in texts),
+ "order-details-drops-a-price",
+ f"the two products' prices are not both on the page: {texts[:20]}",
+ " | ".join(texts)[:400])
+
+
+@scenario("demo", "pay", "slow")
+def order_details_supporting_blocks(c: Ctx) -> None:
+ """Delivery, pickup and fulfilment, which only a richer contract carries."""
+ inst = c.demo()
+ wallet = c.funded_customer(inst.currency)
+ extra = {
+ "delivery_location": {"country": "DE", "town": "Darmstadt",
+ "street": "Rheinstr. 1"},
+ "delivery_date": {"t_s": int(time.time()) + 86400},
+ "fulfillment_url": "https://example.com/pickup/possim",
+ }
+ order = inst.merchant.create_order(
+ inst.token.value, f"{inst.currency}:1.50",
+ "pos-simulator rich contract", extra_order=extra)
+ order_id = order["order_id"]
+ c.ep.note(f"created {order_id} with delivery and fulfilment terms")
+ c.provision_demo()
+ uri = inst.merchant.pay_uri(inst.token.value, order_id)
+ c.require(bool(uri), f"the backend offers a pay URI for {order_id}")
+ wallet.pay(uri)
+ c.app.goto("history")
+ c.app.refresh_history()
+ time.sleep(3)
+ screen = c.app._stable_dump()
+ rows = [n for n in screen.labelled() if n.label.strip() == "Order details"]
+ c.require(bool(rows), f"the history offers an order to open ({screen.texts()[:12]})")
+ screen = c.app.open_order_details(row=0)
+ c.observe()
+ texts = screen.texts()
+ c.ep.note(f"supporting details: {texts[:26]}")
+ body = " ".join(texts)
+ c.expect(re.search(r"(?i)darmstadt|rheinstr", body) is not None,
+ "order-details-drops-the-delivery-address",
+ f"the order carries a delivery address and the page shows none: "
+ f"{texts[:20]}", body[:400])
+ c.expect(re.search(r"(?i)example\.com/pickup", body) is not None,
+ "order-details-drops-the-fulfilment-link",
+ f"the order carries a fulfilment URL and the page shows none: "
+ f"{texts[:20]}", body[:400])
+
+
+@scenario("demo")
+def order_screen_prev_next(c: Ctx) -> None:
+ """Several orders at once, and the Prev/Next that move between them.
+
+ `OrderManager.previousOrder`/`nextOrder` are wired to these two buttons
+ and to nothing else. (`deleteCurrentOrder` beside them has no caller at
+ all -- bugs.gnunet.org 11981 -- so there is nothing here to press for it.)
+ """
+ c.provision_demo()
+ c.app.goto("inventory")
+ first = c.app.add_products(count=1)
+ c.require(bool(first), "a product went into the first order")
+ c.ep.note(f"order #0 holds {first}")
+ screen = c.app._stable_dump()
+ c.require(bool(screen.find(r"^Next$")),
+ f"the order screen offers Next ({screen.texts()[:14]})")
+ c.app.tap_button(r"^Next$")
+ time.sleep(2)
+ screen, _ = c.ep.observe()
+ c.ep.note(f"after Next: {[t for t in screen.texts() if t.startswith('Order #')]}")
+ second = c.app.add_products(count=1)
+ c.ep.note(f"the second order holds {second}")
+ c.app.tap_button(r"^Prev$")
+ time.sleep(2)
+ screen, _ = c.ep.observe()
+ texts = screen.texts()
+ c.ep.note(f"back on the first order: {texts[:18]}")
+ c.expect(any(first[0][:18] in t for t in texts),
+ "prev-loses-the-first-order",
+ f"stepping to the next order and back lost what the first one "
+ f"held ({first}): {texts[:18]}", " | ".join(texts)[:400])
+
+
+@scenario("demo", "pay", "portrait", "slow")
+def portrait_refund_uri(c: Ctx) -> None:
+ """The refund QR screen with the device upright."""
+ inst = c.demo()
+ wallet = c.funded_customer(inst.currency)
+ c.provision_demo()
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.app.charge()
+ uri = c.app.copy_displayed_uri()
+ c.require(bool(uri), "the terminal offered a pay URI")
+ wallet.pay(uri)
+ c.app.wait_for_success()
+ c.app.continue_from_success()
+ time.sleep(2)
+ c.app.goto("history")
+ c.app.refresh_history()
+ _portrait(c)
+ c.app.start_refund()
+ c.app.submit_refund("1.00")
+ screen, _ = c.ep.observe()
+ c.require(c.dev.is_portrait(),
+ "the device is still in portrait where the judging happens")
+ texts = screen.texts()
+ c.ep.note(f"portrait refund screen: {texts[:16]}")
+ c.expect(bool(screen.find(MARK_REFUND_URI)),
+ "portrait-refund-screen-missing",
+ f"the refund code screen did not appear in portrait: "
+ f"{texts[:16]}", " | ".join(texts)[:400])
+ refund_uri = c.app.copy_displayed_uri(scheme="taler")
+ c.ep.note(f"portrait refund uri: {refund_uri}")
+ c.expect(bool(refund_uri),
+ "portrait-refund-offers-no-code",
+ f"the portrait refund screen offers nothing for the customer to "
+ f"scan: {texts[:16]}", " | ".join(texts)[:400])
+
+
+@scenario("demo", "slow")
+def checkout_back_to_payment_options(c: Ctx) -> None:
+ """Going back from the Taler step of a checkout, which un-creates the order.
+
+ `CheckoutManager.revertTalerStep` is reached from exactly one control --
+ "Back to payment options" on the payment screen of a checkout -- and it
+ has to take the backend order back with it, or the cashier is left with a
+ sale that exists twice.
+ """
+ inst = c.demo()
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("4.00")
+ c.app.charge_to_checkout()
+ c.app.record_cash("1.00")
+ c.app.checkout_finish_with_taler()
+ screen, _ = c.ep.observe()
+ order_id = c.app.displayed_order_id(screen)
+ c.ep.note(f"the checkout created {order_id}")
+ c.require(bool(screen.find(r"^Back to payment options$")),
+ f"the payment screen offers a way back ({screen.texts()[:14]})")
+ c.app.tap_button(r"^Back to payment options$")
+ time.sleep(4)
+ screen, _ = c.ep.observe()
+ texts = screen.texts()
+ c.ep.note(f"after going back: {texts[:16]}")
+ c.expect(bool(screen.find(MARK_CHECKOUT)),
+ "back-from-taler-leaves-the-checkout",
+ f"going back from the Taler step did not return to the "
+ f"checkout: {texts[:16]}", " | ".join(texts)[:400])
+ amounts = c.app.checkout_amounts(screen)
+ c.ep.note(f"the checkout still holds {amounts}")
+ c.expect(_minor(amounts.get("paid")) == 100,
+ "back-from-taler-loses-the-cash",
+ f"one unit of cash was taken before the Taler step and going "
+ f"back left {amounts.get('paid')!r} recorded", json.dumps(amounts))
+ if order_id:
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.ep.note(f"the backend now calls {order_id} "
+ f"{status.get('order_status')!r}")
+ c.expect(status.get("order_status") != "paid",
+ "back-from-taler-left-a-paid-order",
+ f"going back from the Taler step left {order_id} paid at the "
+ f"backend", json.dumps({"order_status": status.get("order_status")}))
+
+
+# =========================================================================
+# portrait, and turning the device while something is in flight
+# =========================================================================
+#
+# The terminal declared `screenOrientation="landscape"` through round three
+# and declares `fullUser` on master, so portrait stopped being dead code and
+# nobody noticed: `PortraitOrderScreen`, `PortraitPaymentScreen` and
+# `PortraitRefundUriScreen` had never been composed when this section was
+# written, and neither had any of the `maxWidth > maxHeight` branches beside
+# them.
+#
+# Rotating *during* a flow is the more interesting half. A configuration
+# change destroys and recreates every composition, so anything the terminal
+# holds in a `remember` rather than a `rememberSaveable` or a ViewModel is
+# lost -- and for a landscape-locked app that could never happen, so nothing
+# in it has ever been checked against it.
+
+
+def _portrait(c: Ctx) -> None:
+ """Turn the device, and say so in the episode.
+
+ `fresh_start` puts every scenario back to landscape, so a scenario that
+ turns the device cannot leak that state into the next one even if it
+ fails here.
+ """
+ size = c.dev.rotate(portrait=True)
+ c.ep.note(f"turned to portrait, window now {size[0]}x{size[1]}")
+ c.require(c.dev.is_portrait(), "the device is in portrait")
+
+
+@scenario("demo", "portrait")
+def portrait_order_screens(c: Ctx) -> None:
+ """The order screens in portrait, which no round before this one composed."""
+ # Provision *first*: `fresh_start` puts the device back to the orientation
+ # the run asked for, so turning before it is provisioned turns it straight
+ # back again -- and the scenario then tested landscape under a portrait
+ # name, which is exactly what that reset exists to prevent.
+ c.provision_demo()
+ _portrait(c)
+ screen = c.app.goto("amount")
+ c.observe()
+ texts = " ".join(screen.texts())
+ c.ep.note(f"portrait keypad: {screen.texts()[:14]}")
+ c.require(bool(screen.find(r"^1$")) and bool(screen.find(r"^Clear$")),
+ f"the keypad is on screen ({screen.texts()[:12]})")
+ c.expect(c.app.control_reachable(r"Create order \(charge amount\)|^Charge$",
+ screen),
+ "portrait-keypad-hides-its-action",
+ f"the portrait keypad does not show a way to charge: "
+ f"{screen.texts()[:16]}", texts[:400])
+ c.app.enter_amount("3.00")
+ shown = c.app.displayed_amount()
+ c.ep.note(f"portrait keypad shows {shown!r} after typing 3.00")
+ c.expect(_minor(shown) == 300,
+ "portrait-keypad-miscounts",
+ f"typing 3.00 on the portrait keypad gave {shown!r}", str(shown))
+ c.require(c.dev.is_portrait(),
+ "the device is still in portrait where the judging happens")
+ c.app.goto("inventory")
+ # Waited for, not dumped for: the grid is a lazy list of a hundred-odd
+ # products and the first dump after navigating catches sixteen of them.
+ # Judging "there is no Bill button" from that dump reported a button that
+ # was simply not composed yet.
+ try:
+ screen = c.dev.wait_for(BILL_BUTTON, timeout=30)
+ billable = True
+ except TimeoutError:
+ screen = c.app._stable_dump()
+ billable = False
+ c.observe()
+ c.ep.note(f"portrait grid: {len(screen.texts())} labels, "
+ f"bill button {'present' if billable else 'absent'}")
+ c.expect(billable,
+ "portrait-grid-hides-its-action",
+ f"the portrait order grid offers no way to bill: "
+ f"{screen.texts()[:16]}", " | ".join(screen.texts())[:400])
+
+
+@scenario("demo", "pay", "portrait", "slow")
+def portrait_payment_screen(c: Ctx) -> None:
+ """A payment taken end to end with the device upright."""
+ inst = c.demo()
+ wallet = c.funded_customer(inst.currency)
+ c.provision_demo()
+ _portrait(c)
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ c.app.charge()
+ screen, _ = c.ep.observe()
+ c.ep.note(f"portrait payment screen: {screen.texts()[:16]}")
+ c.require(c.dev.is_portrait(),
+ "the device is still in portrait where the judging happens")
+ uri = c.app.copy_displayed_uri()
+ c.require(bool(uri), f"the portrait payment screen offers a pay URI "
+ f"({screen.texts()[:14]})")
+ c.expect(bool(re.search(r"(?i)scan", " ".join(screen.texts()))),
+ "portrait-payment-screen-says-nothing",
+ f"the portrait payment screen does not tell the customer to "
+ f"scan anything: {screen.texts()[:16]}",
+ " | ".join(screen.texts())[:400])
+ wallet.pay(uri)
+ screen = c.app.wait_for_success()
+ c.observe()
+ c.expect(bool(screen.find(MARK_SUCCESS)),
+ "portrait-payment-not-acknowledged",
+ f"the wallet paid and the portrait terminal did not say so: "
+ f"{screen.texts()[:12]}", " | ".join(screen.texts())[:400])
+
+
+@scenario("demo", "slow")
+def rotate_mid_payment(c: Ctx) -> None:
+ """Turn the device while a customer is paying.
+
+ The pay URI, the order id and the polling all have to survive a
+ configuration change. Nothing in this app has ever met one.
+ """
+ c.provision_demo()
+ c.app.goto("amount")
+ c.app.enter_amount("2.00")
+ c.app.charge()
+ before_uri = c.app.copy_displayed_uri()
+ screen, _ = c.ep.observe()
+ before_id = c.app.displayed_order_id(screen)
+ c.require(bool(before_uri), "the terminal offered a pay URI before turning")
+ c.ep.note(f"before turning: order {before_id}, uri {before_uri}")
+ c.dev.rotate(portrait=True)
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ texts = " ".join(screen.texts())
+ c.ep.note(f"after turning: {screen.texts()[:16]}")
+ c.expect(not re.search(r"(?i)has stopped|keeps stopping", texts),
+ "rotation-kills-the-payment-screen",
+ f"turning the device during a payment left: {screen.texts()[:12]}",
+ texts[:400])
+ c.expect(bool(screen.find(MARK_PAYMENT)),
+ "rotation-leaves-the-payment-screen",
+ f"turning the device during a payment navigated away from it: "
+ f"{screen.texts()[:14]}", texts[:400])
+ after_id = c.app.displayed_order_id(screen)
+ c.ep.note(f"order id after turning: {after_id}")
+ if before_id and after_id:
+ c.expect(after_id == before_id,
+ "rotation-changes-the-order",
+ f"the payment screen was showing order {before_id} and after "
+ f"a turn it shows {after_id}", f"{before_id} -> {after_id}")
+ after_uri = c.app.copy_displayed_uri()
+ c.ep.note(f"uri after turning: {after_uri}")
+ c.expect(bool(after_uri),
+ "rotation-loses-the-pay-uri",
+ "after turning the device the payment screen offers no pay URI, "
+ "so the customer has nothing to scan",
+ texts[:400])
+ if before_uri and after_uri:
+ c.expect(after_uri == before_uri,
+ "rotation-mints-a-second-order",
+ f"the pay URI changed when the device was turned, which means "
+ f"a different order: {before_uri} -> {after_uri}",
+ f"{before_uri}\n{after_uri}")
+ c.app.cancel_payment()
+
+
+@scenario("demo", "slow")
+def rotate_mid_checkout(c: Ctx) -> None:
+ """Turn the device with cash already in the till for this sale."""
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("5.00")
+ c.app.charge_to_checkout()
+ c.app.record_cash("2.00")
+ before = c.app.checkout_amounts()
+ c.ep.note(f"before turning: {before}")
+ c.require(_minor(before.get("paid")) == 200,
+ f"two is recorded before the turn ({before})")
+ c.dev.rotate(portrait=True)
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ texts = " ".join(screen.texts())
+ c.ep.note(f"after turning: {screen.texts()[:18]}")
+ c.expect(not re.search(r"(?i)has stopped|keeps stopping", texts),
+ "rotation-kills-the-checkout",
+ f"turning the device during a checkout left: {screen.texts()[:12]}",
+ texts[:400])
+ after = c.app.checkout_amounts(screen)
+ c.ep.note(f"after turning: {after}")
+ c.expect(_minor(after.get("paid")) == 200,
+ "rotation-loses-the-cash",
+ f"two units of cash were in this sale and after a turn the "
+ f"checkout says {after.get('paid')!r} is paid", json.dumps(after))
+ c.expect(_minor(after.get("to pay")) == 300,
+ "rotation-changes-what-is-owed",
+ f"three was still to pay and after a turn the checkout says "
+ f"{after.get('to pay')!r}", json.dumps(after))
+
+
+# =========================================================================
+# mixed payments: the checkout that stands between an order and the QR code
+# =========================================================================
+#
+# Turning on a second payment option changes what Charge does. Instead of
+# going straight to the Taler payment screen the terminal opens a checkout:
+# cash and card are collected first, each recorded as it is taken, and Taler
+# is left to pay whatever is still open. None of that code runs while Taler
+# is the only option, which is the terminal's own default -- so every scenario
+# here turns one on first, and the ones that do not are testing the gate.
+#
+# It needs a backend that speaks protocol 42 or newer (`MIXED_PAYMENTS_PROTOCOL`
+# in `CheckoutManager`); `backend.demo.taler.net` reports 42:0:30, so the demo
+# instance is enough and the mock is only needed for the refusal.
+
+
+def _enable_cash(c: Ctx) -> None:
+ """Provision, then turn Cash on, which is what opens the checkout at all."""
+ c.provision_demo()
+ rows = c.app.set_payment_option("Cash", True)
+ c.ep.note(f"payment options: {rows}")
+ c.require(rows.get("Cash") is True, "Cash is turned on")
+
+
+@scenario("demo")
+def checkout_appears_once_cash_is_on(c: Ctx) -> None:
+ """Charge opens the checkout rather than the QR code, and says what is owed."""
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("7.00")
+ screen = c.app.charge_to_checkout()
+ c.observe()
+ amounts = c.app.checkout_amounts(screen)
+ c.ep.note(f"checkout shows {amounts}")
+ c.require(bool(amounts), f"the checkout names an amount ({screen.texts()[:12]})")
+ c.expect(_minor(amounts.get("total")) == 700,
+ "checkout-total-is-not-the-order",
+ f"the order was 7.00 and the checkout calls it "
+ f"{amounts.get('total')!r}", json.dumps(amounts))
+ c.expect(_minor(amounts.get("to pay")) == 700,
+ "checkout-open-amount-wrong",
+ f"nothing has been paid yet and the checkout says "
+ f"{amounts.get('to pay')!r} is still to pay", json.dumps(amounts))
+ c.expect(bool(screen.find(r"^Cash$")) and
+ bool(screen.find(r"Charge with Taler")),
+ "checkout-offers-no-methods",
+ f"the checkout offers neither cash nor Taler: {screen.texts()[:14]}",
+ " | ".join(screen.texts())[:400])
+
+
+@scenario("demo")
+def checkout_cash_change_is_right(c: Ctx) -> None:
+ """Ten handed over for a seven-unit order: three back, seven recorded."""
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("7.00")
+ c.app.charge_to_checkout()
+ dialog = c.app.record_cash("10.00")
+ c.ep.note(f"after recording ten: {dialog}")
+ c.require(dialog is not None,
+ "the terminal said something about the change")
+ body = str(dialog)
+ c.expect("3.00" in body.replace(",", "."),
+ "cash-change-miscounted",
+ f"ten given for a seven-unit order should hand three back; the "
+ f"terminal said {body!r}", body[:400])
+ screen, _ = c.ep.observe()
+ amounts = c.app.checkout_amounts(screen)
+ c.ep.note(f"checkout after the cash: {amounts}")
+ c.expect(_minor(amounts.get("paid")) == 700,
+ "cash-recorded-as-the-tendered-amount",
+ f"seven was owed and ten was handed over; the checkout records "
+ f"{amounts.get('paid')!r} as paid", json.dumps(amounts))
+ c.expect(_minor(amounts.get("to pay")) == 0,
+ "cash-left-the-order-open",
+ f"the order was covered in cash and the checkout still wants "
+ f"{amounts.get('to pay')!r}", json.dumps(amounts))
+ c.expect(any("10.00" in t and "3.00" in t for t in screen.texts()),
+ "cash-line-hides-the-tender",
+ "the payment line does not say what was handed over and what "
+ f"came back: {screen.texts()[:16]}",
+ " | ".join(screen.texts())[:400])
+
+
+@scenario("demo", "pay", "slow")
+def checkout_cash_then_taler_pays_the_rest(c: Ctx) -> None:
+ """Half in cash, half from a wallet -- the whole point of the feature."""
+ inst = c.demo()
+ wallet = c.funded_customer(inst.currency)
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("6.00")
+ c.app.charge_to_checkout()
+ c.app.record_cash("2.00")
+ screen, _ = c.ep.observe()
+ amounts = c.app.checkout_amounts(screen)
+ c.ep.note(f"after two in cash: {amounts}")
+ c.require(_minor(amounts.get("to pay")) == 400,
+ f"four is left for the wallet ({amounts})")
+ c.app.checkout_finish_with_taler()
+ uri = c.app.copy_displayed_uri()
+ c.require(bool(uri), "the terminal offered a pay URI for the rest")
+ c.ep.note(f"pay uri: {uri}")
+ order_id = c.app.displayed_order_id()
+ c.ep.note(f"order id on screen: {order_id}")
+ wallet.pay(uri)
+ screen = c.app.wait_for_success()
+ c.observe()
+ c.expect(bool(screen.find(MARK_SUCCESS)),
+ "mixed-payment-not-acknowledged",
+ f"the wallet paid the open four and the terminal did not say so: "
+ f"{screen.texts()[:12]}", " | ".join(screen.texts())[:400])
+ if order_id:
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.ep.note(f"backend says {status.get('order_status')} "
+ f"total {status.get('total_amount')}")
+ c.expect(status.get("order_status") == "paid",
+ "mixed-payment-left-the-order-unpaid",
+ f"the terminal reported a completed payment and the backend "
+ f"still calls {order_id} {status.get('order_status')!r}",
+ json.dumps({k: status.get(k) for k in
+ ("order_status", "total_amount")}))
+ charged = _order_amount(status)
+ c.ep.note(f"the backend charged {charged!r} for {order_id}")
+ c.expect(_minor_json(charged) == 400,
+ "taler-charged-the-whole-order",
+ f"two was taken in cash, so the wallet should have been asked "
+ f"for four; the backend order is for {charged!r}",
+ json.dumps({"amount": charged}))
+
+
+@scenario("demo")
+def checkout_cash_covers_it_all(c: Ctx) -> None:
+ """A sale settled entirely in cash still has to reach the backend."""
+ inst = c.demo()
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("3.00")
+ c.app.charge_to_checkout()
+ c.app.record_cash("3.00")
+ screen, _ = c.ep.observe()
+ c.require(_minor(c.app.checkout_amounts(screen).get("to pay")) == 0,
+ "the cash covered the order")
+ c.app.checkout_tile(r"^Complete payment$")
+ screen = c.dev.wait_for(r"Collect receipt|^Payment received$", timeout=90)
+ c.observe()
+ order_id = c.app.displayed_order_id(screen)
+ c.ep.note(f"receipt screen for {order_id}: {screen.texts()[:14]}")
+ c.require(bool(order_id), "the receipt screen names the order")
+ c.app.tap_button(r"^Collect receipt on this device$")
+ screen = c.dev.wait_for(MARK_SUCCESS, timeout=90)
+ c.observe()
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.ep.note(f"backend: {status.get('order_status')} / {status.get('total_amount')}")
+ c.expect(status.get("order_status") == "paid",
+ "cash-sale-not-recorded-at-the-backend",
+ f"the whole order was paid in cash and collected on the device, "
+ f"and the backend still calls {order_id} "
+ f"{status.get('order_status')!r}",
+ json.dumps({"order_status": status.get("order_status")}))
+
+
+@scenario("demo")
+def checkout_cash_left_behind_when_abandoned(c: Ctx) -> None:
+ """Cash taken, then the cashier backs out -- the money must not vanish."""
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("5.00")
+ c.app.charge_to_checkout()
+ c.app.record_cash("2.00")
+ c.observe()
+ screen = c.app.checkout_cancel(confirm=True)
+ c.ep.note(f"after cancelling with money taken: {screen.texts()[:16]}")
+ c.observe()
+ body = " ".join(screen.texts())
+ c.expect(not re.search(r"(?i)exception|null|error code", body),
+ "abandoned-checkout-shows-an-internal-error",
+ f"cancelling a checkout that holds cash showed: {body[:200]!r}",
+ body[:400])
+ # The terminal keeps abandoned checkouts so the cash can be reconciled,
+ # and the place it keeps them is the history list -- `mergeHistoryEntries`
+ # puts every checkout that is not Completed above the backend's own
+ # orders. If the two units are not there, money a cashier took is gone
+ # from the only screen that could account for it.
+ screen = c.app.goto("history")
+ time.sleep(4)
+ screen = c.app._stable_dump()
+ texts = screen.texts()
+ c.ep.note(f"history after abandoning: {texts[:16]}")
+ paid_line = [t for t in texts if "Paid:" in t]
+ c.expect(any(_minor(t.split("Paid:")[1]) == 200 for t in paid_line),
+ "abandoned-cash-is-not-in-the-history",
+ f"two units were taken in cash and the checkout abandoned; the "
+ f"history does not account for them: {texts[:16]}",
+ " | ".join(texts)[:400])
+ c.expect(bool(screen.find(r"^Mark as settled$|^Continue$")),
+ "abandoned-checkout-cannot-be-closed",
+ f"the abandoned checkout offers no way to settle or resume it: "
+ f"{texts[:16]}", " | ".join(texts)[:400])
+
+
+@scenario("demo")
+def checkout_cash_cannot_exceed_nothing(c: Ctx) -> None:
+ """The keypad's fraction shortcuts, and a zero that must stay unsubmittable."""
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("7.00")
+ c.app.charge_to_checkout()
+ c.app.checkout_tile(r"^Cash$")
+ screen = c.dev.wait_for(MARK_CHECKOUT_PAD, timeout=30)
+ c.observe()
+ shortcuts = {t for t in screen.texts() if re.match(r"^1/[234]$", t)}
+ c.ep.note(f"shortcuts offered: {sorted(shortcuts)}")
+ c.require(bool(shortcuts), f"the keypad offers fractions ({screen.texts()[:16]})")
+ submit = [t for t in screen.texts() if t.startswith("Record ")]
+ c.ep.note(f"submit label at zero: {submit}")
+ c.expect(bool(submit) and _minor(submit[0]) == 0,
+ "cash-keypad-starts-non-zero",
+ f"the cash keypad opened with {submit!r} rather than nothing typed",
+ " | ".join(screen.texts())[:400])
+ node = screen.find(r"^Record .* cash$")
+ target = screen.tap_target(node) if node else None
+ c.expect(target is not None and not target.enabled,
+ "cash-records-nothing",
+ "the cash keypad lets a payment of zero be recorded",
+ f"submit node: {target}")
+ # A half of seven is 3.50 and a third is 2.33 -- both exact enough to
+ # check, and both the sort of arithmetic that goes wrong quietly.
+ half = next((t for t in screen.texts()
+ if t.startswith("Half of remaining balance")), "")
+ c.ep.note(f"half says: {half!r}")
+ c.expect(_minor(half) == 350,
+ "cash-half-shortcut-wrong",
+ f"half of seven should be 3.50; the button says {half!r}",
+ half)
+
+
+@scenario("demo")
+def checkout_is_refused_by_an_old_backend(c: Ctx) -> None:
+ """A backend below protocol 42 has to say so rather than offer the feature."""
+ c.provision_mock("healthy")
+ screen = c.app.goto_payment_options()
+ c.observe()
+ body = " ".join(screen.texts())
+ version = c.app.about_rows().get("Merchant portal URL", "")
+ c.ep.note(f"mock backend version in About: {version!r}")
+ c.ep.note(f"payment options screen: {screen.texts()[:16]}")
+ mentions = bool(re.search(r"(?i)needs merchant backend protocol|several parts",
+ body))
+ rows = c.app.payment_option_rows(screen)
+ c.ep.note(f"options: {rows}; warning shown: {mentions}")
+ c.require("Cash" in rows, f"the options screen listed Cash ({rows})")
+ c.expect(mentions,
+ "old-backend-not-warned-about",
+ f"the mock backend is below protocol 42 and the payment-options "
+ f"screen says nothing about it: {screen.texts()[:16]}",
+ body[:400])
+
+
+@scenario("demo")
+def checkout_survives_process_death(c: Ctx) -> None:
+ """Cash already taken has to be there after the process is killed."""
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("9.00")
+ c.app.charge_to_checkout()
+ c.app.record_cash("4.00")
+ before = c.app.checkout_amounts()
+ c.ep.note(f"before the kill: {before}")
+ c.require(_minor(before.get("paid")) == 400, f"four is recorded ({before})")
+ c.app.process_death()
+ time.sleep(4)
+ screen, _ = c.ep.observe()
+ texts = " ".join(screen.texts())
+ c.ep.note(f"after the kill: {screen.texts()[:16]}")
+ c.expect(not re.search(r"(?i)has stopped|keeps stopping", texts),
+ "checkout-crashes-on-restart",
+ f"the terminal did not survive a restart mid-checkout: "
+ f"{screen.texts()[:12]}", texts[:400])
+ found = bool(re.search(r"(?i)unfinished|continue", texts)) or \
+ _minor(c.app.checkout_amounts(screen).get("paid")) == 400
+ c.expect(found,
+ "cash-lost-on-restart",
+ f"four units of cash were taken and after a restart the terminal "
+ f"shows no sign of them: {screen.texts()[:16]}",
+ texts[:400])
+
+
+@scenario("demo")
+def payment_options_summary_counts(c: Ctx) -> None:
+ """Turning an option on and off again has to be visible and reversible."""
+ c.provision_demo()
+ rows = c.app.set_payment_option("Cash", True)
+ c.require(rows.get("Cash") is True, "Cash went on")
+ c.observe()
+ screen = c.app.goto("settings")
+ counted = [t for t in screen.texts() if re.search(r"turned on", t)]
+ c.ep.note(f"settings summary with cash on: {counted}")
+ c.expect(any("2" in t for t in counted),
+ "payment-options-count-wrong",
+ f"Taler and Cash are on and Settings says {counted!r}",
+ " | ".join(screen.texts())[:400])
+ rows = c.app.set_payment_option("Cash", False)
+ c.expect(rows.get("Cash") is False,
+ "payment-option-will-not-turn-off",
+ f"Cash could not be turned off again: {rows}", json.dumps(rows))
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ screen = c.app.charge()
+ c.observe()
+ c.expect(bool(screen.find(MARK_PAYMENT)),
+ "checkout-shown-with-no-external-options",
+ f"with Cash off again, Charge should go straight to the payment "
+ f"screen and showed {screen.texts()[:12]}",
+ " | ".join(screen.texts())[:400])
+ c.app.cancel_payment()
+
+
+@scenario("demo")
+def payment_option_detail_without_a_key(c: Ctx) -> None:
+ """SumUp with no affiliate key must explain itself, not fail obscurely."""
+ c.provision_demo()
+ screen = c.app.goto_payment_options()
+ c.observe()
+ rows = c.app.payment_option_rows(screen)
+ c.require("SumUp" in rows, f"SumUp is listed ({rows})")
+ c.app.tap_button(r"^Open SumUp settings$")
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ body = " ".join(screen.texts())
+ c.ep.note(f"SumUp detail: {screen.texts()[:18]}")
+ c.expect(not re.search(r"(?i)exception|stacktrace|null\b|retrofit|okhttp",
+ body),
+ "payment-option-detail-leaks-an-internal-error",
+ f"the SumUp settings page showed an internal error: {body[:200]!r}",
+ body[:400])
+ c.expect(bool(screen.texts()),
+ "payment-option-detail-is-blank",
+ "the SumUp settings page has nothing on it at all",
+ body[:400])
+
+
+@scenario("demo", "slow")
+def taler_display_pairing_wizard(c: Ctx) -> None:
+ """The customer-display pairing wizard, as far as a device without one goes.
+
+ `TalerDevicesFragment` and `TalerBluetoothDevice` are a thousand lines
+ apiece and nothing has ever opened them. An emulator has no Taler display
+ to pair with, which is the point: what is being judged is that the wizard
+ asks for what it needs, says what it is doing, and ends in a sentence
+ rather than in a spinner or an empty list, when the scan finds nothing.
+ """
+ c.provision_demo()
+ screen = c.app.goto_payment_options()
+ c.observe()
+ c.require(bool(screen.find(r"^Open GNU Taler settings$")),
+ f"the Taler option has a settings page ({screen.texts()[:12]})")
+ c.app.tap_button(r"^Open GNU Taler settings$")
+ screen = c.dev.wait_for(r"Manage displays|Add device", timeout=45)
+ c.observe()
+ c.ep.note(f"devices screen: {screen.texts()[:14]}")
+ c.expect(bool(screen.find(r"^Add device$")),
+ "devices-screen-offers-nothing",
+ f"the displays page has no way to add one: {screen.texts()[:14]}",
+ " | ".join(screen.texts())[:400])
+ c.app.tap_button(r"^Add device$")
+ screen = c.dev.wait_for(r"Bluetooth display", timeout=30)
+ c.observe()
+ node = screen.find(r"^Bluetooth display$")
+ c.require(node is not None, f"the chooser offers Bluetooth ({screen.texts()})")
+ c.dev.tap_node(node, screen)
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ # The permission prompt is the system's, not the app's.
+ node = screen.find(r"^Allow device access$")
+ if node is not None:
+ c.ep.note("the app asked for nearby-device access before scanning")
+ # Tapped at the node: this is a Compose AlertDialog, and tap_button
+ # may press Back on the way, which dismisses it instead of answering.
+ c.dev.tap_node(node, screen)
+ time.sleep(3)
+ grant = c.app._stable_dump()
+ allow = grant.find(r"^Allow$")
+ if allow is not None:
+ c.dev.tap_node(allow, grant)
+ time.sleep(4)
+ steps = []
+ for _ in range(4):
+ screen = c.app._stable_dump()
+ steps.append(screen.texts()[:4])
+ node = screen.find(r"^Next$|^Find Taler display$")
+ if node is None:
+ break
+ c.dev.tap_node(node, screen)
+ time.sleep(4)
+ c.ep.note(f"wizard steps: {steps}")
+ c.require(len(steps) > 1, f"the wizard had more than one step ({steps})")
+ # Nothing to find, so what matters is that it stops looking and says so.
+ deadline = time.monotonic() + 60
+ screen = c.app._stable_dump()
+ while time.monotonic() < deadline and screen.find(r"Looking for"):
+ time.sleep(4)
+ screen = c.app._stable_dump()
+ c.observe()
+ texts = screen.texts()
+ c.ep.note(f"after the scan: {texts[:12]}")
+ c.expect(not any("Looking for" in t for t in texts),
+ "display-scan-never-stops",
+ f"the scan for a customer display is still running after a "
+ f"minute with nothing to find: {texts[:12]}",
+ " | ".join(texts)[:400])
+ c.expect(bool(screen.find(r"(?i)search again|no display|not found|cancel")),
+ "display-scan-ends-with-nothing-to-do",
+ f"the scan found no display and offers no way on or out: "
+ f"{texts[:12]}", " | ".join(texts)[:400])
+ body = " ".join(texts)
+ c.expect(not re.search(r"(?i)exception|null\b|securityexception", body),
+ "display-pairing-leaks-an-internal-error",
+ f"the pairing wizard showed an internal error: {body[:200]!r}",
+ body[:400])
+ cancel = screen.find(r"^Cancel$")
+ if cancel is not None:
+ c.dev.tap_node(cancel, screen)
+ time.sleep(2.5)
+ screen, _ = c.ep.observe()
+ c.expect(bool(screen.find(r"Manage displays|Add device|Customers pay")),
+ "display-wizard-cannot-be-left",
+ f"cancelling the pairing wizard did not return to the devices "
+ f"page: {screen.texts()[:12]}", " | ".join(screen.texts())[:400])
+
+
+@scenario("demo", "phone")
+def login_form_fits_a_phone(c: Ctx) -> None:
+ """The login form has to stay usable once the keyboard is up."""
+ c.app.fresh_start()
+ screen = c.app.wait_for_config_screen()
+ c.observe()
+ fields = screen.editable()
+ c.require(len(fields) >= 3,
+ f"the form starts with its three fields ({screen.texts()[:12]})")
+ c.dev.tap_node(fields[0], screen)
+ time.sleep(2.5)
+ screen, _ = c.ep.observe()
+ c.require(c.dev.keyboard_shown(), "tapping a field raised the keyboard")
+ after = screen.editable()
+ scrollable = [n for n in screen.nodes if n.scrollable]
+ c.ep.note(f"with the keyboard up: {len(after)} field(s), "
+ f"{len(scrollable)} scrollable, texts {screen.texts()[:12]}")
+ c.expect(bool(after),
+ "login-form-collapses-under-the-keyboard",
+ f"tapping the first field left the form with no fields at all; "
+ f"what is on screen is {screen.texts()[:12]}",
+ " | ".join(screen.texts())[:400])
+ c.expect(bool(after) or bool(scrollable),
+ "login-form-cannot-be-scrolled-back",
+ "the form lost its fields to the keyboard and nothing on the "
+ "screen scrolls, so there is no way back to them",
+ " | ".join(screen.texts())[:400])
+ c.dev.hide_keyboard()
+ time.sleep(1.5)
+ screen, _ = c.ep.observe()
+ c.expect(bool(c.app.control_reachable(r"^Connect$", screen))
+ or bool(screen.find(r"^Connect$")),
+ "login-form-loses-connect",
+ f"Connect is not reachable with the keyboard down either: "
+ f"{screen.texts()[:12]}", " | ".join(screen.texts())[:400])
+
+
+@scenario("mock")
+def checkout_on_a_mock_backend(c: Ctx) -> None:
+ """The whole cash checkout against a backend of our own.
+
+ Until `mockd.py` grew `/collect` and `/refund-external` this could only
+ be driven against the shared demo instance, which meant it could not be
+ parallelised and no fault could be injected into it. This is the proof
+ that it can be, and the oracle is the mock's own memory: what the
+ terminal said happened has to match what the backend was asked to do.
+ """
+ c.provision_mock("healthy")
+ rows = c.app.set_payment_option("Cash", True)
+ c.require(rows.get("Cash") is True,
+ f"Cash can be turned on against the mock ({rows})")
+ c.app.goto("amount")
+ c.app.enter_amount("3.00")
+ screen = c.app.charge_to_checkout()
+ c.observe()
+ c.ep.note(f"checkout on the mock: {c.app.checkout_amounts(screen)}")
+ c.app.record_cash("3.00")
+ c.app.checkout_tile(r"^Complete payment$")
+ c.dev.wait_for(r"Collect receipt|^Payment received$", timeout=90)
+ screen, _ = c.ep.observe()
+ order_id = c.app.displayed_order_id(screen)
+ c.require(bool(order_id), f"the receipt names the order ({screen.texts()[:10]})")
+ c.app.tap_button(r"^Collect receipt on this device$")
+ c.dev.wait_for(MARK_SUCCESS, timeout=90)
+ c.observe()
+ assert c.mock is not None
+ order = c.mock.state.orders.get(order_id)
+ c.ep.note(f"the mock's order {order_id}: "
+ f"paid={getattr(order, 'paid', None)} "
+ f"collected={getattr(order, 'collected', None)}")
+ c.expect(order is not None and order.collected,
+ "cash-sale-never-collected",
+ f"the terminal said the sale was complete and the backend was "
+ f"never asked to settle {order_id}",
+ f"order={order!r}")
+
+
+@scenario("mock")
+def checkout_collect_refused(c: Ctx) -> None:
+ """The backend refuses to settle a sale the cashier has already taken cash for.
+
+ This is the worst moment for a backend to say no: the money is in the
+ till and the customer is leaving. What matters is that the terminal says
+ so rather than reporting a completed sale, and that it does not lose the
+ cash it has recorded.
+ """
+ c.provision_mock("collect-fails")
+ rows = c.app.set_payment_option("Cash", True)
+ c.require(rows.get("Cash") is True, f"Cash is on ({rows})")
+ c.app.goto("amount")
+ c.app.enter_amount("2.00")
+ c.app.charge_to_checkout()
+ c.app.record_cash("2.00")
+ c.app.checkout_tile(r"^Complete payment$")
+ c.dev.wait_for(r"Collect receipt|^Payment received$", timeout=90)
+ c.app.tap_button(r"^Collect receipt on this device$")
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ body = (f"{dialog.title} {dialog.message}" if dialog
+ else " ".join(screen.texts()))
+ c.ep.note(f"after a refused collect: {body[:220]}")
+ c.expect(not bool(screen.find(MARK_SUCCESS)),
+ "refused-collect-reported-as-paid",
+ f"the backend refused to settle the order and the terminal says "
+ f"the payment went through: {screen.texts()[:12]}", body[:400])
+ _judge_message(c, body, "a backend that refused to settle a cash sale")
+ assert c.mock is not None
+ order_ids = list(c.mock.state.orders)
+ c.ep.note(f"the mock holds {order_ids}")
+ c.expect(not any(o.collected for o in c.mock.state.orders.values()),
+ "refused-collect-recorded-anyway",
+ "the backend refused the collect and the mock has the order "
+ "marked settled anyway",
+ json.dumps({k: v.collected
+ for k, v in c.mock.state.orders.items()}))
+
+
+@scenario("demo", "slow")
+def checkout_cash_refund_is_recorded(c: Ctx) -> None:
+ """Hand cash back on a cash sale, and see it reach the backend.
+
+ The whole external-refund path is new and has never been driven: a
+ `RefundAvailability` chooser that offers the methods the order was
+ actually paid with, a confirmation that the money has physically changed
+ hands, and `POST /private/orders/<id>/refund-external`. None of it is a
+ Taler refund, so none of it shows up in `refund_amount` -- the backend
+ keeps it in `refunds_external`, which is what this checks.
+ """
+ inst = c.demo()
+ _enable_cash(c)
+ c.app.goto("amount")
+ c.app.enter_amount("4.00")
+ c.app.charge_to_checkout()
+ c.app.record_cash("4.00")
+ c.app.checkout_tile(r"^Complete payment$")
+ c.dev.wait_for(r"Collect receipt|^Payment received$", timeout=90)
+ screen, _ = c.ep.observe()
+ order_id = c.app.displayed_order_id(screen)
+ c.require(bool(order_id), f"the receipt names the order ({screen.texts()[:10]})")
+ c.app.tap_button(r"^Collect receipt on this device$")
+ c.dev.wait_for(MARK_SUCCESS, timeout=90)
+ c.app.continue_from_success()
+ time.sleep(2)
+
+ c.app.goto("history")
+ time.sleep(4)
+ screen = c.app._stable_dump()
+ rows = [n for n in screen.labelled() if n.label.strip() == "Order details"]
+ c.require(bool(rows), f"the history offers an order to open ({screen.texts()[:12]})")
+ c.dev.tap_node(min(rows, key=lambda n: n.bounds[1]), screen)
+ time.sleep(4)
+ screen, _ = c.ep.observe()
+ c.require(bool(screen.find(r"^Refund$")),
+ f"the cash-paid order offers a refund ({screen.texts()[:14]})")
+ c.app.tap_button(r"^Refund$")
+ screen = c.dev.wait_for(r"Refund method", timeout=45)
+ c.observe()
+ texts = " ".join(screen.texts())
+ c.ep.note(f"refund chooser: {screen.texts()[:14]}")
+ c.expect(bool(screen.find(r"^Cash$")),
+ "cash-refund-not-offered",
+ f"the order was paid in cash and the refund screen does not "
+ f"offer it back: {screen.texts()[:14]}", texts[:400])
+ c.expect(bool(re.search(r"(?i)hand the cash back", texts)),
+ "cash-refund-unexplained",
+ f"the cash refund offers no instruction about the money itself: "
+ f"{screen.texts()[:14]}", texts[:400])
+
+ c.app.fill_field(r"^Amount$", "1.50")
+ time.sleep(1)
+ if c.dev.keyboard_shown():
+ c.dev.hide_keyboard()
+ time.sleep(1)
+ c.app.tap_button(r"^Record refund$")
+ time.sleep(3)
+ screen, _ = c.ep.observe()
+ confirm = screen.find(r"Money returned")
+ c.require(confirm is not None,
+ f"the terminal asked for confirmation ({screen.texts()[:12]})")
+ c.dev.tap_node(confirm, screen)
+ time.sleep(5)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ c.ep.note(f"after recording: {dialog or screen.texts()[:12]}")
+ said_recorded = bool(dialog and re.search(r"(?i)recorded", str(dialog)))
+ c.expect(said_recorded,
+ "cash-refund-not-acknowledged",
+ f"the terminal did not say the refund was recorded: "
+ f"{dialog or screen.texts()[:12]}",
+ " | ".join(screen.texts())[:400])
+
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ external = status.get("refunds_external") or []
+ c.ep.note(f"backend refunds_external: {json.dumps(external)[:300]}")
+ c.expect(any(_minor_json(r.get("amount")) == 150 for r in external),
+ "cash-refund-never-reached-the-backend",
+ f"the terminal said the refund was recorded on the order and the "
+ f"backend has {external!r} against {order_id}",
+ json.dumps(external)[:400])
+ c.expect(_minor_json(status.get("refund_amount")) == 0,
+ "cash-refund-counted-as-a-taler-refund",
+ f"handing cash back should not become a Taler refund; the "
+ f"backend reports refund_amount={status.get('refund_amount')!r}",
+ json.dumps({"refund_amount": status.get("refund_amount")}))
+
+
+def _minor(shown: Optional[str]) -> Optional[int]:
+ """A displayed amount as whole minor units, or None if there is none.
+
+ The terminal renders amounts with the currency's symbol and the locale's
+ grouping -- "\u30af7.00", "1,234.56" -- and a scenario comparing against the
+ backend cares about the number, not the dressing.
+ """
+ if not shown:
+ return None
+ m = Pos.AMOUNT_SHOWN.search(shown)
+ if m:
+ text = m.group(0)
+ else:
+ # A whole number has no separator, and the backend writes amounts that
+ # way: "KUDOS:0", "KUDOS:4". Reading those as "no amount at all"
+ # turned a correct zero into a finding.
+ whole = re.search(r"\d+", shown)
+ if whole is None:
+ return None
+ text = whole.group(0)
+ for sep in ("\u00a0", "\u202f", " "):
+ text = text.replace(sep, "")
+ if text.count(",") and text.count("."):
+ text = text.replace(",", "")
+ elif text.count(",") > 1:
+ text = text.replace(",", "")
+ else:
+ text = text.replace(",", ".")
+ whole, _, frac = text.partition(".")
+ whole = whole.replace(".", "")
+ return int(whole or 0) * 100 + int((frac + "00")[:2] or 0)
+
+
+def _order_amount(status: dict) -> Optional[str]:
+ """What the backend says an order is for, paid or not.
+
+ `total_amount` is only in an *unpaid* order's status; once it is paid the
+ figure is in `contract_terms.amount`, and reading the first field alone
+ reported the correct four-unit order as an order for nothing.
+ """
+ direct = status.get("total_amount")
+ if direct:
+ return direct
+ return (status.get("contract_terms") or {}).get("amount")
+
+
+def _minor_json(amount: Optional[str]) -> Optional[int]:
+ """A backend amount ("KUDOS:4.5") as whole minor units."""
+ if not amount or ":" not in amount:
+ return None
+ return _minor(amount.split(":", 1)[1])
+
+
+# =========================================================================
+# fault injection: a real backend made to go wrong
+# =========================================================================
+#
+# The mock answers like a merchant who is set up badly. Twister answers like
+# the demo backend having a bad day: everything is the real exchange until one
+# field, one status code or one byte count is not. That is where the
+# terminal's error branches live -- `Response.getFailureString` picks one of
+# five arms by exception type, `fallbackStatusMessage` one of seven by status
+# code, and nothing a correctly configured backend says reaches any of them.
+#
+# Two rules learned from writing these. A mutation fires once, so a *single*
+# backend call can be targeted exactly by arming it immediately before the tap
+# that makes it; anything the terminal polls needs `sustain`, which re-arms in
+# a loop. And a failed login leaves the form on screen, so `expect_success`
+# has to be False or `provision_by_form` fails the scenario for the app's
+# correct behaviour.
+
+
+def _order_to_delete(c: Ctx) -> str:
+ """An unpaid order sitting in the history, ready to be deleted.
+
+ Created through the merchant API rather than the terminal, so that the
+ twister mutation armed later lands on the delete and not on something the
+ terminal was doing on its way there.
+ """
+ inst = c.demo()
+ order = inst.merchant.create_order(
+ inst.token.value, f"{inst.currency}:1",
+ "pos-simulator to delete under fault")
+ order_id = order["order_id"]
+ c.ep.note(f"created {order_id} to delete")
+ c.app.goto("history")
+ c.app.refresh_history()
+ time.sleep(2)
+ screen = c.app._stable_dump()
+ c.require(bool(screen.find(r"^Delete order$")),
+ f"the history offers a delete action ({screen.texts()[:14]})")
+ return order_id
+
+
+@scenario("fault", "demo")
+def fault_delete_refused_as_claimed(c: Ctx) -> None:
+ """A delete the backend refuses with 409, which is a real claim.
+
+ Only possible since taler-twister learned to proxy DELETE: before that
+ the request never reached a backend at all, so no scenario could see what
+ the terminal does with the answer. 409 is the one status where the
+ force-delete prompt is the right response, so this is the arm that should
+ stay green.
+ """
+ c.provision_twister()
+ _order_to_delete(c)
+ assert c.tw is not None
+ c.tw.status(409)
+ c.app.tap_button(r"^Delete order$")
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ body = (f"{dialog.title} {dialog.message}" if dialog
+ else " ".join(screen.texts()))
+ c.ep.note(f"after a 409 on the delete: {body[:220]}")
+ c.expect(dialog is not None and re.search(r"(?i)force", str(dialog)) is not None,
+ "claimed-delete-offers-no-force",
+ f"the backend refused the delete with 409 and the terminal did "
+ f"not offer to force it: {body[:200]}", body[:400])
+
+
+@scenario("fault", "demo")
+def fault_delete_server_error(c: Ctx) -> None:
+ """A delete the backend fails with 502, which is *not* a claim.
+
+ The terminal raises its force-delete prompt on any failed delete and
+ throws the reason away, so a plain server error is reported to the
+ cashier as "This order has been claimed by a wallet" -- filed as
+ bugs.gnunet.org 11977 with a patch. This is the regression test for it,
+ and it could not be written until twister could carry a DELETE.
+ """
+ c.provision_twister()
+ _order_to_delete(c)
+ assert c.tw is not None
+ c.tw.status(502)
+ c.app.tap_button(r"^Delete order$")
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ body = (f"{dialog.title} {dialog.message}" if dialog
+ else " ".join(screen.texts()))
+ c.ep.note(f"after a 502 on the delete: {body[:220]}")
+ c.expect(re.search(r"(?i)claimed by a wallet", body) is None,
+ "failed-delete-blamed-on-a-wallet",
+ f"the delete failed with a server error and the terminal told "
+ f"the cashier a wallet had claimed the order: {body[:200]}",
+ body[:400])
+ _judge_message(c, body, "a delete the backend answered 502")
+
+
+def _fault_dialog_text(c: Ctx) -> tuple[str, Optional[Dialog]]:
+ """Whatever the terminal said about the fault, dialog or screen."""
+ screen, _ = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ body = (f"{dialog.title} {dialog.message}" if dialog
+ else " ".join(screen.texts()))
+ return body, dialog
+
+
+def _clear_dialog(c: Ctx) -> None:
+ """Close whatever modal is up, by its button and not by its geometry.
+
+ `Pos.dismiss_dialog` goes through `read_dialog`, which infers the dialog
+ from where things are on screen and returns None when the inference fails.
+ That is the right conservative answer for *reading* a dialog and the wrong
+ one for getting rid of it: a sweep that arms seven faults in a row leaves
+ the first dialog up and then times out looking for a button behind it.
+ Here it is enough that something dismissible is on screen.
+ """
+ for _ in range(3):
+ screen = c.app._stable_dump()
+ node = screen.find(r"^(OK|Ok|ok|Dismiss|Close)$")
+ if node is None:
+ return
+ c.dev.tap_node(node, screen)
+ time.sleep(1.5)
+
+
+def _tap_through_dialogs(c: Ctx, pattern: str, tries: int = 4) -> bool:
+ """Press a control that a dialog keeps appearing in front of.
+
+ A screen that fetches on its own puts its error dialog back up between the
+ clearing and the tap, so one `_clear_dialog` before the tap is not enough:
+ the fault scenarios arm, tap, read, arm again, and the second arming raced
+ the dialog the first one had raised.
+ """
+ for _ in range(tries):
+ _clear_dialog(c)
+ try:
+ c.app.tap_button(pattern, timeout=10)
+ return True
+ except (PosError, TimeoutError):
+ time.sleep(2)
+ return False
+
+
+def _judge_message(c: Ctx, body: str, what: str) -> None:
+ """A fault report has to name the failure and not leak the stack.
+
+ Both halves have been seen to fail for real: round one's finding 4 is a
+ dialog that shows the backend's own 401 hint instead of the terminal's
+ session-expired string, and a dialog quoting `io.ktor...` is the shape of
+ "internal error" this harness exists to find.
+ """
+ c.expect(not re.search(r"(?i)exception|io\.ktor|kotlinx\.|java\.lang|"
+ r"\bat [a-z]+\.[a-z]+\.", body),
+ "exception-in-dialog",
+ f"{what} produced a message quoting an exception or a stack "
+ f"frame: {body[:200]!r}",
+ body[:600])
+ # A message need not say "exception" to be one. kotlinx.serialization's
+ # own wording -- "Field 'orders' is required for type with serial name
+ # 'net.taler.merchantlib.OrderHistory'" -- names a Kotlin class and a
+ # serial name and is shown verbatim, which tells a cashier nothing and
+ # tells everyone else what the app is built out of.
+ c.expect(not re.search(r"serial name|\bnet\.taler\.[a-z]+\.[A-Za-z]|"
+ r"\bIllegal input\b", body),
+ "internal-type-name-in-dialog",
+ f"{what} produced a message naming an internal type: "
+ f"{body[:220]!r}",
+ body[:600])
+ c.expect(bool(body.strip()),
+ "silent-failure",
+ f"{what} produced no message at all",
+ body[:600])
+
+
+@scenario("fault", "demo")
+def fault_login_server_error(c: Ctx) -> None:
+ """Every backend call during login answers 500."""
+ c.provision_twister(expect_success=False,
+ arm_during_login=(("status", 500),))
+ body, dialog = _fault_dialog_text(c)
+ c.ep.note(f"login against a 500 backend: {body[:300]}")
+ c.require(bool(body.strip()), "the terminal said something about the 500")
+ c.expect(bool(re.search(r"(?i)server error|500|could not", body)),
+ "server-error-not-named",
+ f"a backend answering 500 to everything produced: {body[:200]!r}",
+ body[:600])
+ _judge_message(c, body, "a backend answering 500")
+ _clear_dialog(c)
+ screen, _ = c.ep.observe()
+ c.expect(bool(screen.find(AT_LOGIN)),
+ "stuck-after-server-error",
+ "a 500 during login left the terminal somewhere other than the "
+ "login form",
+ " | ".join(screen.texts())[:500])
+
+
+@scenario("fault", "demo")
+def fault_login_malformed_reply(c: Ctx) -> None:
+ """The backend's replies are truncated mid-JSON during login.
+
+ Not a status code and not a connection failure: a 200 whose body stops.
+ Ktor's deserializer throws, which is the `else` arm of
+ `getFailureString` -- the one that shows `exception.message`, and so the
+ one most likely to put a serialization error in front of a cashier.
+ """
+ c.provision_twister(expect_success=False,
+ arm_during_login=(("malform",),))
+ body, _ = _fault_dialog_text(c)
+ c.ep.note(f"login against truncated JSON: {body[:300]}")
+ c.require(bool(body.strip()), "the terminal reported the truncated reply")
+ _judge_message(c, body, "a truncated JSON reply")
+
+
+@scenario("fault", "demo")
+def fault_login_connection_cut(c: Ctx) -> None:
+ """The connection closes in the middle of the response body.
+
+ This is the only way to reach the `IOException` arm of
+ `Response.getFailureString`: the request succeeded, the status was 200, the
+ headers arrived, and then the socket went away. No status code produces
+ it and neither does an unreachable host, which fails earlier and
+ differently.
+ """
+ tw = c.provision_twister()
+ # On the history screen *before* the fault goes in: the dialog it raises
+ # covers the screen's own markers, so a `goto` inside the block waits out
+ # its timeout looking for a button behind a modal.
+ c.app.goto("history")
+ with c.front.transport("cut"):
+ # The history fragment fetches its first page as it opens, so the
+ # dialog is usually already up by the time the block starts and there
+ # is no Refresh button to find behind it. Either way is the fault
+ # firing; what must not happen is waiting out a timeout for a button
+ # the dialog is covering.
+ deadline = time.monotonic() + 40
+ body = ""
+ while time.monotonic() < deadline:
+ body, dialog = _fault_dialog_text(c)
+ if dialog is not None or re.search(r"(?i)error", body):
+ break
+ try:
+ c.app.tap_button(r"Refresh history", timeout=8)
+ except (PosError, TimeoutError):
+ pass
+ time.sleep(3)
+ c.ep.note(f"a body that stopped halfway: {body[:300]}")
+ c.require(bool(body.strip()), "the terminal reported the cut connection")
+ _judge_message(c, body, "a response body that stopped halfway")
+ c.expect(bool(re.search(r"(?i)network|connection|internet|merchant url",
+ body)),
+ "transport-error-shows-the-library-wording",
+ f"a response body that stopped halfway was reported as "
+ f"{body[:200]!r}. merchant-lib has a sentence for this -- "
+ f"\"Network error: check your internet connection and merchant "
+ f"URL.\" -- but `Response.getFailureString` only reaches it for "
+ f"SocketTimeout, Connect and UnknownHost; every other IOException "
+ f"falls through to `exception.message`, which is whatever the HTTP "
+ f"engine happened to call it",
+ body[:600])
+ _clear_dialog(c)
+ with c.front.transport("none"):
+ c.app.tap_button(r"Refresh history")
+ time.sleep(8)
+ screen, _ = c.ep.observe()
+ c.expect(bool(c.app.history_rows(screen)),
+ "history-does-not-recover",
+ "after one cut connection the history list stayed empty even "
+ "though the backend answers correctly again",
+ " | ".join(screen.texts())[:500])
+
+
+@scenario("fault", "demo")
+def fault_login_wrong_content_type(c: Ctx) -> None:
+ """The backend answers JSON labelled as plain text."""
+ c.provision_twister(
+ expect_success=False,
+ arm_during_login=(("header", "Content-Type", "text/plain"),))
+ body, _ = _fault_dialog_text(c)
+ c.ep.note(f"login against text/plain JSON: {body[:300]}")
+ _judge_message(c, body, "JSON labelled text/plain")
+
+
+@scenario("fault", "demo")
+def fault_status_code_sweep(c: Ctx) -> None:
+ """Every status code the terminal has its own sentence for.
+
+ `Response.fallbackStatusMessage` has seven arms and the terminal's own
+ dialogs sit on top of them. One history refresh makes exactly one backend
+ call, so each code can be aimed at precisely instead of hoping a login
+ hits the right request.
+ """
+ c.provision_twister()
+ c.app.goto("history")
+ seen: dict[int, str] = {}
+ for code in (400, 401, 403, 404, 408, 503, 418):
+ assert c.tw is not None
+ c.tw.status(code)
+ c.app.tap_button(r"Refresh history")
+ time.sleep(5)
+ body, dialog = _fault_dialog_text(c)
+ seen[code] = body[:160]
+ c.ep.note(f"{code}: {body[:160]}")
+ _judge_message(c, body, f"a {code} from the backend")
+ _clear_dialog(c)
+ c.require(len(seen) == 7, "all seven status codes were served and read")
+ c.expect(len({v for v in seen.values() if v}) > 1,
+ "status-codes-indistinguishable",
+ "every status code from 400 to 418 produced the same message, so "
+ "a cashier cannot tell a bad request from a server fault: "
+ f"{seen}",
+ json.dumps(seen)[:900])
+ # 401 is the session-expired case, and round one found it showing the
+ # backend's hint rather than the terminal's own string. Checked here
+ # again, on a real backend, because this is the cheapest route to it.
+ c.expect(not re.search(r"(?i)^error \d+ \(401\)", seen.get(401, "").strip()),
+ "unauthorized-shows-protocol-error",
+ f"a 401 showed the protocol error verbatim: {seen.get(401)!r}",
+ seen.get(401, ""))
+
+
+@scenario("fault", "demo")
+def fault_order_creation_server_error(c: Ctx) -> None:
+ """The order the cashier just rang up comes back 502."""
+ c.provision_twister()
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ assert c.tw is not None
+ c.tw.status(502)
+ c.ep.perform(Action("tap_label", "Create order (charge amount)"))
+ time.sleep(8)
+ body, _ = _fault_dialog_text(c)
+ c.ep.note(f"order creation against a 502: {body[:300]}")
+ c.require(bool(body.strip()), "the terminal reported the failed order")
+ c.expect(bool(re.search(r"(?i)could not create|order", body)),
+ "order-failure-unnamed",
+ f"an order refused with 502 produced: {body[:200]!r}",
+ body[:600])
+ _judge_message(c, body, "an order refused with 502")
+
+
+@scenario("fault", "demo")
+def fault_order_creation_malformed(c: Ctx) -> None:
+ """The order is created and the reply says so unintelligibly.
+
+ The dangerous half of this is not the dialog: the backend really did
+ create the order, so a terminal that reports a failure and walks away has
+ left an order behind that nobody will collect. That is what the history
+ comparison at the end is for.
+ """
+ inst = c.demo()
+ before = {o.get("order_id") for o in inst.merchant.history(inst.token.value, limit=-8)}
+ c.provision_twister()
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ assert c.tw is not None
+ c.tw.malform()
+ c.ep.perform(Action("tap_label", "Create order (charge amount)"))
+ time.sleep(10)
+ body, _ = _fault_dialog_text(c)
+ c.ep.note(f"order creation with a truncated reply: {body[:300]}")
+ _judge_message(c, body, "an order whose reply was truncated")
+ after = inst.merchant.history(inst.token.value, limit=-8)
+ # Narrowed to orders that look like the one this scenario just asked for.
+ # The instance is shared, and a diff of the whole history blamed the
+ # terminal for an order another worker had created *and paid* 67 seconds
+ # earlier -- which is how this scenario reported two orphans from a single
+ # POST.
+ fresh = [o for o in after
+ if o.get("order_id") not in before
+ and o.get("summary") == "Regular order"
+ and str(o.get("amount")) == f"{inst.currency}:1"]
+ c.ep.note(f"orders the backend gained: {[o.get('order_id') for o in fresh]}")
+ # A history entry carries `paid`; `order_status` belongs to
+ # GET /private/orders/{id} and is simply absent here, so asking for it
+ # made `!= "paid"` true of every order, paid ones included.
+ unpaid = [o for o in fresh if not o.get("paid")]
+ if not EXCLUSIVE_DEMO:
+ c.ep.note("another worker shares this instance, so the orders it "
+ "gained are not this scenario's to count")
+ return
+ c.expect(len(unpaid) <= 1,
+ "orphaned-orders-after-unreadable-reply",
+ f"an order reply the terminal could not read left "
+ f"{len(unpaid)} unpaid orders behind: "
+ f"{[o.get('order_id') for o in unpaid]}",
+ json.dumps(fresh)[:800])
+
+
+# The insecure-pay-URI dialog stacks its three buttons in a Column rather than
+# laying them out in a row, and `Pos.read_dialog` infers a dialog from exactly
+# that row -- so it returns None for this one even with the dialog plainly on
+# screen. It is recognised by what it says instead.
+INSECURE_URI_DIALOG = re.compile(
+ r"Payment link problem|Try fixed link|Continue as is")
+
+
+def _insecure_dialog_on(screen) -> bool:
+ return bool(screen.find(INSECURE_URI_DIALOG.pattern))
+
+
+def _insecure_uri_dialog(c: Ctx, button: str) -> tuple[Optional[str], str]:
+ """Charge an amount, make the pay URI insecure, and press `button`.
+
+ The terminal polls the order's status about once a second, and each poll
+ overwrites the previous one -- so a single mutation raises the dialog for
+ one poll and the next poll dismisses it again. `sustain` keeps the URI
+ insecure for as long as it takes to read the dialog and press something.
+ """
+ tw = c.provision_twister()
+ c.app.goto("amount")
+ c.app.enter_amount("1.00")
+ # Arm the mutation *before* the order exists, so the terminal's first
+ # status poll already sees the insecure URI: `Pos.charge` would wait for a
+ # payment screen that the dialog is covering.
+ insecure = "taler+http://pay/backend.demo.taler.net/instances/sandbox/x/"
+ with tw.sustain(("modify", "taler_pay_uri", insecure)):
+ c.ep.perform(Action("tap_label", "Create order (charge amount)"))
+ deadline = time.monotonic() + 60
+ dialog = None
+ screen = c.app._stable_dump()
+ while time.monotonic() < deadline:
+ screen = c.app._stable_dump()
+ if _insecure_dialog_on(screen):
+ dialog = c.app.read_dialog(screen)
+ break
+ time.sleep(1.5)
+ c.require(_insecure_dialog_on(screen),
+ "the terminal objected to a taler+http:// pay URI "
+ f"(screen: {screen.texts()[:10]})")
+ c.ep.note(f"insecure-URI dialog: {dialog}")
+ c.ep.observe()
+ c.ep.perform(Action("tap_label", button))
+ time.sleep(4)
+ screen, _ = c.ep.observe()
+ # Read the URI here, while the backend is still being made to hand out
+ # an insecure one. Outside the block the next status poll gets the
+ # real `taler://` URI and the terminal replaces what it is showing with
+ # it -- which is correct, and which made "continue as is" look like it
+ # had been ignored.
+ uri = c.app.displayed_pay_uri()
+ c.ep.note(f"pay URI while the backend is still wrong: {uri}")
+ return uri, " | ".join(screen.texts())
+
+
+@scenario("fault", "demo")
+def fault_insecure_pay_uri_upgrade(c: Ctx) -> None:
+ """A taler+http:// pay URI, upgraded to https on the cashier's say-so."""
+ uri, after = _insecure_uri_dialog(c, "Try fixed link")
+ c.ep.note(f"after upgrading: {after[:300]}")
+ c.expect(bool(uri and uri.startswith("taler://")),
+ "https-upgrade-did-not-upgrade",
+ f"accepting the HTTPS upgrade left the terminal showing {uri!r}",
+ after[:600])
+
+
+@scenario("fault", "demo")
+def fault_insecure_pay_uri_continue(c: Ctx) -> None:
+ """A taler+http:// pay URI the cashier decides to use anyway."""
+ uri, after = _insecure_uri_dialog(c, "Continue as is")
+ c.ep.note(f"after continuing: {after[:300]}")
+ c.expect(bool(uri and uri.startswith("taler+http://")),
+ "insecure-uri-not-honoured",
+ f"choosing to continue with the insecure URI showed {uri!r} "
+ f"instead of the insecure one the cashier accepted",
+ after[:600])
+
+
+@scenario("fault", "demo")
+def fault_insecure_pay_uri_cancel(c: Ctx) -> None:
+ """A taler+http:// pay URI the cashier refuses, cancelling the order."""
+ _, after = _insecure_uri_dialog(c, "Cancel order")
+ # The order id, so that "claimed by a wallet" can be checked against what
+ # the backend actually thinks. Round four could not answer that because
+ # the id was never written down.
+ # The payment screen's own order id is unreadable here -- the force-delete
+ # dialog is on top of it -- so fall back to the id the terminal logs when
+ # its delete fails.
+ order_id = c.app.displayed_order_id()
+ if not order_id:
+ hit = re.findall(r"Delete order (\S+) (?:failed|succeeded)",
+ c.dev.logcat(lines=4000))
+ order_id = hit[-1] if hit else None
+ c.ep.note(f"order on screen: {order_id}")
+ # Asked of the backend directly, not through twister: the dialog claims a
+ # wallet has claimed the order, so what the backend thinks of it is the
+ # only thing that can settle that.
+ if order_id:
+ try:
+ inst = c.demo()
+ status = inst.merchant.order_status(inst.token.value, order_id)
+ c.ep.note(f"backend on {order_id}: order_status="
+ f"{status.get('order_status')!r}")
+ except Exception as e: # a 404 is itself an answer
+ c.ep.note(f"backend on {order_id}: {e}")
+ c.ep.note(f"after cancelling: {after[:300]}")
+ screen, _ = c.ep.observe()
+ c.expect(not bool(screen.find(MARK_PAYMENT)) or
+ bool(screen.find(MARK_AMOUNT)) or bool(screen.find(MARK_ORDER)),
+ "cancel-left-the-payment-screen-up",
+ "cancelling the order over an insecure pay URI left the terminal "
+ "on the payment screen",
+ after[:600])
+
+
+@scenario("fault", "demo")
+def fault_history_unreadable(c: Ctx) -> None:
+ """The order history comes back as something that is not an order history.
+
+ Three shapes in one scenario, because each is one refresh: a truncated
+ body, a deleted field, and a flipped character inside a string. The last
+ is the subtle one -- the JSON still parses, so nothing throws, and whatever
+ the terminal draws it draws from a value that is wrong.
+ """
+ c.provision_twister()
+ c.app.goto("history")
+ c.app.tap_button(r"Refresh history")
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ rows = c.app.history_rows(screen)
+ c.require(bool(rows), f"the history list has rows to corrupt ({len(rows)})")
+ assert c.tw is not None
+ for label, arm in (("truncated", ("malform",)),
+ ("no orders field", ("delete", "orders")),
+ ("flipped summary", ("flip", "orders.0.summary"))):
+ # Each round leaves a dialog over the Refresh button, and the screen
+ # puts it back up on its own, so the tap has to keep clearing it.
+ _clear_dialog(c)
+ getattr(c.tw, arm[0])(*arm[1:])
+ c.require(_tap_through_dialogs(c, r"Refresh history"),
+ f"the history could be refreshed for the {label} round")
+ time.sleep(6)
+ body, dialog = _fault_dialog_text(c)
+ c.ep.note(f"history {label}: {(str(dialog) or body)[:240]}")
+ _judge_message(c, body if dialog else "ok", f"a {label} history")
+ _clear_dialog(c)
+ screen, _ = c.ep.observe()
+ c.expect(bool(screen.find(MARK_HISTORY)),
+ "history-screen-lost",
+ f"a {label} history reply took the terminal off the history "
+ f"screen: {screen.texts()[:10]}",
+ " | ".join(screen.texts())[:500])
+ _tap_through_dialogs(c, r"Refresh history")
+ time.sleep(6)
+ screen, _ = c.ep.observe()
+ c.expect(bool(c.app.history_rows(screen)),
+ "history-does-not-recover",
+ "after three broken replies the history list stayed empty even "
+ "though the backend answers correctly again",
+ " | ".join(screen.texts())[:500])
+
+
+@scenario("fault", "demo", "slow")
+def fault_chaos_walk(c: Ctx) -> None:
+ """The terminal driven normally while one request in eight fails.
+
+ Deliberate scenarios arm one fault and look at one screen. What they
+ cannot produce is a fault arriving at a moment nobody chose -- a config
+ refresh failing while the order screen is already up, a status poll failing
+ between two successful ones. Chaos mode is twister answering 503 at
+ random, and what is being checked is only that nothing crashes and nothing
+ ends up on a dead screen.
+ """
+ c.provision_twister(chaos=12, expect_success=False)
+ c.ep.observe()
+ screen = c.app._stable_dump()
+ # Logging in may itself have failed; retry until it sticks, because the
+ # walk is the point and a 503 on the first call is not.
+ for _ in range(6):
+ if not screen.find(AT_LOGIN):
+ break
+ _clear_dialog(c)
+ try:
+ c.app.provision_by_form(c.tw.host, merchant.DEMO_INSTANCE,
+ merchant.DEMO_SECRET, expect_success=False)
+ except PosError as e:
+ c.ep.note(f"login retry: {e}")
+ screen = c.app._stable_dump()
+ c.require(not screen.find(AT_LOGIN),
+ "the terminal got a session despite the chaos")
+ c.ep.note("logged in under chaos; walking")
+ for destination in ("amount", "inventory", "history", "settings",
+ "amount", "history", "inventory"):
+ try:
+ c.app.goto(destination)
+ except (PosError, TimeoutError) as e:
+ c.ep.note(f"goto {destination}: {e}")
+ screen = c.app._stable_dump()
+ if c.app.read_dialog(screen) is not None:
+ c.app.dismiss_dialog()
+ continue
+ screen, findings = c.ep.observe()
+ dialog = c.app.read_dialog(screen)
+ if dialog is not None:
+ c.ep.note(f"{destination}: {dialog}")
+ _judge_message(c, f"{dialog.title} {dialog.message}",
+ f"a 503 while opening {destination}")
+ _clear_dialog(c)
+ c.require(True, "the terminal was walked under a 12% failure rate")
+ screen, _ = c.ep.observe()
+ c.expect(not bool(screen.find(MARK_FETCHING)),
+ "stuck-on-spinner-after-chaos",
+ "a walk under random 503s ended on the configuration spinner",
+ " | ".join(screen.texts())[:500])
+
+
+@scenario("fault", "demo")
+def fault_token_request_tampered(c: Ctx) -> None:
+ """The login's own token request is altered on the way up.
+
+ Twister can mutate a *request*, not only a reply, and the terminal's login
+ is the one place it sends a body of its own -- the token request carrying
+ the scope and the duration. A backend that gets a scope the terminal did
+ not ask for is a thing no amount of reply-breaking can produce.
+ """
+ c.provision_twister(expect_success=False,
+ arm_during_login=(("modify_upload", "scope", "readonly"),))
+ body, _ = _fault_dialog_text(c)
+ c.ep.note(f"login with a tampered token request: {body[:300]}")
+ screen, _ = c.ep.observe()
+ _judge_message(c, body if body.strip() else "ok",
+ "a token request altered in flight")
+ c.require(True, "the token request was altered in flight and the terminal "
+ "neither crashed nor hung")
+ c.expect(not bool(screen.find(MARK_FETCHING)),
+ "stuck-on-spinner-after-tampered-token",
+ "a tampered token request left the terminal on the spinner",
+ " | ".join(screen.texts())[:500])
+
+
+def _order_total(screen) -> Optional[str]:
+ """The order screen's running total, as it is drawn.
+
+ Two places carry it and the wording differs: the order pane's header says
+ "Total: KUDOS 5.50" and the complete button says "Bill KUDOS 5.50"
+ (`order_total` and `order_complete_with_amount`). The compact layout
+ drops the header, so a scenario that only knew the first one read an
+ order with a total in it as an order with none.
+ """
+ for pattern in (r"Total:\s*(\S.*)$", r"^Bill\s+(\S.*)$"):
+ for node in screen.nodes:
+ m = re.search(pattern, node.label.strip())
+ if m:
+ return m.group(1).strip()
+ return None
+
+
+def _order_id_from(uri: Optional[str]) -> Optional[str]:
+ """The order id inside a `taler://pay/` URI."""
+ if not uri:
+ return None
+ m = re.search(r"/instances/[^/]+/([^/?]+)/?", uri)
+ if m:
+ return m.group(1)
+ m = re.search(r"taler(?:\+http)?://pay/[^/]+/([^/?]+)", uri)
+ return m.group(1) if m else None
+
+
+# -- the runner -----------------------------------------------------------
+
+
+def run_one(name: str, out_dir: Path, coverage_dir: Optional[Path]) -> dict:
+ fn, tags, doc = SCENARIOS[name]
+ dev = Device(SERIAL)
+ ep = Episode(dev, out_dir, name=name, coverage_dir=coverage_dir)
+ app = Pos(dev)
+ app.before_wipe = lambda: ep.dump_coverage("before-wipe")
+ c = Ctx(dev=dev, app=app, ep=ep, name=name)
+ started = time.monotonic()
+ outcome, error = "ok", ""
+ try:
+ fn(c)
+ except ScenarioFailure as e:
+ outcome, error = "unreached", str(e)
+ except (PosError, TimeoutError) as e:
+ outcome, error = "unreached", f"{type(e).__name__}: {e}"
+ except Exception as e:
+ outcome, error = "harness-error", f"{type(e).__name__}: {e}"
+ traceback.print_exc()
+ try:
+ ep.observe()
+ except Exception:
+ pass
+ summary = ep.finish({
+ "tags": list(tags),
+ "doc": doc,
+ "outcome": outcome,
+ "error": error,
+ "checks": c.checks,
+ "seconds": round(time.monotonic() - started, 1),
+ })
+ serious = summary["serious"]
+ print(f" {outcome:<14} {name:<36} {summary['seconds']:>6.1f}s "
+ f"{len(summary['findings'])} finding(s), {serious} serious"
+ + (f"\n {error}" if error else ""))
+ return summary
+
+
+def main(argv: list[str]) -> int:
+ ap = argparse.ArgumentParser(description=__doc__,
+ formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("names", nargs="*")
+ ap.add_argument("--list", action="store_true")
+ ap.add_argument("--all", action="store_true")
+ ap.add_argument("--tag", action="append", default=[])
+ ap.add_argument("--skip-tag", action="append", default=[])
+ ap.add_argument("--out", default=None)
+ ap.add_argument("--no-coverage", action="store_true")
+ args = ap.parse_args(argv)
+
+ if args.list:
+ width = max(len(n) for n in SCENARIOS)
+ for name, (_, tags, doc) in SCENARIOS.items():
+ print(f" {name:<{width}} [{','.join(tags)}] {doc}")
+ print(f"\n{len(SCENARIOS)} scenarios")
+ return 0
+
+ chosen = list(args.names)
+ if args.all or args.tag or not chosen:
+ # Named scenarios are kept rather than replaced, so that a selection
+ # can be "everything except the mock set, plus these three mock ones"
+ # -- which is what the campaign asks for when a scenario needs a
+ # screen only one worker's geometry can show.
+ selected = [n for n, (_, tags, _) in SCENARIOS.items()
+ if (not args.tag or set(args.tag) & set(tags))
+ and not (set(args.skip_tag) & set(tags))]
+ chosen = selected + [n for n in chosen if n not in selected]
+ unknown = [n for n in chosen if n not in SCENARIOS]
+ if unknown:
+ print(f"unknown scenario(s): {unknown}; --list shows them all")
+ return 2
+
+ stamp = time.strftime("%Y%m%d-%H%M%S")
+ out_dir = Path(args.out or (SIM_ROOT / "out" / f"suite-{stamp}-w{WORKER}"))
+ out_dir.mkdir(parents=True, exist_ok=True)
+ coverage_dir = None if args.no_coverage else SIM_ROOT / "run" / "coverage"
+ if coverage_dir:
+ coverage_dir.mkdir(parents=True, exist_ok=True)
+
+ print(f"{len(chosen)} scenario(s) on {SERIAL}, artifacts in {out_dir}")
+ summaries = []
+ try:
+ for name in chosen:
+ summaries.append(run_one(name, out_dir, coverage_dir))
+ finally:
+ stop_mocks()
+ stop_twisters()
+
+ (out_dir / "suite.json").write_text(json.dumps(summaries, indent=2))
+ ok = [s for s in summaries if s["outcome"] == "ok"]
+ unreached = [s for s in summaries if s["outcome"] == "unreached"]
+ broken = [s for s in summaries if s["outcome"] == "harness-error"]
+ serious = sum(s["serious"] for s in summaries)
+ print(f"\n{len(ok)} ok, {len(unreached)} unreached, {len(broken)} harness errors; "
+ f"{serious} serious finding(s) across {len(summaries)} scenarios")
+ print(f"artifacts: {out_dir}")
+ return 0 if not broken else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/pos-simulator/emu/emu.sh b/pos-simulator/emu/emu.sh
@@ -0,0 +1,230 @@
+#!/bin/bash
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+#
+# Emulator lifecycle for the POS simulator. One AVD per worker; the worker
+# index picks both the AVD name and the (even) console port, so several workers
+# can run side by side.
+#
+# Unlike the wallet's equivalent this does not map any ports by default: the
+# terminal talks to a merchant backend on the public internet, which the
+# emulator reaches through its own NAT. "reverse" exists for the mock
+# backend, which runs on the host.
+#
+# Usage:
+# emu.sh create <worker> create/replace the AVD
+# emu.sh boot <worker> [poster] boot headless, optionally with a QR
+# code hanging in the virtual scene
+# emu.sh prepare <worker> [apk] install the terminal, grant permissions,
+# kill animations
+# emu.sh reverse <worker> [port...] map host ports into the emulator
+# emu.sh serial <worker> print the adb serial
+# emu.sh kill <worker> shut the emulator down
+#
+# A phone-sized worker, for the other half of every screen that has two:
+#
+# POS_LCD_WIDTH=1920 POS_LCD_HEIGHT=1080 POS_LCD_DENSITY=420 \
+# emu.sh create 3 && ... boot 3 && ... prepare 3
+
+set -eu
+
+SIM_ROOT=${POS_SIM_ROOT:-/opt/taler-pos-sim}
+export ANDROID_SDK_ROOT=${ANDROID_SDK_ROOT:-/opt/android-sdk}
+export ANDROID_HOME=$ANDROID_SDK_ROOT
+export ANDROID_AVD_HOME=${ANDROID_AVD_HOME:-$SIM_ROOT/avd}
+ADB=$ANDROID_SDK_ROOT/platform-tools/adb
+EMULATOR=$ANDROID_SDK_ROOT/emulator/emulator
+AVDMANAGER=$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/avdmanager
+IMAGE=${POS_SYSTEM_IMAGE:-"system-images;android-36;google_apis;x86_64"}
+PKG=${POS_PKG:-net.taler.merchantpos}
+BOOT_TIMEOUT=${POS_BOOT_TIMEOUT:-300}
+# A PNG to hang on the wall of the emulator's virtual scene, so the camera has
+# something real to decode. Only settable at launch, hence one boot per image.
+POSTER=${POS_POSTER:-}
+
+die() { echo "emu.sh: $*" >&2; exit 1; }
+
+worker=${2:-0}
+avd_name() { echo "taler-pos-$worker"; }
+api_level() { echo "$IMAGE" | sed -n 's/.*android-\([0-9][0-9]*\).*/\1/p'; }
+# The virtual scene camera, which is what lets a QR code be shown to the
+# device, needs an image that can deliver NV21 frames: below API 26 the camera
+# service rejects the format and retries until the boot times out.
+camera_back() { [ "$(api_level)" -ge 26 ] 2>/dev/null && echo virtualscene || echo emulated; }
+old_image() { [ "$(api_level)" -lt 29 ] 2>/dev/null; }
+ram_size() { old_image && echo 2048 || echo 4096; }
+heap_size() { old_image && echo 256 || echo 512; }
+data_partition() { old_image && echo 2048M || echo 6144M; }
+# Not 5554: the wallet simulator numbers its workers from there, and a second
+# harness starting on an occupied port does not boot anything -- it silently
+# attaches to the other one's emulators and drives the wrong app.
+POS_PORT_BASE=${POS_PORT_BASE:-5584}
+# 2560x1600 at 320dpi is 1280x800dp, so smallestScreenWidthDp is 800 and every
+# screen takes its tablet branch. 1920x1080 at 420dpi is 731x411dp, which is
+# a phone on both counts -- and small enough on the short edge for the amount
+# keypad's `isCompactPhone` arm as well.
+LCD_WIDTH=${POS_LCD_WIDTH:-2560}
+LCD_HEIGHT=${POS_LCD_HEIGHT:-1600}
+LCD_DENSITY=${POS_LCD_DENSITY:-320}
+console_port() { echo $((POS_PORT_BASE + 2 * worker)); }
+serial() { echo "emulator-$(console_port)"; }
+
+create() {
+ mkdir -p "$ANDROID_AVD_HOME"
+ # A tablet profile, not a phone: five of the terminal's screens pick their
+ # layout on `smallestScreenWidthDp >= 720` -- the order grid, the payment
+ # screen, the refund URI screen, the QR config tab and the amount keypad --
+ # so a phone-sized AVD runs a different half of the app. Both are worth
+ # running; the default is the tablet, because that is what a counter has on
+ # it. The device profile does not decide this on its own: the LCD is set
+ # below and overrides whatever the profile says, so POS_LCD_* is what
+ # actually moves the app from one layout to the other.
+ local device=${POS_AVD_DEVICE:-medium_tablet}
+ echo no | "$AVDMANAGER" create avd -n "$(avd_name)" -k "$IMAGE" \
+ -d "$device" --force >/dev/null
+ local cfg="$ANDROID_AVD_HOME/$(avd_name).avd/config.ini"
+ python3 - "$cfg" "$(camera_back)" "$(ram_size)" "$(heap_size)" \
+ "$(data_partition)" "$LCD_WIDTH" "$LCD_HEIGHT" "$LCD_DENSITY" <<'PY'
+import sys
+path = sys.argv[1]
+cfg = {}
+for line in open(path):
+ if '=' in line:
+ k, v = line.rstrip('\n').split('=', 1)
+ cfg[k] = v
+# A temp data partition would throw away everything on shutdown; the rest is
+# headless tuning. The LCD is landscape because the app is: an emulator whose
+# natural orientation is portrait still works, but every screenshot comes out
+# rotated and the virtual scene's poster ends up on its side.
+cfg.pop('disk.dataPartition.path', None)
+cfg.update({
+ 'hw.ramSize': sys.argv[3],
+ 'vm.heapSize': sys.argv[4],
+ 'disk.dataPartition.size': sys.argv[5],
+ 'hw.audioInput': 'no',
+ 'hw.audioOutput': 'no',
+ 'hw.camera.back': sys.argv[2],
+ 'hw.camera.front': 'emulated',
+ 'hw.keyboard': 'yes',
+ 'hw.gpu.enabled': 'yes',
+ 'hw.gpu.mode': 'swiftshader_indirect',
+ 'hw.lcd.width': sys.argv[6],
+ 'hw.lcd.height': sys.argv[7],
+ 'hw.lcd.density': sys.argv[8],
+ 'hw.initialOrientation': 'landscape',
+ 'showDeviceFrame': 'no',
+})
+with open(path, 'w') as f:
+ f.writelines(f'{k}={v}\n' for k, v in sorted(cfg.items()))
+PY
+ echo "created $(avd_name)"
+}
+
+kill_emu() {
+ local s waited=0 port pid
+ s=$(serial)
+ port=$(console_port)
+ "$ADB" -s "$s" emu kill >/dev/null 2>&1 || true
+ # Waiting matters: `emu kill` returns as soon as the console accepts it,
+ # and a process still holding the AVD's lock files stops the next boot.
+ while [ "$waited" -lt 90 ]; do
+ "$ADB" devices 2>/dev/null | grep -q "^$s" || break
+ sleep 2
+ waited=$((waited + 2))
+ done
+ for _ in $(seq 1 30); do
+ pid=$(pgrep -f -- "-port $port" | head -1)
+ [ -n "$pid" ] || break
+ kill "$pid" 2>/dev/null || true
+ sleep 2
+ done
+ rm -f "$ANDROID_AVD_HOME/$(avd_name).avd"/*.lock 2>/dev/null || true
+ echo "killed $s after ${waited}s"
+}
+
+boot() {
+ local log="$SIM_ROOT/run/emu-$worker.log"
+ mkdir -p "$SIM_ROOT/run"
+ "$ADB" start-server >/dev/null 2>&1 || true
+ local camera poster_args=()
+ camera=$(camera_back)
+ local poster=${3:-$POSTER}
+ if [ -n "$poster" ] && [ "$camera" = virtualscene ]; then
+ [ -r "$poster" ] || die "no poster image at $poster"
+ poster_args=(-virtualscene-poster "wall=$poster")
+ fi
+ local wipe_args=()
+ [ "${POS_KEEP_DATA:-0}" = "1" ] || wipe_args=(-wipe-data)
+ setsid "$EMULATOR" -avd "$(avd_name)" -port "$(console_port)" \
+ -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect \
+ -no-snapshot-load -no-snapshot-save "${wipe_args[@]}" \
+ -camera-back "$camera" "${poster_args[@]}" \
+ > "$log" 2>&1 < /dev/null &
+ echo "booting $(avd_name) on $(serial), log $log" >&2
+ local waited=0
+ while [ "$waited" -lt "$BOOT_TIMEOUT" ]; do
+ if [ "$("$ADB" -s "$(serial)" shell getprop sys.boot_completed 2>/dev/null | tr -d '\r\n')" = "1" ]; then
+ echo "booted after ${waited}s"
+ return 0
+ fi
+ sleep 2
+ waited=$((waited + 2))
+ done
+ tail -20 "$log" >&2 || true
+ die "emulator did not finish booting within ${BOOT_TIMEOUT}s"
+}
+
+reverse() {
+ local s p
+ s=$(serial)
+ shift 2 2>/dev/null || true
+ local ports=("$@")
+ [ ${#ports[@]} -gt 0 ] || ports=(${POS_MOCK_PORT:-19443})
+ for p in "${ports[@]}"; do
+ "$ADB" -s "$s" reverse "tcp:$p" "tcp:$p" >/dev/null
+ done
+ echo "mapped ${ports[*]} into $s"
+}
+
+prepare() {
+ local s apk
+ s=$(serial)
+ apk=${3:-$SIM_ROOT/apk/pos.apk}
+ [ -r "$apk" ] || die "no APK at $apk"
+ # Deterministic, animation-free UI: the driver reads the view hierarchy and
+ # animations make it race.
+ "$ADB" -s "$s" shell settings put global window_animation_scale 0
+ "$ADB" -s "$s" shell settings put global transition_animation_scale 0
+ "$ADB" -s "$s" shell settings put global animator_duration_scale 0
+ "$ADB" -s "$s" shell settings put secure long_press_timeout 250
+ "$ADB" -s "$s" shell svc power stayon true
+ # The terminal is landscape-locked, so the system will rotate the window
+ # whatever this says; pinning it stops the *launcher* from rotating under
+ # the app, which is what makes a screenshot come out sideways.
+ "$ADB" -s "$s" shell settings put system accelerometer_rotation 0
+ "$ADB" -s "$s" shell install -r -g "$apk" 2>/dev/null \
+ || "$ADB" -s "$s" install -r -g "$apk"
+ "$ADB" -s "$s" shell pm grant "$PKG" android.permission.CAMERA 2>/dev/null || true
+ echo "prepared $s with $apk"
+}
+
+case "${1:-}" in
+ create) create ;;
+ boot) boot "$@" ;;
+ prepare) prepare "$@" ;;
+ reverse) reverse "$@" ;;
+ serial) serial ;;
+ kill) kill_emu ;;
+ *) die "usage: emu.sh {create|boot|prepare|reverse|serial|kill} <worker> [arg]" ;;
+esac
diff --git a/pos-simulator/emu/twister.sh b/pos-simulator/emu/twister.sh
@@ -0,0 +1,53 @@
+#!/bin/bash
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+#
+# Build taler-twister on the emulator host.
+#
+# It has to be built *there* and not in the workspace's shared prefix, because
+# that is where the driver runs and where the proxy has to listen. It needs no
+# Taler libraries of its own -- GNUnet's util/json/curl, libmicrohttpd, jansson,
+# zlib and libcurl are all it links against, and a Debian with the gnunet-dev
+# packages has every one of them -- so --with-gnunet=/usr is usually right and
+# nothing from ~/target is involved.
+#
+# Usage: twister.sh <path-to-a-twister-checkout-or-tarball> [prefix]
+
+set -eu
+
+SRC=${1:?usage: twister.sh <twister-src> [prefix]}
+PREFIX=${2:-/tmp/twister-build/inst}
+BUILD=${POS_TWISTER_BUILD:-/tmp/twister-build/src}
+
+for p in gnunetutil libmicrohttpd jansson libcurl zlib; do
+ pkg-config --exists "$p" ||
+ { echo "twister.sh: missing $p (install the -dev package)" >&2; exit 1; }
+done
+
+mkdir -p "$BUILD"
+if [ -d "$SRC" ]; then
+ tar -C "$SRC" --exclude=.git -cf - . | tar -C "$BUILD" -xf -
+else
+ tar -C "$BUILD" -xf "$SRC"
+fi
+
+cd "$BUILD"
+./bootstrap
+./configure --with-gnunet="${POS_GNUNET_PREFIX:-/usr}" --prefix="$PREFIX"
+make -j"$(nproc)"
+make install
+
+echo
+echo "built: $PREFIX/bin/taler-twister-service"
+echo "point the driver at it with POS_TWISTER_PREFIX=$PREFIX"
diff --git a/pos-simulator/env.sh b/pos-simulator/env.sh
@@ -0,0 +1,25 @@
+# Source this before driving the POS simulator.
+#
+# Everything volatile lives under POS_SIM_ROOT: the AVDs, the emulator's own
+# state, the episode artifacts and the coverage dumps. On tripwire that is a
+# tmpfs, because the root filesystem is shared with several other projects and
+# is full; an AVD's data partition is sparse, so a worker costs a few GB of
+# the box's 251 GB of RAM and nothing on disk. Nothing here needs to survive a
+# reboot: the code is in git and the findings are copied out as they are made.
+export POS_SIM_ROOT=${POS_SIM_ROOT:-/tmp/taler-pos-sim}
+export ANDROID_SDK_ROOT=${ANDROID_SDK_ROOT:-/opt/android-sdk}
+export ANDROID_HOME=$ANDROID_SDK_ROOT
+export ANDROID_AVD_HOME=$POS_SIM_ROOT/avd
+# The emulator otherwise scatters snapshots and crash reports through $HOME.
+export ANDROID_EMULATOR_HOME=$POS_SIM_ROOT/emulator-home
+export ANDROID_PREFS_ROOT=$POS_SIM_ROOT/emulator-home
+# The emulator console ports this harness owns. The wallet simulator uses
+# 5554 upwards; sharing them means whichever harness starts second attaches to
+# the other's emulators instead of booting its own.
+export POS_PORT_BASE=${POS_PORT_BASE:-5584}
+export POS_ADB=$ANDROID_SDK_ROOT/platform-tools/adb
+export POS_WALLET_CLI=${POS_WALLET_CLI:-$(command -v taler-wallet-cli || echo /root/.local/bin/taler-wallet-cli)}
+export POS_WALLET_DIR=$POS_SIM_ROOT/run/wallets
+export PATH=$ANDROID_SDK_ROOT/platform-tools:$PATH
+mkdir -p "$ANDROID_AVD_HOME" "$ANDROID_EMULATOR_HOME" "$POS_SIM_ROOT/run" \
+ "$POS_SIM_ROOT/out" "$POS_WALLET_DIR"
diff --git a/pos-simulator/findings/ROUND1.md b/pos-simulator/findings/ROUND1.md
@@ -0,0 +1,206 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# POS simulator, round one
+
+The first round of the harness described in `../README.md`, run on
+`tripwire.taler.net` on 2026-10-29 against
+
+* `backend.demo.taler.net`, instance `sandbox`, backend version `42:0:30`,
+ currency KUDOS, with a customer wallet funded from `bank.demo.taler.net`
+ through `taler-wallet-cli` 1.6.48;
+* `backend/mockd.py`, for the merchant configurations a shared public instance
+ cannot be made to have.
+
+The app under test is `merchant-terminal` at `1.6.6` (versionCode 29), built
+from this branch's `sim` build type.
+
+### Accounts this round created
+
+* `possim` at `bank.demo.taler.net`, password `possim-pos-simulator` -- the
+ customer's bank account, derived from the name so that a re-run adopts it
+ rather than failing to register a new one. It holds play money and is not a
+ credential worth protecting; `counterparty.customer()` recreates it from
+ nothing.
+* No new instance at `backend.demo.taler.net`. Self-provisioning is enabled
+ there but `mandatory_tan_channels` is `["email"]`, so `POST /instances`
+ answers 202 with an emailed challenge:
+
+ ```json
+ {"combi_and": true,
+ "challenges": [{"tan_channel": "email", "challenge_id": "249-XGVEK8NW..."}]}
+ ```
+
+ which the harness cannot solve on its own. Everything a fresh or broken
+ instance is needed *for* is covered by `backend/mockd.py` instead; what is
+ *not* covered, and would need a real one, is the two-factor path in
+ `ConfigFragment.fetchLimitedAccessTokenWithMfa` -- see the next round.
+
+ Orders and refunds were added to the shared `sandbox` instance, which is
+ what it is for; nothing else there was modified.
+
+## Findings
+
+Each has a write-up and a standalone reproducer beside it, and three carry a
+patch that compiles; the first has also been verified to stop the failure it
+fixes.
+
+| | Finding | Severity |
+| --- | --- | --- |
+| 1 | [The QR configuration tab crashes the terminal on the first camera frame](qr-config-tab-crashes-the-terminal.md) | high |
+| 2 | [A refund amount with two decimal points refunds a different number](refund-amount-swallows-extra-decimal-points.md) | medium-high |
+| 3 | [A freshly provisioned merchant instance cannot be used at all](fresh-instance-cannot-be-used.md) | high for a new user |
+| 4 | [An expired session shows a protocol error instead of asking for credentials](expired-session-shows-a-protocol-error.md) | medium |
+| 5 | [A backend that never answers leaves the login form behind a spinner forever](login-hangs-forever-on-a-silent-backend.md) | medium-high |
+| 6 | [The terminal asks for its configuration at `/private%2Fpos`](pos-config-url-percent-encodes-the-separator.md) | medium |
+| 7 | [A `taler-pos://` setup URI loses the backend's port](setup-uri-drops-the-port.md) | medium |
+| 8 | [A failed configuration fetch leaves the terminal on its spinner for good](config-fetch-failure-strands-the-spinner.md) | medium |
+| 9 | [Controls a screen reader cannot announce](controls-without-accessible-names.md) | low, three of them |
+
+Every part of the harness earned its place:
+
+* The **emulator** found 1 and 8. The crash needs a camera frame to arrive, and
+ an accessible name is missing from the view hierarchy or it is not.
+* The **customer wallet** found 2. The refund form will accept `1.000.50`
+ whether or not anybody is watching; what makes it a finding rather than a
+ guess is that a real order was paid, a real refund was made against it, and
+ the backend recorded KUDOS:1.
+* The **mock backend** found 3, 5 and 6. A fresh instance, a peer that accepts
+ and goes quiet, and a router that does not decode encoded slashes are three
+ things a correct public backend cannot be asked to be.
+* **Minting credentials** found 4 and 7 -- an expiring token is not something
+ the terminal can ask for, so nothing that drives only the UI can reach that
+ path at all.
+
+## What the terminal got right
+
+Worth recording, because a harness that only reports failures gives no sense of
+what it covered:
+
+* **Version negotiation.** A backend advertising `11:0:0` is refused with
+ "Service outdated. Please wait until it gets upgraded."; one advertising
+ `60:0:2` with "App too old. Please upgrade!". Both messages name the right
+ party. (The first version of the mock's `version-old` profile said `12:0:0`,
+ which the terminal accepted -- correctly, since `12:0:0` and the terminal's
+ `20:0:8` overlap at 12. The finding was the profile's, not the app's.)
+* **A wrong password** produces "Error: Invalid username or password" and
+ leaves the login form usable.
+* **An unreachable host** fails quickly and says "Error: Could not connect to
+ configuration server", with no exception text in the dialog.
+* **A real backend error** keeps its status: a 502 from the demo backend during
+ a history refresh produced "Error fetching the order history / Server error
+ (502)".
+* **The unsellable-product badges, on real data.** The `sandbox` inventory
+ contains a product priced in a currency the instance does not use, and the
+ grid shows it with "Wrong currency" rather than offering it. The
+ `instance_wrong_currency` mock profile was built to test that path and the
+ shared instance turned out to exercise it anyway.
+* **Refund validation, three times out of four.** On an order of 1.00, the
+ form refuses `99.00` with "Greater than order amount of 1.00", `0.00` with
+ "Needs to be positive amount" and `abc` with "Invalid amount". Only
+ `1.0.0` gets through -- which is finding 2, and which is why that one is a
+ parser bug rather than a missing feature.
+* **Payment end to end.** An order billed on the keypad, paid by a real wallet
+ from a real bank, acknowledged by the terminal, confirmed paid at the
+ backend -- then refunded, the refund accepted by the same wallet, and the
+ backend's `refunded` flag confirming it. The whole loop, both directions.
+
+## False positives, found and removed
+
+Every scenario that reported one was re-run against the corrected harness, and
+every one of these came back clean -- which is the only way to tell a fixed
+harness bug from a defect that stopped reproducing:
+
+| Reported | What it really was | Re-run |
+| --- | --- | --- |
+| `zero-amount-accepted-silently` | an empty dump read as a screen with nothing on it | `amount_keypad_edges` ok |
+| `offline-start-dead-end` | the same; the terminal does come up on its cached configuration offline | `offline_at_startup` ok |
+| `stuck-after-auth-error` | the same | `login_wrong_password` ok |
+| `cancelled-logout-logged-out` | "Merchant portal URL" stands for the login form *and* for a row in Settings' About block | `settings_logout_cancelled` ok |
+| `version-mismatch-silent` | the mock's "too old" profile said `12:0:0`, which overlaps the terminal's `20:0:8` at 12 and is correctly accepted | `backend_version_mismatch` ok at `11:0:0` |
+| `setup-uri-dead-end` | a dialog is its own window, so the login form behind it is not in that dump | replaced by finding 8, which is sharper |
+| `silent-failure` x4 | a random walk tapping prices and status badges, correlated with background backend errors by nothing but timing | oracle now ignores non-actions |
+| `qr-tab-crash-without-permission` | the system permission dialog is a different activity | recognised |
+| `empty-hierarchy` x8, `url-shape-rejected` x3 | dumps that lost their race with the UI | `Episode.observe` retries |
+
+The harness changes are in the three commits after the first; the scenarios
+themselves were not weakened, and several got stricter on the way (`Ctx.expect`
+against the backend rather than against the screen alone).
+
+Three harness failures were not false positives but plain bugs in the driver,
+all fixed: an `am start -W` that hung for its full timeout and aborted a
+scenario with a traceback about adb, a customer wallet allowed to run dry
+mid-round, and a refund URI built without the trailing slash the backend's own
+builder writes.
+
+## Coverage
+
+JaCoCo, merged across 117 execution dumps from every episode of the round. The
+figures are `merchant-terminal`'s own classes; `merchant-lib` and
+`taler-kotlin-android` are reported as sources but not instrumented, because
+only the application module's classes carry the agent.
+
+```
+instruction 31097/40234 77.3%
+branch 1063/1739 61.1%
+line 3827/4864 78.7%
+complexity 1111/1897 58.6%
+method 792/1047 75.6%
+class 123/140 87.9%
+```
+
+One class is entirely untouched -- `HistoryManager$forceDeleteOrder$1`, twelve
+lines -- and `coverage/gaps.py` ranks the rest:
+
+```
+ 288 missed 79.1% ~.config
+ 228 missed 62.5% ~.payment
+ 187 missed 80.8% ~.order
+ 144 missed 67.5% ~.refund
+ 85 missed 80.0% ~.history
+```
+
+The payment package is the weakest at 62.5%, and the shape of what is missing
+is consistent: `ProcessPaymentFragmentKt` is at 42.5% because its three
+dialogs -- force delete, the insecure-payment prompt and the payment error --
+are each reached by one path and the insecure-URI one not at all. That needs a
+backend handing out a `taler+http://` pay URI, which neither the demo backend
+nor the mock currently does; it is one mock profile away.
+
+Branch coverage lagging line coverage by eighteen points is the other thing to
+read: the scenarios walk each feature once, so the second arm of most `if`s is
+untaken. That is what the random walk is for, and one 220-step walk is not
+enough of it.
+
+## What the next round should do
+
+1. **Finish verifying the QR fix.** The patch stops the crash and the preview
+ renders, but no code has yet been decoded through the emulator's
+ virtual-scene camera, so the stride and rotation handling is reasoned rather
+ than demonstrated. `driver/qrposter.py` is the tool; the poster is on the
+ wall and the decode has not fired.
+2. **A fresh instance on the demo backend.** Self-provisioning there needs an
+ emailed TAN, which the harness cannot solve. Everything a fresh instance is
+ needed *for* is covered by the mock, but a real one would also exercise the
+ two-factor path in `fetchLimitedAccessTokenWithMfa`, which nothing currently
+ reaches.
+3. **The refund package**, which is the largest uncovered area and whose
+ scenarios are the slowest -- they need a paid order each.
+4. **The NFC half of tap-to-pay**, which no emulator can reach: the terminal's
+ host card emulation needs an NFC adapter, and no system image has one. This
+ may need a physical device or a different emulator.
+5. **More exploration.** One 220-step walk is not many; the walk is where
+ sequences nobody would write down come from.
diff --git a/pos-simulator/findings/ROUND2.md b/pos-simulator/findings/ROUND2.md
@@ -0,0 +1,201 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# POS simulator, round two: fault injection and the other layout
+
+Round two set out to raise coverage, with `taler-twister` for the network side.
+It ran in two passes. The first used five emulators, which `tripwire` cannot
+carry -- load reached 10 and the time per scenario went from about ninety
+seconds to several minutes -- and was abandoned half finished. The second used
+three, which is what the box takes: load settled around three and the pace came
+back. Everything below is from the second pass plus what the first had already
+collected.
+
+## Coverage
+
+```
+ round one round two
+instruction 31097/40234 77.3% 34219/40234 85.0%
+branch 1063/1739 61.1% 1159/1739 66.6%
+line 3827/4864 78.7% 4155/4864 85.4%
+complexity 1111/1897 58.6% 1217/1897 64.2%
+method 792/1047 75.6% 835/1047 79.8%
+class 123/140 87.9% 130/140 92.9%
+```
+
+`+328` lines and `+96` branches, and **no class is at 0% any more**: round
+one's one untouched class, `HistoryManager$forceDeleteOrder$1`, is reached
+now. The round-one dumps are merged in: the APK is
+byte-identical, and jacoco matches execution data to classes by checksum.
+
+Where it went:
+
+```
+ProcessPaymentFragmentKt 42.5% -> 93.4% (+115 lines)
+AmountEntryFragmentKt 78.7% -> 95.6% (+46)
+OrderFragmentKt 76.4% -> 84.7% (+51)
+PaymentManager 62.1% -> 83.5% (+22)
+ConfigManager 71.3% -> 82.2% (+28)
+~.payment (package) 62.5% -> 90.5%
+```
+
+Branch coverage rose by five and a half points against line coverage's six and
+a half, where round one had branch coverage lagging line coverage by
+eighteen. That is what the
+fault scenarios bought: the lines were already being executed, and what was
+missing was the arm taken when the backend misbehaves.
+
+## What moved, and why
+
+### A phone-sized emulator
+
+Five of the terminal's screens choose their layout at runtime on
+`smallestScreenWidthDp >= 720` -- the order grid, the payment screen, the
+refund URI screen, the QR config tab and the amount keypad (the last on
+`>= 600`, with a third arm for a short screen). Round one ran a tablet only,
+so the phone half of each was never executed, and in three of those files it is
+the larger half.
+
+The device profile does not decide this: `emu.sh` writes the LCD geometry into
+the AVD and that is what the app sees, so a `medium_phone` AVD still came up
+2560x1600 at 320dpi -- 1280x800dp, a tablet. `POS_LCD_*` settles it, and
+1920x1080 at 420dpi is 731x411dp.
+
+### Twister: a real backend made to go wrong
+
+`driver/faults.py` puts `taler-twister` -- the fault-injecting proxy the C test
+suites use -- in front of `backend.demo.taler.net`, and `driver/suite.py` gains
+thirteen `fault` scenarios. Everything stays real except the one field, status
+code or byte count that was armed. Two things had to be bridged:
+
+* **TLS.** Twister is a plain HTTP proxy and the terminal hard-codes `https://`.
+ `faults.TlsFront` terminates TLS with the certificate the mock already uses
+ and relays bytes -- a byte relay, not an HTTP proxy, so keep-alive, chunked
+ bodies and uploads pass through untouched.
+* **One mutation, one request.** A twister mutation is consumed when it fires,
+ which suits a test script and not a screen that polls: the insecure-pay-URI
+ dialog opens on one poll of the order status and the next poll closes it.
+ `Twister.sustain()` re-arms in a loop.
+
+`TlsFront` also injects what twister has no notion of because it is below HTTP:
+a body that stops halfway, or a reset while the request is still going up.
+
+### A mock backend that demands a two-factor code
+
+Round one reported the two-factor login path as unreachable: the demo backend
+has `mandatory_tan_channels: ["email"]` and mails the code. It is reachable
+after all -- a mock can be that backend with a code the harness knows, and the
+terminal cannot tell the difference. The whole dance is four requests and one
+header, and `ChallengeRequiredException`,
+`ConfigFragment.fetchLimitedAccessTokenWithMfa` and `ConfigManager`'s challenge
+calls are now covered.
+
+Three scenarios walk it: one channel chosen from two; three wrong codes and
+then the right one, which covers both statuses the terminal treats as
+recoverable (409 "wrong code" and 429 "a new code is on its way"); and
+`combi_and`, where both channels must be answered and no chooser is shown.
+
+## Findings
+
+| | Finding | Severity |
+| --- | --- | --- |
+| 10 | [A connection that dies mid-response is reported in the HTTP engine's words](transport-error-shows-the-library-wording.md) | low-medium |
+| 11 | [A missing field is reported to the cashier by its Kotlin type name](serialization-error-shown-to-the-cashier.md) | low-medium |
+
+Both are the same arm of `Response.getFailureString` -- the one that shows
+`exception.message` -- and both are reachable only through a proxy over a real
+backend. A cut connection produces OkHttp's "unexpected end of stream"; a
+deleted field produces kotlinx.serialization's "Field 'orders' is required for
+type with serial name 'net.taler.merchantlib.OrderHistory'". Round one's nine
+stand.
+
+Also observed, and not promoted to a finding because it has not been checked on
+a real device:
+
+* **The login form does not fit a phone in landscape.** At 731x411dp the form
+ ends below the bottom edge: Password is clipped, and Connect and the
+ "No instance?" help card are off-screen, with nothing to say the screen
+ scrolls. The terminal is landscape-locked, so turning the device is not
+ available. The driver now scrolls; a person would have to work it out.
+
+## What the terminal got right
+
+* **A sold-out product.** A 410 carrying `product_id` and the quantities is the
+ one backend error the terminal translates rather than quotes, and it does:
+ "Error: Not enough inventory available / Inventory stock unavailable for
+ product ...". It reloads the inventory afterwards, as it should.
+* **The insecure payment link**, from all three sides. Twister handing out a
+ `taler+http://` URI raises "Payment link problem", and "Try fixed link"
+ produces a `taler://` URI, "Continue as is" keeps the insecure one, and
+ "Cancel order" leaves the payment screen. The wording names no scheme, which
+ is the right call for a cashier.
+* **Two-factor login**, including three wrong codes in a row: the terminal
+ asked again each time, requested a fresh code when the backend rate-limited
+ it, and sent the code hyphenated as `0000-0000` the way the backend expects.
+* **An order whose reply was truncated.** The order really was created; the
+ terminal reported the failure and left no second order behind.
+
+## False positives, found and removed
+
+Four this round, each confirmed by re-running the scenario against the
+corrected harness:
+
+| Reported | What it really was |
+| --- | --- |
+| `zero-amount-accepted-silently` | at 0.00 the charge button is *disabled*, which is better than a dialog; the oracle insisted on the dialog |
+| `keypad-overflow-blank` | the keypad groups thousands, so its largest amount reads `999,999,999,999.99` and the parser only knew the ungrouped shape |
+| `insecure-uri-not-honoured` | the URI was read after `sustain` stopped re-arming, so the backend was healthy again and the terminal had correctly re-read it |
+| `insecure-uri-dialog-says-nothing` | the dialog says "payment link" rather than "http", deliberately; the oracle was looking for the jargon |
+
+Four harness bugs behind them, all fixed:
+
+* **Back dismisses a Compose dialog**, and `tap_button` used Back to put the
+ keyboard away before every tap -- so the custom-product `Add` and the
+ two-factor `OK` disappeared before they could be pressed. The keyboard is now
+ only put away when the dump's own root bounds say it covers the control.
+* **One wallet shared by three workers.** They spent each other's coins; the
+ symptom was one worker topping up to 60 and another failing with
+ "insufficient balance" in whatever scenario came next. One wallet and one
+ bank account per worker now.
+* **A dialog covering the next tap.** A scenario that arms a fault, reads the
+ dialog and arms the next one has to dismiss it first, or it waits out its
+ timeout looking for a button behind a modal.
+* **Scrolling a control out of existence.** `_scroll_into_view` could move a
+ dialog's own list and carry the target off screen; losing it is worse than
+ not having moved it, so that is undone.
+
+## What round three should do
+
+1. **The refund form on a phone**, which is the one open question this round
+ leaves. `refund_full` and `refund_amount_edges` both fail there, twice each,
+ and the screen they fail on carries only its title and the order summary --
+ no amount field, no buttons -- while the same scenarios pass on a tablet.
+ Either the form clips its controls on a short screen, which is a finding, or
+ the driver is still mishandling the keyboard, which is not. A list of labels
+ cannot tell those apart, so `Pos.start_refund` now photographs the screen
+ when it happens and the next run settles it. `RefundUriFragmentKt` at 45.3%
+ is the largest single remainder and sits behind the same door.
+2. **The config package**, the largest remaining gap at 81.1%: the QR
+ configuration tab is most of it, and it crashes (round one, finding 1).
+3. ~~**`fault_login_connection_cut` is flaky through the proxy.**~~ Settled in
+ round three: it was not the proxy. A change to the driver -- putting the
+ keyboard away only when it is over the control -- stopped it being put away
+ on the login form, which does not resize under the IME, so the tap on
+ Connect landed on a key. With the keyboard handled from the window
+ manager's own inset the scenario passes and finding 10 reproduces.
+4. **More chaos.** `fault_chaos_walk` runs the terminal under a 12% failure
+ rate and it came through clean; one walk is not many, and it is the only
+ scenario where a fault arrives at a moment nobody chose.
diff --git a/pos-simulator/findings/ROUND3.md b/pos-simulator/findings/ROUND3.md
@@ -0,0 +1,155 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# POS simulator, round three: what a merchant fills in, and what a cashier taps
+
+Round two broke the backend's replies. Round three went the other way and
+asked what the terminal does with a backend that is *working* but configured
+differently, and with sequences of taps nothing had performed.
+
+## Coverage
+
+```
+ round one round two round three
+instruction 77.3% 85.0% 85.8%
+branch 61.1% 66.6% 68.5%
+line 78.7% 85.4% 86.1%
+class 87.9% 92.9% 92.9%
+```
+
+Branch coverage moved three times as far as line coverage this round, which is
+what a round of *variations* should do: the same lines, with the other value
+in the field.
+
+### What the figures leave out
+
+146 of the 677 missed lines cannot be reached by any run of this build. Eight
+`internal fun *ScreenContent` composables render a screen from a fixture, and
+the only thing that calls them is `ScreenshotActivity` -- which lives in the
+`debug` source set, and `sim` is its own build type and does not include it.
+`OrderScreenContent` alone is 73 lines.
+
+`coverage/gaps.py` now discounts them, so the honest figure is
+
+```
+reachable lines covered: 4187/4718 (88.7%); the ceiling is 97.0%
+```
+
+and the ranking points at work that can actually be done.
+
+## What a merchant fills in
+
+Almost everything a product can carry is optional, and the `healthy` mock
+profile fills in none of it. The new `rich-catalogue` profile fills in all of
+it, one product per thing the terminal does with the metadata:
+
+| Product | What it is for |
+| --- | --- |
+| Espresso | a picture, and a name that is not the description -- `displayName` takes the name and `displayDescription` the description, the only case where a card shows two lines |
+| Flour | stock as decimal strings (`unit_total_stock` and friends), which is `stockLimit`'s BigDecimal arm; an integer count never reaches it |
+| Pastry | six of six sold, so the card says "Out of stock" instead of offering it |
+| Tap water | unlimited stock written as `"-1"` rather than `-1` |
+| Hamper | a tax, a net price and a delivery location, which only `toContractProduct` looks at |
+| Daily paper | no picture at all, so a row mixes products with and without one |
+
+The pictures are real: `ConfigProduct.image` is a `data:image/png;base64,` URL,
+the grid decodes it in two places, and a row lays itself out differently when
+any product in it has one.
+
+Three more things the backend can be:
+
+* **`token-needs-prefix`** hands out a bare token and then refuses it, which is
+ the only way to make `ConfigManager.fetchPosConfig` take its retry -- it
+ sends the token as it has it, and on a 401 sends it again as
+ `secret-token:<it>`.
+* **`mfa-two-channels`** and **`mfa-both-required`** (round two) now also cover
+ giving up: cancelling the code prompt raises `ChallengeCancelledException`,
+ which is its own arm of the login.
+* Finite stock makes the terminal fetch `/private/products/<id>` per product,
+ so `enrichProductsWithStockDetails` runs for real; a restart afterwards
+ exercises `applyCachedStockData`.
+
+## What a cashier taps
+
+Six sequences that nothing had performed:
+
+* **Select an order line and press +1 and -1.** Adding a product is one tap and
+ every scenario did it; selecting the resulting *line* and changing its
+ quantity is three more, and `onSelectProduct`, `onIncrease` and `onDecrease`
+ were untaken on both layouts. One Coffee at 5.50, +1 to 11.00, -1 back to
+ 5.50.
+* **An unparseable price in the custom-product dialog**, which is the arm that
+ sets the error text rather than adding the product.
+* **"Show payment" on an unpaid order in the history**, which rebuilds a
+ payment from a history entry alone (`PaymentManager.resumePayment`); every
+ other route to the payment screen comes from having just created the order.
+* **"Show refund" after a restart**, when the refund the terminal held is gone
+ and `resumeRefund` has to say so.
+* **A merchant URL pasted whole**, scheme and `/instances/<name>` and all,
+ which is what `sanitizeMerchantUrlAndUpdateFields` is for.
+* **The login help card's other two buttons**, and logging in with "Remember
+ password" unticked, which is the arm where `restoreCachedRuntimeConfig` has
+ nothing to restore.
+
+## Findings
+
+[On a phone, a form with a text field loses its buttons to the
+keyboard](refund-form-unusable-on-a-phone.md) -- the open question round two
+left, now answered with a photograph of each case. The refund form loses both
+fields and both buttons; the custom-product dialog keeps reporting its buttons
+at coordinates the keyboard is drawing over, so a tap aimed at **Add** presses
+the key underneath. Round two's findings 10 and 11 stand.
+
+## False positives, found and removed
+
+| Reported | What it really was |
+| --- | --- |
+| `scheme-left-in-the-url-field`, `instance-path-not-split-out` | the form is only rewritten when it is submitted; the scenario read the fields before pressing Connect, and the login that followed bound the right instance |
+| `bad-custom-amount-unexplained` | the tap meant for **Add** landed on the keyboard, so nothing was submitted and there was nothing to explain -- which is the finding above, arrived at the wrong way round |
+
+And four harness bugs behind them:
+
+* **The raw tap action pressed keyboard keys.** `Action("tap_label", …)` taps
+ wherever the dump says the label is, and for a dialog that can be behind the
+ IME. It now declines, and `Pos.control_reachable` lets a scenario judge the
+ app for it instead of tripping over it.
+* **The driver could not see the keyboard.** The IME is not in the
+ accessibility dump and its window frame is the whole screen; the window
+ manager publishes it as an inset, which is exact.
+* **Hiding the keyboard only when it is in the way** -- the fix that made the
+ dialogs tappable -- broke the login form, which does *not* resize under the
+ IME, so nothing said the keyboard was over the Connect button. Where the
+ inset cannot be read, the driver now assumes it is in the way, as it did
+ before.
+* **"Total:" is not the only wording.** The order pane's header says "Total: X"
+ and the complete button says "Bill X"; the compact layout drops the header,
+ so a scenario that knew only the first read an order with a total as an order
+ without one.
+
+## What is left
+
+1. **The QR configuration tab**, about 110 lines of `ConfigFragment` and
+ `ConfigFragmentKt` -- the camera analyzer, the decode, and the phone half of
+ the screen. All of it sits behind round one's finding 1, which is that the
+ tab crashes on the first frame. The patch is written and verified; until it
+ lands this is unreachable.
+2. **The phone and the mock cannot be combined.** A mock scenario has to
+ provision through the login form, because a `taler-pos://` setup URI loses
+ the port (round one, finding 7) -- and the login form does not fit a phone.
+ A mock on port 443, which the harness runs as root and could bind, would
+ need no port in the URI and would unblock the whole `mock` set on a phone.
+3. **`RefundUriFragmentKt` at 45.3%** is the largest single remainder, and it
+ is the phone half of the refund QR screen, behind the finding above.
diff --git a/pos-simulator/findings/ROUND4.md b/pos-simulator/findings/ROUND4.md
@@ -0,0 +1,257 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# Round four: a different app
+
+Rounds one to three measured a terminal of about 4,900 lines. Master's
+`24f7b249` ("[pos] add support for mixed payments and UI changes") added
+**20,753** of them, and the three rounds' findings were all fixed in the same
+commit -- so this round starts against an app two and a half times the size
+with none of its new surface ever driven:
+
+| new | what it is |
+| --- | --- |
+| `checkout/` | 2,843 lines: cash and card taken *before* Taler, change, partial payments, abandoned sales |
+| `devices/` | 2,277 lines: a Bluetooth customer display and a USB one |
+| `paymentoptions/` | 1,323 lines plus 1,492 for SumUp: which methods a terminal offers |
+| `history/OrderDetailsScreen.kt` | 994 lines: an order's products, images, deadlines, refunds |
+| `config/ConfigDraftViewModel.kt` | 348 lines: the login form rebuilt around it |
+
+Five defects were found, each filed with a patch that was built and verified
+on the emulator it was found on (the fifth after the round proper, see the end):
+
+| | severity | filed |
+| --- | --- | --- |
+| [The terminal dies one second after the session ends on the payment screen](payment-poll-crashes-when-the-session-ends.md) | high | [11973](https://bugs.gnunet.org/view?id=11973) |
+| [On a phone, the login form disappears the moment you tap a field](login-form-collapses-under-the-keyboard.md) | high on a phone | [11971](https://bugs.gnunet.org/view?id=11971) |
+| [On a phone, the cash keypad's own button is cut in half](cash-keypad-submit-is-cut-off.md) | medium | [11972](https://bugs.gnunet.org/view?id=11972) |
+| [Every failed delete says a wallet claimed the order](force-delete-blames-a-wallet.md) | medium to high | [11977](https://bugs.gnunet.org/view?id=11977) |
+| ["Paid in full", under a title bar that says "Payment required"](receipt-screen-titled-payment-required.md) | low to medium | [11974](https://bugs.gnunet.org/view?id=11974) |
+
+## The crash
+
+`PaymentManager.checkPayment` dereferences `configManager.merchantConfig!!`,
+and the payment screen calls it once a second from a `CountDownTimer`. The
+field is set to null the moment any request comes back 401 -- which is what a
+session ending *is*. Between the 401 and the next tick there are 869
+milliseconds, and then the process is killed in front of a paying customer.
+
+It is not one line: the same `!!` is in five methods of that file and every one
+of them is reachable after the session has gone, including `cancelPayment`,
+which is what a cashier presses when the screen stops responding. The patch
+routes all of them through one helper that returns null and stops the polling.
+
+Reproduced twice on two emulators; with the patch the terminal shows the
+"Session expired -- please re-enter your credentials" dialog that was always
+written for this and never got a chance to appear.
+
+## What was *not* wrong
+
+Rather more than was wrong, and worth recording because each one cost time:
+
+* **The mixed-payment checkout is correct where it counts.** Ten handed over
+ for a seven-unit bill records a payment of seven, shows "Received ク10.00,
+ change ク3.00", and tells the cashier to hand ク3.00 back. Cash plus Taler
+ splits the way it should: two in cash on a six-unit sale leaves a backend
+ order whose `contract_terms.amount` is `KUDOS:4`, the wallet pays that, and
+ the order ends `paid`. A sale settled entirely in cash reaches the backend
+ as `paid` once the receipt is collected, and a sale abandoned with cash in
+ it stays in the history list as "Paid: ク2.00" with a way to settle it.
+* **Handing cash back works end to end.** The refund screen offers the methods
+ the order was actually paid with, refuses the ones it was not ("GNU Taler
+ ク0.00 Unavailable"), asks for confirmation that the money physically moved,
+ and the backend records it under `refunds_external` -- without counting it
+ as a Taler refund.
+* **The refund form still explains a bad amount.** "Invalid amount", "Needs to
+ be positive amount", "Greater than order amount of 1.00" are all still
+ there, and `1.0.0` is refused -- round one's finding 2 stays fixed.
+* **The order-details page handles awkward goods.** A product with a real PNG,
+ one sold by the kilogram, one named in four scripts, one costing a cent and
+ one costing nothing all render with the right unit price and the right
+ total.
+* **The Bluetooth pairing wizard degrades.** With no display to find it asks
+ for nearby-device access, walks its steps, scans, stops, and offers "Search
+ again" -- no spinner, no stack trace.
+
+## The harness had to be rebuilt to see any of this
+
+Six screens were renamed or restructured, and each one failed in a way that
+reads like a defect rather than a rename:
+
+| what changed | what it looked like |
+| --- | --- |
+| the login form lays out its fields after its tab row | "no text field on screen at all", 11 scenarios out of 11 |
+| Settings moved the About rows into a lazy list, and the keyboard survives the move from the form | the terminal reported itself bound to no instance |
+| "Approve refund" became "Refund Taler" | five malformed refund amounts "refused in silence" |
+| "No instance?" became "No account?" | the demo-credentials button could not be found |
+| the checkout's compact layout says "Total: X" where the wide one says "Order total" | the checkout had no amounts on a phone |
+| sub-screens have a Back arrow where the drawer button is, and both are unlabelled in the dump | navigation pressed Back and then tapped whatever was underneath |
+
+And two bugs in the harness itself, both of which had been quietly inventing
+findings:
+
+* **`Screen.tap_target` skipped disabled clickables.** A label inside a
+ disabled button resolved to the nearest *enabled* neighbour -- for the
+ keypad's Charge button, a digit key three rows up -- so the caller read that
+ key's state and reported that charging nothing was allowed. It is not: the
+ button is correctly disabled, in this build and the last one.
+* **`tap_button` could not reach a control a lazy list had not composed yet**,
+ which is where Connect lives once the keyboard is up.
+* **`total_amount` is only in an *unpaid* order's status.** Once an order is
+ paid the figure moves to `contract_terms.amount`, so the check that the
+ wallet had been asked for four units rather than six read the correct order
+ as an order for nothing -- on the one scenario the whole feature exists
+ for. `_order_amount` now reads whichever field is there.
+* **A history entry has no `order_status`.** The same confusion one level
+ down: `GET /private/orders` returns `paid`, and asking those entries for
+ `order_status` made every one of them look unpaid. Between this and the
+ line above, *both* of the suite's "ask the backend what really happened"
+ checks were reading the wrong field of the right endpoint.
+
+## What was added
+
+* **A driver for the checkout**: payment options and their switches, the cash
+ keypad and its fraction shortcuts, the change dialog, the payment lines, and
+ abandoning a sale that already holds money.
+* **Fifteen scenarios**, over the checkout, payment options, the external
+ refund, the display-pairing wizard, and the login form's own geometry.
+* **`driver/inventory.py`**, which puts six deliberately awkward products on
+ the *demo* instance -- a real PNG, a description no column fits, a fraction
+ of a kilogram, four scripts and an emoji, one cent, and nothing at all. The
+ mock can answer anything, which is exactly why it cannot settle what the
+ order grid and the order-details page do with goods a merchant really sold:
+ the mock's products are never bought, never recorded in a contract and never
+ read back out of an order.
+
+## Coverage
+
+Against the terminal as it now is -- 11,821 lines where rounds one to three
+measured 4,864 -- after the round's own run:
+
+| | covered |
+| --- | --- |
+| instruction | 63,432 / 97,974 (**64.7%**) |
+| line | 7,827 / 11,821 (**66.2%**) |
+| branch | 2,453 / 5,294 (46.3%) |
+| method | 1,524 / 2,446 (62.3%) |
+| class | 242 / 318 (76.1%) |
+
+Reachable lines -- discounting the 205 in bodies a `sim` build cannot enter at
+all -- are **67.4%**, against a ceiling this report can never read above 98.3%.
+The run was 66 scenarios on the tablet worker (47 ok, 17 unreached, 2 harness
+errors) plus the mock set across two phones.
+
+The figure is not comparable with round three's 88.7% of reachable lines:
+that was a different, much smaller app. What it says is that two thirds of a
+terminal nobody had driven is now driven, and where the remaining third is:
+
+| package | covered | what is left |
+| --- | --- | --- |
+| `paymentoptions.sumup` | 19.4% | needs an affiliate key and a card reader |
+| `devices` | 37.7% | needs a Bluetooth or USB display to pair with |
+| `amount` | 50.0% | the compact-phone keypad arm |
+| `paymentoptions` | 58.2% | the card tiles, which need a provider |
+| `checkout` | 68.1% | the card dialog and pending-charge recovery |
+| `history` | 67.6% | the order-details page's delivery and reorder blocks |
+
+`devices` went 17.9% -> 37.7%, `checkout` 48.0% -> 68.1% and `refund`
+52.1% -> 79.1% over the round, on the back of the pairing-wizard, checkout and
+external-refund scenarios.
+
+## One thing left half-looked-at
+
+The terminal fetches the order history in the background, and when that fetch
+fails it raises a **modal** error dialog over whatever the cashier is doing --
+`payment_options_summary_counts` failed four times in a row at
+`Settings`, with
+
+```
+['Error fetching the order history', 'Server error (502)', 'OK']
+```
+
+on screen, in a scenario that never opened the history list. The message
+itself is fine; what is questionable is a background refresh the cashier did
+not ask for taking the whole screen. The demo backend was answering 502
+intermittently all evening under five emulators, which is what exposed it and
+also what makes it hard to say exactly when the dialog is raised -- so this is
+recorded rather than filed. A mock that answers 502 on `private/orders` and
+nothing else would settle it in one scenario.
+
+## Two the fault set turned up, both now answered
+
+Both were investigated after the round proper, one agent each. They came out
+opposite ways, which is the useful part.
+
+### A fifth defect, filed
+
+[Every failed delete says a wallet claimed the
+order](force-delete-blames-a-wallet.md) --
+[11977](https://bugs.gnunet.org/view?id=11977). `tryDeleteOrder` raises the
+force-delete prompt on *any* failure and throws the reason away, so a network
+error, a 5xx, an expired token and a 404 all tell the cashier "This order has
+been claimed by a wallet". The episode now records the backend saying
+`order_status='unpaid'` about the very order the dialog claims a wallet has
+taken. `HistoryManager.deleteOrder` has the same shape; the correct pattern,
+which asks `checkOrder` first, is twenty lines above it in the same file.
+
+The hypothesis this started from -- that the scenario's sustained twister
+mutation had corrupted the DELETE -- was **refuted**. The truth is blunter:
+`taler-twister` proxies PUT, POST and GET and closes the connection on
+anything else, so no DELETE has ever reached a backend through it. That is
+recorded in the finding, because it applies to every `fault_*` scenario that
+needs a delete to land.
+
+### An own goal, not a defect
+
+The "unreadable order reply leaves two orders behind" finding was mine. Only
+one of the two orders came from the device under test: Cash was not enabled in
+that run, so the checkout never engaged, the legacy path ran, and the scenario
+contains exactly one `POST /private/orders`. The other, `pos-4438f610-...`,
+belonged to **another worker** on the same shared instance -- and it was
+*paid*.
+
+Two harness bugs, both now fixed:
+
+* `unpaid = [o for o in fresh if o.get("order_status") != "paid"]` asks a
+ history entry for a field it does not have. `GET /private/orders` returns
+ `paid`; `order_status` belongs to `GET /private/orders/{id}`. The key is
+ absent, so `!= "paid"` was true of every order, paid ones included. This is
+ the same mistake as the `total_amount` one, in the same direction: reading a
+ field of the per-order endpoint off a list entry.
+* `EXCLUSIVE_DEMO` -- the guard that exists to suppress exactly this count --
+ was never set. `suite.py` said "the campaign sets it"; `campaign.py` set
+ only `POS_WORKER` and `POS_MOCK_PORT`. It is set now, and only for the one
+ worker that owns the demo plan.
+
+A re-run while the other agent was working made it vivid: one device `POST`,
+**four** accused orders, two of them carrying a summary that exists nowhere in
+this tree.
+
+## What is left
+
+1. **`devices/` is 17.9% covered**, and most of the rest needs hardware: a
+ Bluetooth display to pair with, a USB one to enumerate. The wizard is
+ walked as far as a scan that finds nothing.
+2. **SumUp is 19.4%**, and the build has no affiliate key, so the option
+ reports "Setup is unavailable in this build" and its whole charge path is
+ out of reach. A key would open roughly 1,500 lines.
+3. **The `mock` backend does not speak protocol 42**, so every checkout
+ scenario needs the real demo instance and they cannot be parallelised.
+ Teaching `mockd.py` the mixed-payment endpoints -- `collect`,
+ `refund-external` -- would move the whole set onto workers of their own.
+4. **Three controls on the tablet's custom-product dialog and two on its
+ history screen have no accessible name.** Round one's finding 9 was fixed
+ for the controls that existed then; these are new.
diff --git a/pos-simulator/findings/STATUS.md b/pos-simulator/findings/STATUS.md
@@ -0,0 +1,65 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# Where the findings stand
+
+Checked on 2026-11-08 against `origin/master`, after rebasing this branch onto
+it. **All twelve are fixed.** Nothing from rounds one to three is still open,
+so nothing was filed on `bugs.gnunet.org`.
+
+Every fix arrived in one squashed commit, `24f7b249 [pos] add support for mixed
+payments and UI changes`, and eleven of the twelve are now pinned by a unit
+test that names the exact case the simulator found. Those tests pass on this
+branch: `:merchant-terminal:testSimUnitTest`,
+`:taler-kotlin-android:testDebugUnitTest` and `:merchant-lib:test` are all
+green.
+
+| | Finding | How it is fixed | Pinned by |
+| --- | --- | --- | --- |
+| 1 | [QR tab crashes on the first camera frame](qr-config-tab-crashes-the-terminal.md) | `config/QrLuminance.kt` is new: it honours `rowStride`/`pixelStride` and rotates by writing to the destination index, so nothing calls `PlanarYUVLuminanceSource.rotateCounterClockwise` any more | `QrLuminanceTest` -- padded interleaved frames at all four rotations, plus a truncated-plane case |
+| 2 | [A refund of `1.000.50` settles at 1](refund-amount-swallows-extra-decimal-points.md) | `Amount.fromString` now throws on a second separator: `if (valueSplit.size > 2) throw AmountParserException(...)`, and `isValidAmountStr` agrees | `AmountTest.rejectsExtraDecimalSeparators`, whose list begins `"1.0.0", "1.000.50"` |
+| 3 | [A fresh instance cannot be used](fresh-instance-cannot-be-used.md) | `OrderManager.applyConfiguration` synthesises the "all products" and "uncategorized" categories and returns `null` unconditionally; an empty grid says `order_empty_inventory` instead of refusing the configuration | `ConfigRequestsTest.empty inventory loads and persists through the real unescaped endpoint` |
+| 4 | [An expired session shows a protocol error](expired-session-shows-a-protocol-error.md) | `ConfigManager.handleUnauthorized` fires `sessionExpired` only for the active merchant's own private requests; `MainActivity` observes it and shows `session_expired_toast` | `ConfigSessionTest`, three cases including `real session rejection clears credentials and is consumed once` |
+| 5 | [A silent backend hangs the login forever](login-hangs-forever-on-a-silent-backend.md) | the Ktor client now sets `requestTimeoutMillis`/`socketTimeoutMillis` to 30 s and `connectTimeoutMillis` to 15 s | `ConfigRequestsTest.unresponsive configuration times out with a network error and can be retried` |
+| 6 | [The terminal asks for `/private%2Fpos`](pos-config-url-percent-encodes-the-separator.md) | the URL is built one segment at a time (`.appendPath("private")`), so the separator is not encoded | `ConfigRequestsTest` asserts the server saw `"/instances/test/private/pos"` |
+| 7 | [A setup URI loses the backend's port](setup-uri-drops-the-port.md) | `merchantSetupConfig` keeps it: `val authority = if (data.port == -1) host else "$host:${data.port}"` | `MerchantSetupUriTest.setup links preserve custom ports and both credential formats` |
+| 8 | [A failed config fetch strands the spinner](config-fetch-failure-strands-the-spinner.md) | the spinner is its own `ConfigFetcherFragment` with a Cancel button and an error branch | `ConfigRequestsTest.configuration cancellation stops pending requests...` |
+| 9 | [Controls a screen reader cannot announce](controls-without-accessible-names.md) | all three now have names: the drawer button `navigation_menu_open`, the password toggle `password_show`/`password_hide`, and the checkbox row carries `Role.Checkbox` with `onCheckedChange = null` on the box itself | source only |
+| 10 | [A cut connection is reported in OkHttp's words](transport-error-shows-the-library-wording.md) | `is IOException -> NETWORK_ERROR_MESSAGE`, with no `exception.message` fallback | `ResponseCancellationTest` asserts the message is "Network error: check your internet connection and merchant URL." |
+| 11 | [A missing field is reported by its Kotlin type name](serialization-error-shown-to-the-cashier.md) | `is SerializationException, is ContentConvertException -> "The merchant server returned an invalid response. Please try again."`, and the `else` arm no longer quotes the exception either | `ResponseCancellationTest` feeds it `SerializationException("Field amount is required for type net.taler.internal.Type")` |
+| 12 | [A form loses its buttons to the keyboard on a phone](refund-form-unusable-on-a-phone.md) | `RefundFragment` scrolls: `.imePadding().verticalScroll(rememberScrollState())` | source only |
+
+## The tracker
+
+`bugs.gnunet.org` has one open issue in `merchant-pos-terminal (Android App)` --
+11908, "POS apps lacks persistant db inside of the app" -- which is not any of
+these. The three others in that category are closed: 10210 ("Session expired
+closes application", closed *fixed*, and the closest neighbour to finding 4),
+8652 and 9207.
+
+One caution for whoever searches next: `status=open` is accepted by
+`GET /api/ai/issues` but does **not** filter -- the three closed issues above
+came back from a query asking for open ones. Check each issue's own `status`.
+
+## What this does not say
+
+The twelve were checked by reading `origin/master` and by running its unit
+tests, not by driving the app. The simulator's own environment was gone when
+this was written -- `tripwire` had rebooted and `/tmp/taler-pos-sim` with it --
+so there is no fresh emulator run behind this table. For the eleven with a
+regression test naming the exact input, that is not much of a gap. For 9 and 12,
+which are layout and accessibility properties that a unit test cannot hold,
+a round four should confirm them on a device.
diff --git a/pos-simulator/findings/cash-keypad-submit-is-cut-off.diff b/pos-simulator/findings/cash-keypad-submit-is-cut-off.diff
@@ -0,0 +1,44 @@
+diff --git a/merchant-terminal/src/main/java/net/taler/merchantpos/checkout/CheckoutAmountEntry.kt b/merchant-terminal/src/main/java/net/taler/merchantpos/checkout/CheckoutAmountEntry.kt
+index a22c8c34..994b6507 100644
+--- a/merchant-terminal/src/main/java/net/taler/merchantpos/checkout/CheckoutAmountEntry.kt
++++ b/merchant-terminal/src/main/java/net/taler/merchantpos/checkout/CheckoutAmountEntry.kt
+@@ -244,16 +244,35 @@ internal fun CheckoutAmountEntry(
+
+ isLandscape ->
+ {
++ // The keypad is a fixed stack: four rows of keys, a gap,
++ // and the submit button. At 48 dp a key that is 280 dp
++ // tall, and a phone in landscape leaves about 300 dp once
++ // the title row and this padding are taken off -- so the
++ // submit button, which carries the amount about to be
++ // recorded, was drawn half off the bottom of the screen
++ // with no way to scroll to it. The keys give way first,
++ // and the column scrolls as a backstop, which is what
++ // every other branch here already does.
++ val keyGap = 8.dp
++ val actionGap = 16.dp
++ val submitHeight = 48.dp
++ val keyHeight =
++ ((maxHeight - 40.dp - keyGap * 3 - actionGap - submitHeight) / 4)
++ .coerceIn(36.dp, 48.dp)
+ Row(
+ modifier = Modifier.fillMaxSize().padding(horizontal = 24.dp, vertical = 20.dp),
+ horizontalArrangement = Arrangement.spacedBy(36.dp),
+ verticalAlignment = Alignment.Top,
+ ) {
+ CheckoutNumberPad(
+- modifier = Modifier.weight(0.59f),
+- keyHeight = 48.dp,
+- keyGap = 8.dp,
+- actionGap = 16.dp,
++ modifier =
++ Modifier
++ .weight(0.59f)
++ .fillMaxHeight()
++ .verticalScroll(rememberScrollState()),
++ keyHeight = keyHeight,
++ keyGap = keyGap,
++ actionGap = actionGap,
+ submitLabel = submitLabel,
+ enabled = submitEnabled,
+ onDigit = onDigit,
diff --git a/pos-simulator/findings/cash-keypad-submit-is-cut-off.md b/pos-simulator/findings/cash-keypad-submit-is-cut-off.md
@@ -0,0 +1,135 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# On a phone, the cash keypad's own button is cut in half
+
+Take a cash payment on a phone-sized screen and the button that records it is
+drawn half off the bottom edge:
+
+
+
+That blue bar is **"Record ク10.00 cash"**, sliced through the middle of its
+text. It is the primary action of the screen, it is the only place the amount
+about to be recorded is spelled out in words, and the column it sits in does
+not scroll -- so there is no way to see the rest of it. The visible half can
+be tapped, which is the only reason this is not a dead end.
+
+Two things make it worse than a cosmetic clip:
+
+* The button carries **the amount**. A cashier about to record a cash payment
+ is being asked to confirm a number they cannot fully read.
+* The line that says **"Change to return: ク3.00"** is below the fold in the
+ right-hand column. Ten was handed over for a seven-unit bill and nothing on
+ the visible screen says that three goes back. That column *is* scrollable,
+ so the line can be reached -- but nothing suggests it is there.
+
+## Why it happens
+
+`merchant-terminal/src/main/java/net/taler/merchantpos/checkout/CheckoutAmountEntry.kt`
+lays this screen out four ways. Three of them wrap their content in a
+`verticalScroll`. The phone-in-landscape branch is the one that does not:
+
+```kotlin
+isLandscape ->
+{
+ Row(
+ modifier = Modifier.fillMaxSize().padding(horizontal = 24.dp, vertical = 20.dp),
+ horizontalArrangement = Arrangement.spacedBy(36.dp),
+ verticalAlignment = Alignment.Top,
+ ) {
+ CheckoutNumberPad(
+ modifier = Modifier.weight(0.59f), // <- no scroll, fixed heights
+ keyHeight = 48.dp,
+ keyGap = 8.dp,
+ actionGap = 16.dp,
+ …
+ )
+ Column(Modifier.weight(0.41f).fillMaxHeight().verticalScroll(rememberScrollState())) {
+ AmountSummary(…) // <- this half does scroll
+ }
+ }
+}
+```
+
+The keypad is a fixed stack and its height is arithmetic, not layout: four key
+rows at 48 dp, three 8 dp gaps, a 16 dp action gap and a 48 dp button, which
+is 280 dp, plus 40 dp of vertical padding -- 320 dp. A 1920x1080 phone at
+420 dpi is 411 dp high in landscape; the title row takes 64 dp and the status
+bar some more, leaving about 300 dp inside the `BoxWithConstraints`. The last
+20 dp of the button are simply past the edge, and since the column does not
+scroll they stay there.
+
+The tablet-landscape branch above it uses the same 48 dp keys and gets away
+with it, because a tablet is 800 dp high. Nothing in the phone branch
+recomputes the key size for a screen a third as tall.
+
+## How it was found
+
+`checkout_cash_change_is_right` passes on a tablet. The same walk on a
+phone-sized worker reads the submit button at bounds `(392, 877, 737, 950)`
+in a window `954` pixels high, with no scrollable ancestor -- a control
+hanging over the bottom edge of the screen it is drawn on, which is the shape
+the harness photographs rather than reports as a label it could not find.
+
+## Severity
+
+Medium. Nothing is lost and the sale can be completed: the top half of the
+button takes a tap. But the one screen in the app where a cashier counts money
+out of a till is the one that hides the amount and the change, and it does it
+on every phone-sized device, every time.
+
+## Suggested fix
+
+`cash-keypad-submit-is-cut-off.diff`, verified on the emulator the screenshot
+came from. The key height is derived from the height actually available
+rather than fixed at 48 dp, and the column is given the same `verticalScroll`
+the other three branches already have as a backstop:
+
+```kotlin
+val keyHeight =
+ ((maxHeight - 40.dp - keyGap * 3 - actionGap - submitHeight) / 4)
+ .coerceIn(36.dp, 48.dp)
+…
+CheckoutNumberPad(
+ modifier = Modifier
+ .weight(0.59f)
+ .fillMaxHeight()
+ .verticalScroll(rememberScrollState()),
+ keyHeight = keyHeight,
+ …
+)
+```
+
+With it the button lands at `(392, 877, 737, 930)` -- inside the window, with
+its label whole. The keys lose a few dp, which is invisible beside a button
+that was not there.
+
+Not in the patch, because it is a judgement rather than a defect: **"Change to
+return"** still starts below the fold on the right. Moving it above the
+fraction shortcuts, or showing it beside the entered amount, would put the
+number a cashier needs where they are already looking.
+
+## Reproducer
+
+```bash
+POS_AVD_DEVICE=medium_phone POS_LCD_WIDTH=1920 POS_LCD_HEIGHT=1080 \
+ POS_LCD_DENSITY=420 emu/emu.sh create 4
+emu/emu.sh boot 4 && emu/emu.sh prepare 4
+POS_WORKER=4 python3 driver/suite.py checkout_cash_change_is_right
+```
+
+Turn Cash on in Settings -> Manage payment options first; the checkout does
+not exist while Taler is the only payment option.
diff --git a/pos-simulator/findings/config-fetch-failure-strands-the-spinner.md b/pos-simulator/findings/config-fetch-failure-strands-the-spinner.md
@@ -0,0 +1,108 @@
+# A failed configuration fetch leaves the terminal on its spinner for good
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+**Severity:** medium -- the terminal is stranded on a screen that says it is
+working, after it has already been told it is not. The only way on is to guess
+that the back button does something.
+
+**Where:**
+`merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFetcherFragment.kt`.
+
+**Found by:** `pos-simulator`, scenario `provision_setup_uri_malformed`, with a
+setup URI that names no host.
+
+## What happens
+
+Deliver a `taler-pos://` setup URI with an empty host:
+
+```
+taler-pos:///instances/sandbox#secret-token:V69RBF5QCYC1GQZ...
+```
+
+The terminal accepts it, navigates to its "Fetching configuration…" screen,
+fails, and says so:
+
+```
+'Taler POS': 'Error: The configuration JSON is malformed' ['OK']
+```
+
+Dismiss that, and the spinner is still there. It stays there. The scenario
+waits twelve seconds and then records
+`stuck-fetching-after-bad-uri: a setup URI with no host left the terminal
+fetching configuration forever`; by hand it is still spinning minutes later.
+
+## Why
+
+`ConfigFetcherFragment` navigates on success and only on success:
+
+```kotlin
+configManager.configUpdateResult.observe(viewLifecycleOwner) { result ->
+ when (result) {
+ null -> return@observe
+ is ConfigUpdateResult.Error -> {
+ requireActivity().showPosError(result.msg) // and nothing else
+ }
+ is ConfigUpdateResult.Success -> {
+ if (!navigating) {
+ navigating = true
+ (requireActivity() as MainActivity).navigateToInitialOrderScreen()
+ }
+ }
+ }
+}
+```
+
+The error branch shows a dialog and leaves the fragment where it is. The screen
+behind the dialog is a `CircularProgressIndicator` and the words "Fetching
+configuration…", which is now a lie: nothing is being fetched and nothing will
+be.
+
+Back does get out of it -- `handleExitRequest` falls through to
+`navigateBack()`, which pops to whatever was underneath -- but nothing on
+screen says so, and on a first run there may be nothing underneath, in which
+case `navigateBack` calls `finish()` and the app closes.
+
+## The second half: the URI should not have been accepted
+
+`MainActivity.handleSetupIntent` guards on `data.host ?: return`, which does
+not catch this: `Uri.parse("taler-pos:///instances/sandbox#token").host` is the
+empty string, not null. So the terminal builds `https:///instances/sandbox`,
+asks for it, and gets a failure it then mis-describes as malformed JSON --
+`ConfigManager.fetchConfig` uses `config_error_malformed` as the catch-all for
+every exception that is not a `ClientRequestException`.
+
+Eight other malformed setup URIs in the same scenario -- no token, no instance,
+an empty instance, a blank token, the wrong scheme, and three shapes of
+`#username=&password=` -- are all correctly ignored, leaving the login form
+usable. The empty host is the one that gets through.
+
+## Reproducing it
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 suite.py provision_setup_uri_malformed
+```
+
+or by hand:
+
+```bash
+adb shell am start -a android.intent.action.VIEW \
+ -d 'taler-pos:///instances/sandbox#secret-token:anything' \
+ -n net.taler.merchantpos/.MainActivity
+```
+
+## The fix
+
+Two independent changes, neither of which is a one-liner, so no patch:
+
+* `ConfigFetcherFragment` should leave the fetching screen when the fetch
+ fails -- back to the configuration screen, which is where the user can do
+ something about it. `MainActivity.onStart` already routes an invalid config
+ there, so the destination exists.
+* `handleSetupIntent` should reject an empty host as well as a null one, and
+ `ConfigManager`'s catch-all deserves a second look while someone is in
+ there: "The configuration JSON is malformed" is what the terminal says about
+ a hostname it cannot resolve, a TLS failure and a genuinely malformed reply
+ alike. See `pos-config-url-percent-encodes-the-separator.md` for the other
+ thing in that method.
diff --git a/pos-simulator/findings/controls-without-accessible-names.md b/pos-simulator/findings/controls-without-accessible-names.md
@@ -0,0 +1,79 @@
+# Controls a screen reader cannot announce
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+**Severity:** low individually, and an accessibility bug collectively: a
+cashier using TalkBack cannot tell these controls apart from each other.
+
+**Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/` --
+`config/ConfigFragment.kt` (the password-visibility toggle), `MainActivity.kt`
+(the navigation-drawer button) and the "Remember password" checkbox on the
+login form.
+
+**Found by:** `pos-simulator`, the `unnamed-control` oracle, which fires on
+every screen the suite visits.
+
+## What happens
+
+Three clickable controls publish no text and no content description, and
+contain no labelled node for the framework to borrow one from, so TalkBack
+announces each of them as an unlabelled button:
+
+| Screen | Control | Position in a 2560x1600 window |
+| --- | --- | --- |
+| login (manual) | the eye icon that reveals the password | (2472, 800) |
+| login (manual) | the "Remember password" checkbox | (88, 936) |
+| every screen with a top bar | the navigation-drawer button | (64, 112) |
+
+The drawer button is the one that matters most: it is the only way to reach the
+history, the settings and the other order screen, and it is announced as
+nothing at all.
+
+The checkbox is a subtler case. Its label *is* on screen -- "Remember
+password" sits next to it -- but as a sibling rather than inside it, so the
+semantics do not merge and the two are announced separately: a piece of text,
+and an unlabelled checkbox. A sighted user reads them as one control; a screen
+reader does not.
+
+## Why
+
+Each is an `IconButton` or a `Checkbox` whose content has
+`contentDescription = null`:
+
+```kotlin
+// ConfigFragment.kt, the password field's trailing icon
+IconButton(onClick = { passwordVisible = !passwordVisible }) {
+ Icon(imageVector = ..., contentDescription = null)
+}
+
+// MainActivity.kt, in each of the three top-bar variants
+IconButton(onClick = { scope.launch { drawerState.open() } }) {
+ Icon(Icons.Default.Menu, contentDescription = null)
+}
+```
+
+`contentDescription = null` is the right thing for an icon that is decoration
+beside a label. It is wrong for an icon that *is* the control.
+
+## Reproducing it
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 probe.py # on any screen; unnamed controls are listed
+python3 suite.py accessibility_names
+```
+
+`probe.py` prints a trailing section for every clickable node with no
+accessible name, which is the same check the oracle runs.
+
+## The fix
+
+A `contentDescription` on each icon, from a string resource -- `menu_order`,
+`config_password` and friends already exist, so this is three strings and three
+lines. For the checkbox, the fix is to put the label inside the clickable
+instead: wrap the row in `Modifier.toggleable(...)` with the `Text` inside it,
+so the semantics merge and the whole row is one announced control with one tap
+target.
+
+No patch here: the strings have to be written and translated, which is not a
+mechanical change.
diff --git a/pos-simulator/findings/expired-session-shows-a-protocol-error.md b/pos-simulator/findings/expired-session-shows-a-protocol-error.md
@@ -0,0 +1,93 @@
+# An expired session shows a protocol error instead of asking for credentials
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+**Severity:** medium -- the terminal has the right behaviour implemented and it
+does not run. A cashier whose session has ended sees an error mentioning an
+`Authorization` header, and is left on a screen that cannot do anything.
+
+**Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/MainViewModel.kt`,
+the response-pipeline interceptor.
+
+**Found by:** `pos-simulator`, scenario `token_expires_while_idle`, using a
+75-second access token -- a credential the terminal cannot ask for itself,
+since the login form hard-codes `TokenDuration.Forever`.
+
+## What happens
+
+Provision the terminal with a short-lived token, wait for it to expire, and
+refresh the order history. What should happen is the "Session expired – please
+re-enter your credentials" toast and a return to the login screen. What happens
+is a dialog:
+
+```
+Error fetching the order history
+Error 2015 (401): The merchant refused the request due to lack of
+authorization. - Check credentials in 'Authorization' header
+OK
+```
+
+and the terminal stays on the history screen, which can no longer load
+anything. The string is the backend's own hint, in English regardless of the
+app's language, and it names an HTTP header.
+
+## Why
+
+The handling exists:
+
+```kotlin
+// MainViewModel
+httpClient.responsePipeline.intercept(HttpResponsePipeline.Transform) { (info, body) ->
+ if (context.response.status == HttpStatusCode.Unauthorized &&
+ configManager.merchantConfig != null) {
+ configManager.forgetPassword()
+ configManager.notifySessionExpired()
+ }
+ proceedWith(subject)
+}
+```
+
+and `MainActivity` observes `sessionExpired`, shows the toast and navigates to
+the configuration screen. The `session_expired_toast` string is translated into
+every language the app ships.
+
+It does not fire. The same client is built with `expectSuccess = true`
+(`createDefaultHttpClient`), which installs Ktor's default response validator;
+a 401 therefore raises `ClientRequestException` before the response pipeline's
+`Transform` phase runs, so the interceptor never sees the status. The exception
+is caught instead by `MerchantApi`'s `response { }` wrapper and surfaced as an
+ordinary failure string, which is what reaches the dialog.
+
+That it is caught there is not in doubt -- the message in the dialog is the
+backend's 401 body, which only `MerchantApi`'s error path formats.
+
+## Reproducing it
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 suite.py token_expires_while_idle
+```
+
+The scenario mints a 75-second token through the merchant API, provisions the
+terminal with it as a `taler-pos://` setup URI, waits it out and then asks the
+terminal to do something. `token_revoked_mid_payment` is the same question with
+the credential pulled at a moment of the harness's choosing.
+
+## The fix
+
+The status has to be inspected somewhere the validator has not already thrown.
+Two options, neither of which is a one-liner, which is why no patch is
+attached:
+
+* **`HttpResponseValidator { handleResponseExceptionWithRequest { cause, _ -> … } }`**
+ on the same client: the exception carries the response, so the 401 can be
+ recognised there and `notifySessionExpired()` called before rethrowing. This
+ keeps the single-place handling the current code was aiming at.
+* **In `MerchantApi`'s failure path**, which already distinguishes error
+ shapes; it would have to be given a way to tell `ConfigManager`, which it
+ currently has no reference to.
+
+Whichever is chosen, it is worth checking that it fires for every caller:
+`PaymentManager.checkPayment` deliberately swallows network errors to keep
+polling, so a session that ends while the payment screen is open must not end
+up silently retrying forever against a credential that no longer works.
diff --git a/pos-simulator/findings/force-delete-blames-a-wallet.diff b/pos-simulator/findings/force-delete-blames-a-wallet.diff
@@ -0,0 +1,79 @@
+diff --git a/merchant-lib/src/main/java/net/taler/merchantlib/Response.kt b/merchant-lib/src/main/java/net/taler/merchantlib/Response.kt
+index b91e0723..c49eb345 100644
+--- a/merchant-lib/src/main/java/net/taler/merchantlib/Response.kt
++++ b/merchant-lib/src/main/java/net/taler/merchantlib/Response.kt
+@@ -56,6 +56,15 @@ class Response<out T> private constructor(
+
+ val isFailure: Boolean get() = value is Failure
+
++ /**
++ * The HTTP status the backend answered with, or null when the request never
++ * got an answer at all (a network error) or succeeded. Callers that have to
++ * tell one kind of failure from another need this: the message cannot.
++ */
++ val statusCode: Int?
++ get() = ((value as? Failure)?.exception as? ResponseException)
++ ?.response?.status?.value
++
+ suspend fun handle(onFailure: ((String) -> Unit)? = null, onSuccess: ((T) -> Unit)? = null) {
+ if (value is Failure) onFailure?.let { it(getFailureString(value)) }
+ else onSuccess?.let {
+diff --git a/merchant-terminal/src/main/java/net/taler/merchantpos/history/HistoryManager.kt b/merchant-terminal/src/main/java/net/taler/merchantpos/history/HistoryManager.kt
+index 1b8e27a2..41ac8c44 100644
+--- a/merchant-terminal/src/main/java/net/taler/merchantpos/history/HistoryManager.kt
++++ b/merchant-terminal/src/main/java/net/taler/merchantpos/history/HistoryManager.kt
+@@ -233,11 +233,22 @@ class HistoryManager(
+ mIsLoading.value = true
+ mIsLoadingMore.value = false
+ val merchantConfig = configManager.merchantConfig!!
+- api.deleteOrder(merchantConfig, orderId).handle(
+- { _ ->
++ val result = api.deleteOrder(merchantConfig, orderId)
++ // Same as on the payment screen: only a 409 is a claim that force can
++ // override, so only a 409 may raise the force-delete prompt.
++ val needsForce = result.statusCode == 409
++ result.handle(
++ { errorMsg ->
+ assertUiThread()
+ mIsLoading.value = false
+- mForceDeleteOrderId.value = orderId
++ if (needsForce)
++ {
++ mForceDeleteOrderId.value = orderId
++ }
++ else
++ {
++ onError(R.string.error_delete_order, errorMsg)
++ }
+ }
+ ) {
+ assertUiThread()
+diff --git a/merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt b/merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt
+index 91672e4f..9934d9c5 100644
+--- a/merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt
++++ b/merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt
+@@ -402,10 +402,23 @@ class PaymentManager(
+ val orderId = mPayment.value?.orderId ?: return
+ scope.launch {
+ val result = api.deleteOrder(merchantConfig, orderId)
++ // Only a 409 is the backend refusing because the order is claimed or
++ // already paid. Every other failure -- no network, a 5xx, an expired
++ // token -- is a failure of the request itself, which force cannot fix
++ // and which must not be reported to the cashier as a wallet's claim.
++ val needsForce = result.statusCode == 409
+ result.handle(
+ onFailure = { errorStr ->
+ Log.w(TAG, "Delete order $orderId failed: $errorStr")
+- mDeleteNeedsForce.postValue(true)
++ if (needsForce)
++ {
++ mDeleteNeedsForce.postValue(true)
++ }
++ else
++ {
++ mPayment.postValue(mPayment.value?.copy(error = errorStr))
++ mDeleteNeedsForce.postValue(null)
++ }
+ },
+ onSuccess = {
+ Log.d(TAG, "Delete order $orderId succeeded")
diff --git a/pos-simulator/findings/force-delete-blames-a-wallet.md b/pos-simulator/findings/force-delete-blames-a-wallet.md
@@ -0,0 +1,161 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# Every failed delete says a wallet claimed the order
+
+Cancel an order, have the DELETE fail for any reason at all, and the terminal
+tells the cashier this:
+
+
+
+```
+Force delete order?
+This order has been claimed by a wallet. Force deleting it will release any
+inventory locks and prevent the wallet from completing the payment.
+[Cancel payment] [Force delete]
+```
+
+No wallet had claimed it. The episode records the dialog and the backend's own
+view of the same order, seconds apart:
+
+```
+order on screen: 2026.313-ZHY9Z0163KAHM
+backend on 2026.313-ZHY9Z0163KAHM: order_status='unpaid'
+after cancelling: Force delete order? | This order has been claimed by a wallet. ...
+```
+
+The order was never claimed and was still there afterwards: "Cancel order"
+left a live order behind while telling the cashier a wallet had taken it.
+
+## Why it happens
+
+`payment/PaymentManager.kt`, `tryDeleteOrder()`:
+
+```kotlin
+val result = api.deleteOrder(merchantConfig, orderId)
+result.handle(
+ onFailure = { errorStr ->
+ Log.w(TAG, "Delete order $orderId failed: $errorStr")
+ mDeleteNeedsForce.postValue(true) // <- every failure
+ },
+```
+
+The reason is logged and thrown away. `ProcessPaymentFragment` turns the flag
+straight into the dialog, whose message is `force_delete_dialog_message`. So a
+network error, a 5xx, an expired token and a 404 are all reported as a claim.
+
+`history/HistoryManager.kt`, `deleteOrder()`, has the same shape and does not
+even bind the error:
+
+```kotlin
+api.deleteOrder(merchantConfig, orderId).handle(
+ { _ ->
+ assertUiThread()
+ mIsLoading.value = false
+ mForceDeleteOrderId.value = orderId // <- every failure
+ }
+```
+
+The backend distinguishes these: 404 for an unknown order, 409 for
+already-paid, awaiting-payment (the claim) and externally-paid. Only a 409 is
+a refusal `force` can override.
+
+**The correct pattern is twenty lines above the second one.**
+`HistoryManager.deleteConfirmedOrder()` asks first and derives `force` from
+the answer:
+
+```kotlin
+api.checkOrder(config, item.orderId).handle({ error = it }) { current = it }
+…
+val force =
+ checked is CheckPaymentResponse.Claimed ||
+ (checked.paymentDetails?.amountExternal?.isNotEmpty() ?: item.hasExternalPayments)
+```
+
+## Severity
+
+Medium to high, and it is wrong information rather than a cosmetic slip. A
+till on shop Wi-Fi loses its backend routinely; an expired token and a 502 are
+ordinary. In every one of those cases a cashier standing in front of a
+customer is told a wallet may be paying, so cancelling might strand a payment
+— and the one fact the decision rests on is untrue.
+
+It does not end there. Pressing **Force delete** sends the same request over
+the same broken transport, reports failure only to `Log.w`, and navigates back
+regardless: no error, and the order survives. Pressing **Cancel payment**
+returns to the payment screen with no message at all.
+
+## How it was found
+
+`fault_insecure_pay_uri_cancel` takes the "Cancel order" branch of the
+insecure-pay-URI dialog. The delete fails there for an incidental reason —
+see the harness note below — but the defect is independent of it: the terminal
+never looks at *why*.
+
+Three consecutive reproductions, same screen each time. The scenario now
+records the order id and asks the backend about it, so the contradiction is in
+the artifact rather than in somebody's memory.
+
+## Suggested fix
+
+`force-delete-blames-a-wallet.diff`, verified on the emulator. `Response`
+gains the status code it already holds but does not expose, and the force
+prompt is raised only on 409:
+
+```kotlin
+val statusCode: Int?
+ get() = ((value as? Failure)?.exception as? ResponseException)
+ ?.response?.status?.value
+…
+val needsForce = result.statusCode == 409
+```
+
+with the other branch surfacing the real error — through `mPayment.error` on
+the payment screen, through the existing `error_delete_order` string in the
+history list.
+
+After the patch the same sequence says:
+
+```
+Error: No payment received | Network error: check your internet connection
+and merchant URL. | OK
+```
+
+and the backend still reports that order `unpaid`, which is the truth.
+`:merchant-terminal:testSimUnitTest` and `:merchant-lib:test` pass.
+
+Left out of the patch because they want a decision rather than a fix:
+409/2521 (`ALREADY_PAID`) and 409/2537 (`EXTERNALLY_PAID`) also reach the
+"claimed by a wallet" wording, so the message could be split by error code;
+and `forceDeleteOrder` should report its own failure instead of navigating
+back on hope.
+
+Filed as [11977](https://bugs.gnunet.org/view?id=11977).
+
+## A harness note that matters for every `fault_*` scenario
+
+**`taler-twister` cannot proxy DELETE.** `taler-twister-service.c` handles
+PUT, POST and GET and answers anything else with
+
+```
+WARNING Unsupported HTTP method `DELETE'
+```
+
+closing the connection without a reply. So a DELETE through twister always
+fails, armed or not — which is what made this path fail, and which means
+`fault_insecure_pay_uri_cancel` can never observe a *successful* cancel. Any
+fault scenario that needs a delete to reach the backend is in the same
+position.
diff --git a/pos-simulator/findings/fresh-instance-cannot-be-used.md b/pos-simulator/findings/fresh-instance-cannot-be-used.md
@@ -0,0 +1,98 @@
+# A freshly provisioned merchant instance cannot be used at all
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+**Severity:** high for a new user -- it is the first thing a merchant who has
+just created an instance will see, and what they see is "Error: No valid
+product category found" and a return to the login screen. There is nothing in
+the message that tells them to go and add a product, and nothing they can do
+in the terminal to get past it.
+
+**Where:**
+`merchant-terminal/src/main/java/net/taler/merchantpos/order/OrderManager.kt`
+(the category check) and
+`merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigManager.kt`
+(`onMerchantConfigReceived`, which treats any receiver's complaint as a
+configuration failure).
+
+**Found by:** `pos-simulator`, scenario `fresh_instance_no_inventory`, against
+`backend/mockd.py --profile fresh`.
+
+## What happens
+
+Point the terminal at an instance whose `/private/pos` answers
+
+```json
+{"categories": [], "products": []}
+```
+
+which is what a self-provisioned instance answers until somebody adds a
+product. The terminal fetches it, refuses it, and goes back to the login
+screen:
+
+```
+dialog: 'Taler POS': 'Error: No valid product category found' ['OK']
+```
+
+The terminal has two order screens, and only one of them needs an inventory.
+"Order by amount" is a keypad: a cashier types a price and bills it, and no
+product is involved at any point. It is also the default -- `InitialOrderScreen`
+starts as `AmountEntry`. But the configuration never finishes, so neither
+screen is reached.
+
+## Why
+
+`ConfigManager.onMerchantConfigReceived` hands the fetched configuration to
+every registered `ConfigurationReceiver` and aborts on the first one that
+objects:
+
+```kotlin
+for (receiver in configurationReceivers) {
+ val result = try { receiver.onConfigurationReceived(...) } catch (e: Exception) { ... }
+ if (result != null) { // error
+ if (!silent) mConfigUpdateResult.postValue(ConfigUpdateResult.Error(result))
+ return
+ }
+}
+```
+
+The only receiver is `OrderManager`, which objects when there are no usable
+categories -- reasonably, from its own point of view: it is the inventory
+screen's model and it has no inventory to show. But its objection becomes the
+whole app's configuration failure, including for the screens that do not depend
+on it.
+
+Note that `merchantConfig`, `currency` and `currencySpec` are assigned *after*
+that loop, so a refusal also leaves the terminal with no currency -- which is
+why there is no way to carry on in a degraded mode from where it stops.
+
+## Reproducing it
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 ../findings/repro_fresh_instance_unusable.py
+```
+
+Against a real backend: self-provision an instance, add no products, and log
+the terminal in to it.
+
+## What a fix has to decide
+
+This one needs a product decision, so no patch is included.
+
+The narrow reading is that an instance with no products should still configure,
+with the inventory screen showing an empty state and "Order by amount"
+working -- which means `OrderManager` returning `null` for an empty inventory
+rather than an error, and the inventory screen gaining an empty state. That
+also makes the error message honest again: `config_error_category` would then
+mean what it says, "a product references a category that does not exist",
+rather than doubling as "this instance is new".
+
+The wider reading is that a receiver's objection should not be the app's
+objection: `ConfigManager` could record it, finish the configuration, and let
+each screen decide whether it can work. That is the better shape but a larger
+change.
+
+Either way the message wants rewording: "No valid product category found" is
+about the terminal's data model, and the person reading it is a merchant who
+has not added a product yet.
diff --git a/pos-simulator/findings/images/cash-keypad-on-a-phone.png b/pos-simulator/findings/images/cash-keypad-on-a-phone.png
Binary files differ.
diff --git a/pos-simulator/findings/images/custom-product-dialog-on-a-phone.png b/pos-simulator/findings/images/custom-product-dialog-on-a-phone.png
Binary files differ.
diff --git a/pos-simulator/findings/images/force-delete-blames-a-wallet.png b/pos-simulator/findings/images/force-delete-blames-a-wallet.png
Binary files differ.
diff --git a/pos-simulator/findings/images/login-form-on-a-phone.png b/pos-simulator/findings/images/login-form-on-a-phone.png
Binary files differ.
diff --git a/pos-simulator/findings/images/refund-form-on-a-phone.png b/pos-simulator/findings/images/refund-form-on-a-phone.png
Binary files differ.
diff --git a/pos-simulator/findings/login-form-collapses-under-the-keyboard.diff b/pos-simulator/findings/login-form-collapses-under-the-keyboard.diff
@@ -0,0 +1,69 @@
+diff --git a/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt b/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt
+index 99f9f91e..ae52257b 100644
+--- a/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt
++++ b/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt
+@@ -673,14 +673,34 @@ private fun ConfigScreen(
+ Modifier
+ .widthIn(max = if (isTabletLayout) 960.dp else 640.dp)
+ .fillMaxSize()
+- .padding(20.dp),
++ // A phone in landscape has about 150 dp of screen left
++ // once the keyboard is up; 40 dp of it must not go on
++ // padding, or the field being typed into does not fit.
++ .padding(
++ horizontal = 20.dp,
++ vertical = if (isTabletLayout) 20.dp else 8.dp,
++ ),
+ verticalArrangement = Arrangement.spacedBy(16.dp),
+ ) {
+- RowButtons(
+- mode = mode,
+- onManual = { onModeChanged(ConfigMode.Manual) },
+- onQr = { onModeChanged(ConfigMode.Qr) },
+- )
++ val tabs: @Composable () -> Unit = {
++ RowButtons(
++ mode = mode,
++ onManual = { onModeChanged(ConfigMode.Manual) },
++ onQr = { onModeChanged(ConfigMode.Qr) },
++ )
++ }
++ // In Manual mode the tab row goes *inside* the form's own
++ // list, so that it can scroll away. With the keyboard up a
++ // phone in landscape has about 150 dp of screen left, and a
++ // tab row pinned above the form takes a third of it -- enough
++ // that the field being typed into could not be brought into
++ // view at all. The QR mode has nothing to type and a camera
++ // preview that wants a fixed height, so it keeps the row
++ // where it was.
++ if (mode != ConfigMode.Manual)
++ {
++ tabs()
++ }
+ if (mode == ConfigMode.Manual)
+ {
+ ManualConfigScreen(
+@@ -688,6 +708,7 @@ private fun ConfigScreen(
+ Modifier
+ .fillMaxWidth()
+ .weight(1f),
++ tabs = tabs,
+ merchantUrl = merchantUrl,
+ username = username,
+ token = token,
+@@ -790,6 +811,7 @@ private fun ConfigScreen(
+ @Composable
+ private fun ManualConfigScreen(
+ modifier: Modifier,
++ tabs: @Composable () -> Unit,
+ merchantUrl: String,
+ username: String,
+ token: String,
+@@ -811,6 +833,7 @@ private fun ManualConfigScreen(
+ state = formListState,
+ verticalArrangement = Arrangement.spacedBy(16.dp),
+ ) {
++ item { tabs() }
+ item {
+ OutlinedTextField(
+ value = merchantUrl,
diff --git a/pos-simulator/findings/login-form-collapses-under-the-keyboard.md b/pos-simulator/findings/login-form-collapses-under-the-keyboard.md
@@ -0,0 +1,141 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# On a phone, the login form disappears the moment you tap a field
+
+Tap the **Merchant portal URL** field on a phone-sized screen and the whole
+form goes away. Not scrolled out of reach -- gone. What is left is the title,
+the two tabs, and the keyboard:
+
+
+
+The cashier is typing into a field that is not on the screen, cannot see what
+they have typed, cannot reach **Username**, **Password**, **Remember
+password** or **Connect**, and cannot scroll: nothing on the screen scrolls.
+The only way out is the Back key, which dismisses the keyboard and brings the
+form back -- and then the next tap on a field does it again.
+
+A terminal on a phone therefore cannot be provisioned by hand at all. The only
+route left is a `taler-pos://` setup URI.
+
+Look closely at the tab row as well: **"Manual config"** and **"QR config"**
+are sliced off along the bottom. That is the same squeeze seen from the other
+side -- the row is being measured into less height than its text needs.
+
+## Why it happens
+
+`merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt`:
+
+```kotlin
+Box(
+ modifier = Modifier
+ .fillMaxSize()
+ .systemBarsPadding()
+ .imePadding(), // <- the whole screen shrinks
+ contentAlignment = Alignment.TopCenter,
+) {
+ Column(
+ modifier = Modifier
+ .widthIn(max = if (isTabletLayout) 960.dp else 640.dp)
+ .fillMaxSize()
+ .padding(20.dp),
+ verticalArrangement = Arrangement.spacedBy(16.dp),
+ ) {
+ RowButtons(mode = mode, …) // the two tabs, a fixed height
+ if (mode == ConfigMode.Manual) {
+ ManualConfigScreen(
+ modifier = Modifier.fillMaxWidth().weight(1f), // <- the form
+ …
+ )
+ }
+ }
+}
+```
+
+`imePadding()` takes the keyboard's height off the *whole screen*, and the
+form is the weighted child of what is left. On a phone in landscape -- 411 dp
+high -- the keyboard leaves about 150 dp. The system bars and the 20 dp
+padding take some, the tab row takes about 48 dp and the 16 dp arrangement
+takes 16 more, and the weighted child is measured at roughly nothing. A
+`LazyColumn` with no height composes no items, which is why the fields are
+absent from the view hierarchy rather than merely off screen, and why there is
+no scrollbar to drag: the list that would scroll has nothing in it.
+
+The tab row is clipped for the same reason, one step earlier: it is measured
+against a maximum height smaller than it asked for.
+
+On a tablet the same code is fine. 800 dp less a keyboard still leaves enough
+for three fields and a button, and what does not fit scrolls, because the
+`LazyColumn` is then big enough to exist.
+
+## How it was found
+
+Every scenario that provisions through the form -- the whole `mock` set, and
+the login scenarios -- failed on the phone workers at the first field with
+
+```
+PosError: no text field on screen at all;
+ screen: ['QR config', 'Manual config', 'Merchant settings']
+```
+
+eleven times out of eleven, in 19 seconds each. "No text field on screen at
+all" is a strange thing for a login form to say, so it was photographed rather
+than worked around, and the photograph is the bug.
+
+The same sequence by hand, with no harness in it: open the terminal
+unprovisioned, tap the URL field, look.
+
+## Severity
+
+High on a phone, none on a tablet. It is the first screen of the app and it
+is the one screen a merchant cannot skip. There is no error, nothing blinks,
+and the keyboard behaves normally -- the form simply is not there, which reads
+like the app has crashed into a blank page.
+
+## Suggested fix
+
+`login-form-collapses-under-the-keyboard.diff`, verified on the emulator the
+screenshot came from. Two changes, both in `ConfigScreen`:
+
+* **Put the tab row inside the form's own list** in Manual mode, so that it
+ scrolls away instead of standing on the part of the screen the keyboard
+ left. It is passed in as a `tabs: @Composable () -> Unit` and becomes the
+ list's first item; QR mode keeps the row where it is, because it has nothing
+ to type and a camera preview that wants a fixed height.
+* **Spend less of a short screen on padding**: 8 dp vertical rather than 20 dp
+ where the layout is not a tablet.
+
+With both, the list is no longer measured at nothing, so it composes its items
+again: the fields are back in the hierarchy, `LazyColumn` scrolls the focused
+one above the keyboard, and the keyboard's own Next key walks the form the way
+it was meant to. The tab labels stop being clipped as well, because the row is
+no longer squeezed.
+
+What the patch does *not* do is make the whole form visible at once on a 411 dp
+landscape phone. The keyboard leaves about 150 dp, the app bar takes a third of
+that, and one text field is 56 dp -- so the form shows one field at a time and
+is walked with Next. That is a usable form rather than a good one; collapsing
+the app bar while the keyboard is up would be the next thing to try, and it is
+a design decision rather than a bug fix, so it is not in the patch.
+
+## Reproducer
+
+```bash
+POS_AVD_DEVICE=medium_phone POS_LCD_WIDTH=1920 POS_LCD_HEIGHT=1080 \
+ POS_LCD_DENSITY=420 emu/emu.sh create 1
+emu/emu.sh boot 1 && emu/emu.sh prepare 1
+POS_WORKER=1 python3 driver/suite.py login_form_fits_a_phone
+```
diff --git a/pos-simulator/findings/login-hangs-forever-on-a-silent-backend.md b/pos-simulator/findings/login-hangs-forever-on-a-silent-backend.md
@@ -0,0 +1,98 @@
+# A backend that never answers leaves the login form behind a spinner forever
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+**Severity:** medium-high -- the terminal becomes unusable with no way out
+short of killing the app, and the screen it is stuck on says nothing at all,
+so a cashier cannot tell it apart from a slow network.
+
+**Where:**
+`taler-kotlin-android/src/main/java/net/taler/common/HttpUtils.kt:71` (the
+timeouts) and
+`merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt`
+(the modal that covers the form while `isSubmitting` is true).
+
+**Found by:** `pos-simulator`, scenario `backend_never_answers`, against
+`backend/mockd.py --profile hang`.
+
+## What happens
+
+Point the terminal at a merchant backend that accepts the TCP connection,
+completes the TLS handshake, and then never sends a response. Fill the login
+form in and press Connect.
+
+The form is covered by a modal dialog containing a spinner and nothing else.
+Three minutes later it is still there:
+
+```
+hung-request-never-gives-up: the login form was still covered by its modal
+spinner 180s after submitting to a backend that never answers, with nothing to
+cancel and nothing to read
+blank-screen: 8 nodes, none labelled or tappable
+after a back press: nothing readable
+```
+
+The second line is the accessibility consequence of the first: the dialog is
+the focused window, it contains one `CircularProgressIndicator` and no text, so
+a screen reader announces nothing whatsoever. The third is that there is no way
+out -- `Dialog(onDismissRequest = {})` swallows the back press, and the dialog
+has no button.
+
+## Why
+
+Nothing gives up. `createDefaultHttpClient` installs `HttpTimeout` with every
+timeout set to infinity:
+
+```kotlin
+install(HttpTimeout) {
+ requestTimeoutMillis = INFINITE_TIMEOUT_MS
+ socketTimeoutMillis = INFINITE_TIMEOUT_MS
+ connectTimeoutMillis = INFINITE_TIMEOUT_MS
+}
+```
+
+So `fetchLimitedAccessToken` suspends until the peer closes the connection,
+which a hung peer does not do. `isSubmitting` is only cleared in the `catch`
+blocks of `submitManualConfig` and in `onConfigUpdate`, and neither runs.
+
+This is not the same thing as an unreachable host, which fails quickly and
+correctly (`login_unknown_host` passes): it needs a peer that accepts and then
+goes quiet -- a backend under load, a half-open connection a NAT has forgotten,
+or a captive portal.
+
+The infinite timeouts are deliberate in the library: the wallet needs them for
+long-polling, where a request is *meant* to hang until something happens. The
+terminal's login is not long-polling.
+
+## Reproducing it
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 backend/mockd.py --profile hang --port 19443 &
+python3 suite.py backend_never_answers
+```
+
+## The fix
+
+Two parts, and only the first is strictly necessary.
+
+A finite timeout on the requests the login makes. Ktor's `HttpTimeout` can be
+set per request, so this need not change the shared client and need not affect
+whatever long-polls:
+
+```kotlin
+httpClient.post(tokenUrl) {
+ timeout { requestTimeoutMillis = 30_000 }
+ ...
+}
+```
+
+and the same for the `GET` in `fetchPosConfig` and the backend `config` call.
+
+A way out of the modal. The dialog already exists; giving it a cancel button
+that clears `isSubmitting` -- and, ideally, cancels the coroutine -- turns an
+unrecoverable state into an ordinary one. It also fixes the accessibility side,
+because the button carries a label.
+
+No patch here: the timeout value is a product decision, and which of the three
+calls should get which value is worth a conversation rather than a guess.
diff --git a/pos-simulator/findings/payment-poll-crashes-when-the-session-ends.diff b/pos-simulator/findings/payment-poll-crashes-when-the-session-ends.diff
@@ -0,0 +1,94 @@
+diff --git a/merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt b/merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt
+index 91672e4f..e39c6a78 100644
+--- a/merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt
++++ b/merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt
+@@ -27,6 +27,7 @@ import androidx.lifecycle.MutableLiveData
+ import net.taler.lib.android.assertUiThread
+ import net.taler.merchantlib.CheckPaymentResponse
+ import net.taler.merchantlib.MerchantApi
++import net.taler.merchantlib.MerchantConfig
+ import net.taler.merchantlib.OrderHistoryEntry
+ import net.taler.merchantlib.PostOrderRequest
+ import net.taler.merchantpos.MainActivity.Companion.TAG
+@@ -91,8 +92,8 @@ class PaymentManager(
+ order: Order,
+ includeProducts: Boolean = true,
+ ) = scope.launch {
+- val merchantConfig = configManager.merchantConfig!!
+- val payment = Payment(order, order.summary, configManager.currency!!)
++ val merchantConfig = liveConfig() ?: return@launch
++ val payment = Payment(order, order.summary, configManager.currency ?: return@launch)
+ mPayment.value = payment
+ val parts = order.toOrderParts(includeProducts)
+ val request =
+@@ -235,7 +236,7 @@ class PaymentManager(
+
+ private fun checkPayment(orderId: String) =
+ scope.launch {
+- val merchantConfig = configManager.merchantConfig!!
++ val merchantConfig = liveConfig() ?: return@launch
+ api.checkOrder(merchantConfig, orderId).handle(
+ { error ->
+ // don't call onNetworkError() to not cancel payment, just keep trying
+@@ -369,10 +370,13 @@ class PaymentManager(
+ fun cancelPayment(error: String? = null)
+ {
+ stopPaymentChecks()
+- val merchantConfig = configManager.merchantConfig!!
++ // Not required: cancelling has to work even when the session is the
++ // thing that ended, and then there is nobody to delete the order at.
++ val merchantConfig = configManager.merchantConfig
+ mPayment.value?.let { payment ->
+ // A checkout order records cash or card already taken, so it stays for resuming.
+- if (!payment.paid &&
++ if (merchantConfig != null &&
++ !payment.paid &&
+ payment.checkoutId == null)
+ {
+ payment.orderId?.let { orderId ->
+@@ -398,7 +402,7 @@ class PaymentManager(
+ mDeleteNeedsForce.value = false
+ return
+ }
+- val merchantConfig = configManager.merchantConfig!!
++ val merchantConfig = liveConfig() ?: return
+ val orderId = mPayment.value?.orderId ?: return
+ scope.launch {
+ val result = api.deleteOrder(merchantConfig, orderId)
+@@ -419,7 +423,7 @@ class PaymentManager(
+ @UiThread
+ fun forceDeleteOrder()
+ {
+- val merchantConfig = configManager.merchantConfig!!
++ val merchantConfig = liveConfig() ?: return
+ val orderId = mPayment.value?.orderId ?: return
+ Log.d(TAG, "Force deleting claimed order $orderId")
+ scope.launch {
+@@ -437,6 +441,27 @@ class PaymentManager(
+ mDeleteNeedsForce.value = null
+ }
+
++ /**
++ * The merchant configuration, or null once the session has ended.
++ *
++ * `ConfigManager` clears it the moment a request comes back 401, and the
++ * payment screen polls once a second -- so between two ticks of
++ * [checkTimer] the field can go from a configuration to nothing, and
++ * every `!!` on it here was a crash on the main thread waiting for a
++ * token to expire. Where there is no session left there is also nothing
++ * useful to ask the backend, so the polling is stopped as well.
++ */
++ private fun liveConfig(): MerchantConfig?
++ {
++ val merchantConfig = configManager.merchantConfig
++ if (merchantConfig == null)
++ {
++ Log.d(TAG, "no merchant configuration left; stopping payment checks")
++ stopPaymentChecks()
++ }
++ return merchantConfig
++ }
++
+ private fun stopPaymentChecks()
+ {
+ checkTimer.cancel()
diff --git a/pos-simulator/findings/payment-poll-crashes-when-the-session-ends.md b/pos-simulator/findings/payment-poll-crashes-when-the-session-ends.md
@@ -0,0 +1,136 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# The terminal dies one second after the session ends on the payment screen
+
+The payment screen polls the backend once a second to see whether the customer
+has paid. If the merchant's session ends while it is doing that -- the token
+expires, or the back office revokes it -- the next poll kills the app:
+
+```
+11-08 23:11:08.191 D taler-pos: Network error: Error 2015 (401): The merchant
+ refused the request due to lack of authorization.
+ - Check credentials in 'Authorization' header
+--------- beginning of crash
+11-08 23:11:09.060 E AndroidRuntime: FATAL EXCEPTION: main
+11-08 23:11:09.060 E AndroidRuntime: java.lang.NullPointerException
+ at net.taler.merchantpos.payment.PaymentManager$checkPayment$1.invokeSuspend(PaymentManager.kt:238)
+ at net.taler.merchantpos.payment.PaymentManager.checkPayment(PaymentManager.kt:237)
+ at net.taler.merchantpos.payment.PaymentManager$checkTimer$1.onTick(PaymentManager.kt:79)
+ at android.os.CountDownTimer$1.handleMessage(CountDownTimer.java:145)
+```
+
+869 milliseconds between the 401 and the fatal exception -- exactly one tick of
+the poll timer. The process is killed, the activity is force-finished, and the
+cashier is back at the launcher with a customer halfway through paying.
+
+The session-expiry handling itself is fine and the message is written and
+translated. With the crash fixed, the same scenario shows
+
+```
+'Taler POS': 'Session expired – please re-enter your credentials' ['OK']
+```
+
+which is exactly right. The dialog never gets a chance on an unpatched build.
+
+## Why it happens
+
+`merchant-terminal/src/main/java/net/taler/merchantpos/payment/PaymentManager.kt:238`:
+
+```kotlin
+private fun checkPayment(orderId: String) =
+ scope.launch {
+ val merchantConfig = configManager.merchantConfig!! // <- line 238
+ api.checkOrder(merchantConfig, orderId).handle(…)
+ }
+```
+
+`ConfigManager.merchantConfig` is a `var MerchantConfig?` that is set to null
+the moment a request comes back 401 -- that is what ends the session. The
+payment screen's `CountDownTimer` ticks every `CHECK_INTERVAL` regardless, and
+the tick after the 401 dereferences a field that has just been emptied.
+
+It is not one line. `configManager.merchantConfig!!` appears five times in this
+file, and every one of them is reachable after the session has gone:
+
+| line | method | reached by |
+| --- | --- | --- |
+| 94 | `createPayment` | charging an order |
+| 238 | `checkPayment` | **the poll timer, once a second** |
+| 372 | `cancelPayment` | the Cancel button *and* the payment timeout |
+| 401 | `tryDeleteOrder` | the Delete button |
+| 422 | `forceDeleteOrder` | force-deleting a claimed order |
+
+Line 238 is the one that fires by itself, which is why it is the one that was
+caught; 372 is the next most likely, because a cashier whose screen has just
+stopped responding presses Cancel.
+
+## How it was found
+
+`driver/suite.py`, scenario `token_revoked_mid_payment`: bill an order, wait
+for the payment screen to start polling, revoke the terminal's own access
+token through the merchant API, and watch. The harness mints a token of its
+own for this, so nothing else's session is touched.
+
+Reproduced twice, on two different emulators, with the same stack both times.
+
+## Severity
+
+High. It is a crash, it needs no unusual input, and it happens at the worst
+moment in the app's whole life -- mid-payment, in front of a customer. A token
+with a finite lifetime reaches it on its own, without anybody doing anything
+wrong.
+
+## Suggested fix
+
+`payment-poll-crashes-when-the-session-ends.diff`, verified: the scenario goes
+from a fatal exception to a clean "Session expired" dialog.
+
+One helper, and all five call sites through it:
+
+```kotlin
+/**
+ * The merchant configuration, or null once the session has ended.
+ *
+ * `ConfigManager` clears it the moment a request comes back 401, and the
+ * payment screen polls once a second -- so between two ticks of [checkTimer]
+ * the field can go from a configuration to nothing …
+ */
+private fun liveConfig(): MerchantConfig?
+{
+ val merchantConfig = configManager.merchantConfig
+ if (merchantConfig == null)
+ {
+ Log.d(TAG, "no merchant configuration left; stopping payment checks")
+ stopPaymentChecks()
+ }
+ return merchantConfig
+}
+```
+
+`cancelPayment` is the one exception: it does not take the helper, because
+cancelling has to keep working when the session is the thing that ended. It
+reads the field directly and skips only the "delete the abandoned order" step,
+so the error still reaches `mPayment` and the cashier still sees why.
+
+`:merchant-terminal:testSimUnitTest` passes with the patch.
+
+## Reproducer
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 suite.py token_revoked_mid_payment
+```
diff --git a/pos-simulator/findings/pos-config-url-percent-encodes-the-separator.diff b/pos-simulator/findings/pos-config-url-percent-encodes-the-separator.diff
@@ -0,0 +1,22 @@
+diff --git a/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigManager.kt b/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigManager.kt
+index f50adf0b..5c5078cd 100644
+--- a/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigManager.kt
++++ b/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigManager.kt
+@@ -335,9 +335,16 @@ class ConfigManager(
+ try {
+ val url = when(val c = config) {
+ //is Config.Old -> c.configUrl
++ // Two segments, appended separately: appendPath() encodes
++ // a separator inside its argument, because a segment may
++ // legitimately contain one -- so "private/pos" became
++ // "private%2Fpos". The backend decodes the path before
++ // routing and answered it anyway; a reverse proxy in front
++ // of it need not.
+ is Config.New -> c.merchantUrl.toUri()
+ .buildUpon()
+- .appendPath("private/pos")
++ .appendPath("private")
++ .appendPath("pos")
+ .build()
+ .toString()
+ }
diff --git a/pos-simulator/findings/pos-config-url-percent-encodes-the-separator.md b/pos-simulator/findings/pos-config-url-percent-encodes-the-separator.md
@@ -0,0 +1,97 @@
+# The terminal asks for its configuration at `/private%2Fpos`
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+**Severity:** medium -- works against a bare merchant backend, and cannot work
+behind a reverse proxy that does not decode encoded slashes, which is the
+default for Apache and a common hardening setting for nginx. The terminal then
+cannot be configured at all, and says only "Error: Could not connect to
+configuration server".
+
+**Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigManager.kt:340`
+
+**Found by:** `pos-simulator`, scenario `pos_config_url_encodes_the_separator`.
+
+## What happens
+
+The request the terminal makes for its point-of-sale configuration arrives with
+the path separator percent-encoded. From the mock backend's request log, with
+the terminal configured for instance `mockshop`:
+
+```
+POST /instances/mockshop/private/token 200
+GET /instances/mockshop/private%2Fpos <- the configuration request
+GET /instances/mockshop/config 200
+GET /instances/mockshop/private/products/pretzel 200
+```
+
+Only that one request is affected. Every other call -- the token, the backend
+config, the products, the orders, the refunds -- goes through
+`MerchantConfig.urlFor`, which concatenates strings and so leaves the separator
+alone.
+
+## Why
+
+```kotlin
+val url = when (val c = config) {
+ is Config.New -> c.merchantUrl.toUri()
+ .buildUpon()
+ .appendPath("private/pos") // ConfigManager.kt:340
+ .build()
+ .toString()
+}
+```
+
+`Uri.Builder.appendPath` appends **one path segment** and percent-encodes
+anything in it that is not legal inside a segment -- including `/`, because a
+segment may legitimately contain an encoded slash. The intent was two segments.
+
+## Why nobody has noticed
+
+The GNU Taler merchant backend decodes the request path before routing, so it
+answers the encoded form identically:
+
+```
+$ curl -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOK" \
+ 'https://backend.demo.taler.net/instances/sandbox/private%2Fpos'
+200
+$ curl -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOK" \
+ 'https://backend.demo.taler.net/instances/sandbox/private/pos'
+200
+```
+
+A deployment that puts the backend behind a reverse proxy need not. Apache's
+`AllowEncodedSlashes` defaults to `Off` and answers 404 for such a request
+before it ever reaches the backend; nginx normalises or rejects depending on
+whether the location uses a rewrite. This is the mock backend's exact-match
+routing answering 404 that first surfaced it -- a mock is stricter than the
+real thing on purpose, and that is the value of having one.
+
+## Reproducing it
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 ../findings/repro_encoded_path_separator.py
+```
+
+It starts a mock backend that records the paths it is asked for, provisions the
+terminal against it through the login form, and prints every request that
+arrived with an encoded separator.
+
+## The fix
+
+One line; `pos-config-url-percent-encodes-the-separator.diff` has it. Either
+append the two segments separately:
+
+```kotlin
+ .appendPath("private")
+ .appendPath("pos")
+```
+
+or, matching what the rest of the module does, use `MerchantConfig.urlFor` --
+but that needs a `MerchantConfig`, which does not exist yet at this point in
+`fetchConfig`, so the two `appendPath` calls are the smaller change.
+
+`appendEncodedPath("private/pos")` also works and is what the name suggests,
+but it is the riskier spelling: it would pass a merchant-supplied segment
+through unencoded if the string ever stopped being a literal.
diff --git a/pos-simulator/findings/qr-config-tab-crashes-the-terminal.diff b/pos-simulator/findings/qr-config-tab-crashes-the-terminal.diff
@@ -0,0 +1,160 @@
+diff --git a/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt b/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt
+index 42247056..0bc3fdb5 100644
+--- a/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt
++++ b/merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt
+@@ -393,25 +393,30 @@ class ConfigFragment : Fragment() {
+ useCase.setAnalyzer(cameraExecutor) { proxy ->
+ val mediaImage = proxy.image
+ if (mediaImage != null) {
+- val nv21 = yuv420888ToNv21(mediaImage)
+- val width = mediaImage.width
+- val height = mediaImage.height
+- val source = PlanarYUVLuminanceSource(
+- nv21,
+- width,
+- height,
+- 0,
+- 0,
+- width,
+- height,
+- false,
+- )
+- val rotated = when (proxy.imageInfo.rotationDegrees) {
+- 90, 270 -> source.rotateCounterClockwise()
+- else -> source
+- }
+- val bitmap = BinaryBitmap(HybridBinarizer(rotated))
+ try {
++ val degrees = proxy.imageInfo.rotationDegrees
++ val upright = rotateLuminance(
++ luminanceOf(mediaImage),
++ mediaImage.width,
++ mediaImage.height,
++ degrees,
++ )
++ val sideways = degrees % 180 != 0
++ val width =
++ if (sideways) mediaImage.height else mediaImage.width
++ val height =
++ if (sideways) mediaImage.width else mediaImage.height
++ val source = PlanarYUVLuminanceSource(
++ upright,
++ width,
++ height,
++ 0,
++ 0,
++ width,
++ height,
++ false,
++ )
++ val bitmap = BinaryBitmap(HybridBinarizer(source))
+ val result = qrReader.decodeWithState(bitmap)
+ onQrDecoded(result.text)
+ } catch (_: NotFoundException) {
+@@ -433,18 +438,94 @@ class ConfigFragment : Fragment() {
+ }, cameraExecutor)
+ }
+
+- private fun yuv420888ToNv21(image: Image): ByteArray {
+- val yPlane = image.planes[0].buffer
+- val uPlane = image.planes[1].buffer
+- val vPlane = image.planes[2].buffer
+- val ySize = yPlane.remaining()
+- val uSize = uPlane.remaining()
+- val vSize = vPlane.remaining()
+- val nv21 = ByteArray(ySize + uSize + vSize)
+- yPlane.get(nv21, 0, ySize)
+- vPlane.get(nv21, ySize, vSize)
+- uPlane.get(nv21, ySize + vSize, uSize)
+- return nv21
++ /**
++ * The image's luminance plane, densely packed.
++ *
++ * A YUV_420_888 plane is only densely packed when its row stride equals
++ * the image width and its pixel stride is one. Neither is guaranteed:
++ * hardware commonly aligns rows to 16 or 32 bytes. Copying the buffer
++ * wholesale where they differ shears every row after the first, and the
++ * only symptom is that nothing ever decodes.
++ *
++ * Only this plane is read. [PlanarYUVLuminanceSource] looks at luminance
++ * and nothing else, so the chroma planes need not be copied at all.
++ */
++ private fun luminanceOf(image: Image): ByteArray {
++ val plane = image.planes[0]
++ val buffer = plane.buffer
++ val width = image.width
++ val height = image.height
++ val out = ByteArray(width * height)
++ val rowStride = plane.rowStride
++ val pixelStride = plane.pixelStride
++ if (rowStride == width && pixelStride == 1) {
++ buffer.get(out, 0, minOf(out.size, buffer.remaining()))
++ return out
++ }
++ val row = ByteArray(rowStride)
++ var offset = 0
++ for (y in 0 until height) {
++ val length = minOf(rowStride, buffer.remaining())
++ if (length <= 0) break
++ buffer.get(row, 0, length)
++ if (pixelStride == 1) {
++ System.arraycopy(row, 0, out, offset, minOf(width, length))
++ } else {
++ var x = 0
++ var i = 0
++ while (x < width && i < length) {
++ out[offset + x] = row[i]
++ x++
++ i += pixelStride
++ }
++ }
++ offset += width
++ }
++ return out
++ }
++
++ /**
++ * A densely packed luminance plane, rotated clockwise by [degrees].
++ *
++ * The rotation is done on the bytes rather than by asking the
++ * [PlanarYUVLuminanceSource] to rotate itself: that source does not
++ * support rotation, and its inherited [LuminanceSource.rotateCounterClockwise]
++ * throws rather than returning anything -- which crashed the app on the
++ * first frame of every device whose sensor is a quarter turn from the
++ * display, which is to say most of them.
++ */
++ private fun rotateLuminance(
++ data: ByteArray,
++ width: Int,
++ height: Int,
++ degrees: Int,
++ ): ByteArray {
++ val turns = ((degrees % 360) + 360) % 360
++ if (turns == 0) return data
++ val out = ByteArray(width * height)
++ when (turns) {
++ 90 -> for (y in 0 until height) {
++ val src = y * width
++ for (x in 0 until width) {
++ out[x * height + (height - 1 - y)] = data[src + x]
++ }
++ }
++ 180 -> for (y in 0 until height) {
++ val src = y * width
++ val dst = (height - 1 - y) * width
++ for (x in 0 until width) {
++ out[dst + (width - 1 - x)] = data[src + x]
++ }
++ }
++ 270 -> for (y in 0 until height) {
++ val src = y * width
++ for (x in 0 until width) {
++ out[(width - 1 - x) * height + y] = data[src + x]
++ }
++ }
++ else -> return data
++ }
++ return out
+ }
+
+ private fun onQrDecoded(raw: String) {
diff --git a/pos-simulator/findings/qr-config-tab-crashes-the-terminal.md b/pos-simulator/findings/qr-config-tab-crashes-the-terminal.md
@@ -0,0 +1,140 @@
+# The QR configuration tab crashes the terminal on the first camera frame
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+**Severity:** high -- the documented way to provision a terminal kills the app,
+and keeps killing it, so the terminal cannot be set up that way at all.
+
+**Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/config/ConfigFragment.kt:410`
+
+**Found by:** `pos-simulator`, scenario `config_qr_tab`.
+
+## What happens
+
+On the login screen, select the **QR config** tab. The camera starts, the first
+frame arrives at the analyzer, and the process dies:
+
+```
+FATAL EXCEPTION: main
+Process: net.taler.merchantpos, PID: 23777
+java.lang.UnsupportedOperationException: This luminance source does not support rotation by 90 degrees.
+ at com.google.zxing.LuminanceSource.rotateCounterClockwise(LuminanceSource.java:119)
+ at net.taler.merchantpos.config.ConfigFragment.startCamera$lambda$0$1$0(ConfigFragment.kt:410)
+ at androidx.camera.core.ImageAnalysisAbstractAnalyzer.lambda$analyzeImage$0(ImageAnalysisAbstractAnalyzer.java:310)
+ at android.os.Handler.handleCallback(Handler.java:995)
+ at android.os.Looper.loop(Looper.java:338)
+ at android.app.ActivityThread.main(ActivityThread.java:9067)
+```
+
+The user is dropped on the launcher with "Taler POS keeps stopping". Reopening
+the app and selecting the tab again crashes it again.
+
+## Why
+
+```kotlin
+val source = PlanarYUVLuminanceSource(nv21, width, height, 0, 0, width, height, false)
+val rotated = when (proxy.imageInfo.rotationDegrees) {
+ 90, 270 -> source.rotateCounterClockwise() // ConfigFragment.kt:410
+ else -> source
+}
+```
+
+`PlanarYUVLuminanceSource` does not support rotation. In zxing-core 3.5.4 it
+overrides `crop`, `renderThumbnail` and `isCropSupported`, and leaves
+`rotateCounterClockwise()` and `isRotateSupported()` to the base class --
+where the first throws unconditionally and the second returns `false`:
+
+```
+$ javap -p -cp core-3.5.4.jar com.google.zxing.PlanarYUVLuminanceSource | grep -c rotate
+0
+$ javap -p -cp core-3.5.4.jar com.google.zxing.LuminanceSource | grep rotate
+ public com.google.zxing.LuminanceSource rotateCounterClockwise();
+```
+
+So the branch is a guaranteed crash whenever it is taken, and it is taken
+whenever `rotationDegrees` is 90 or 270 -- which is the *normal* case for this
+screen. `MainActivity` is declared `screenOrientation="landscape"`, the sensor
+on a phone or tablet is mounted for portrait, and CameraX reports the rotation
+needed to bring the two into line. The crash is not an edge case; a device
+whose sensor happens to agree with a landscape display is the edge case.
+
+`isRotateSupported()` is never consulted, which is what would have turned this
+into a no-op instead of a crash.
+
+## A second defect in the same function
+
+`yuv420888ToNv21` copies each plane with `buffer.get(...)` and ignores
+`Image.Plane.getRowStride()` and `getPixelStride()`:
+
+```kotlin
+val ySize = yPlane.remaining()
+...
+yPlane.get(nv21, 0, ySize)
+vPlane.get(nv21, ySize, vSize)
+uPlane.get(nv21, ySize + vSize, uSize)
+```
+
+A YUV_420_888 plane is only densely packed when `rowStride == width` and, for
+the chroma planes, `pixelStride == 1`. Neither is guaranteed: hardware commonly
+aligns rows to 16 or 32 bytes, and the chroma planes of this format are
+routinely semi-planar with `pixelStride == 2`. Where they differ, every row
+after the first is offset by the padding, the luminance image comes out sheared
+and no code decodes -- silently, because a `NotFoundException` is exactly what
+"no code in frame" looks like.
+
+The emulator's camera happens to deliver `rowStride == width`, which is why
+this one does not show up as a crash. It is the same defect the wallet
+simulator recorded for the wallet's scanner
+(`simulator/findings/qr-camera-ignores-the-plane-strides.md`); the two scanners
+are separate code.
+
+## Reproducing it
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 ../findings/repro_qr_tab_crash.py
+```
+
+or by hand: install the app, open it with no configuration, tap **QR config**.
+
+The emulator's virtual-scene camera reproduces it without a code to scan,
+because the crash is in the frame handler and does not depend on what the
+frame contains.
+
+## The fix
+
+`qr-config-tab-crashes-the-terminal.diff` rotates the luminance bytes before
+building the source, instead of asking the source to rotate itself, and honours
+the plane strides while copying. Both changes are in `ConfigFragment`:
+
+* `luminanceFrom(image)` walks the Y plane row by row using `rowStride` and
+ `pixelStride`, so a padded or interleaved plane copies correctly. Only the Y
+ plane is needed -- `PlanarYUVLuminanceSource` reads luminance only, and the
+ chroma bytes the old code appended were never looked at.
+* `rotate(bytes, width, height, degrees)` produces the rotated buffer, and the
+ source is constructed with the dimensions that go with it.
+
+An alternative one-line fix is to drop the rotation altogether, since zxing's
+QR detector finds its finder patterns at any orientation. That is a smaller
+change but a worse one: it leaves the rotation handling in the code looking
+correct while never running, and it does nothing about the strides.
+
+### What the patch was verified to do
+
+On one emulator (API 36, tablet profile, virtual-scene camera), with the same
+AVD and the same tap in both cases:
+
+* the unpatched APK dies with the stack trace above -- reproduced four times,
+ including twice with a bare `adb shell input tap` rather than through the
+ harness, so it is not an artefact of how the simulator taps;
+* the patched APK does not. The QR tab opens, the live camera preview renders
+ and the "Scan the QR code from Merchant Backoffice" hint appears (confirmed
+ by screenshot, because the view hierarchy is unreliable over a camera
+ preview -- see the README's gotchas).
+
+What is **not** yet verified is that a code is decoded correctly: showing the
+camera a real QR code needs the emulator's virtual-scene poster, and no decode
+has succeeded yet on that path. So the stride fix is reasoned from the
+YUV_420_888 contract rather than demonstrated, and the rotation fix is
+demonstrated only to the extent that it no longer crashes. Finishing that
+verification is the first item for the next round.
diff --git a/pos-simulator/findings/receipt-screen-titled-payment-required.diff b/pos-simulator/findings/receipt-screen-titled-payment-required.diff
@@ -0,0 +1,18 @@
+diff --git a/merchant-terminal/src/main/java/net/taler/merchantpos/MainActivity.kt b/merchant-terminal/src/main/java/net/taler/merchantpos/MainActivity.kt
+index 87c5079e..897d06fc 100644
+--- a/merchant-terminal/src/main/java/net/taler/merchantpos/MainActivity.kt
++++ b/merchant-terminal/src/main/java/net/taler/merchantpos/MainActivity.kt
+@@ -533,6 +533,13 @@ private fun MerchantTerminalApp(
+ {
+ currentPayment?.statusLoading == true -> R.string.order_details_loading
+ currentPayment?.claimed == true -> R.string.checkout_payment_claimed_title
++ // A sale settled entirely in cash or on a card reaches
++ // this screen only to hand the customer a receipt.
++ // The body says so -- "Collect receipt", "Paid in
++ // full" -- and titling it "Payment required" told the
++ // cashier the opposite on the same screen.
++ currentPayment?.selfCollect == true ->
++ R.string.checkout_collect_receipt_title
+ else -> R.string.payment_process_label
+ },
+ )
diff --git a/pos-simulator/findings/receipt-screen-titled-payment-required.md b/pos-simulator/findings/receipt-screen-titled-payment-required.md
@@ -0,0 +1,100 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# "Paid in full", under a title bar that says "Payment required"
+
+A sale paid entirely outside Taler -- all cash, or all card -- still ends on
+the payment screen, because the customer can scan a receipt into a Taler
+wallet from it. The body says so plainly:
+
+```
+Collect receipt
+Summary Regular order
+Paid in full
+Scan with a Taler wallet to collect the receipt.
+Collect receipt on this device
+```
+
+and the title bar above it says **Payment required**.
+
+The recorded hierarchy, in order, with the title last because it is the top
+bar's own node:
+
+```
+['Collect receipt', 'Payment possible until 11/8/26 10:33 PM', 'Order',
+ '#pos-a58b70de-12d0-4447-9773-26f316b21eb0', 'Summary', 'Regular order',
+ 'Paid in full', 'Scan with a Taler wallet to collect the receipt.',
+ 'Merchant', 'Demo Sandbox merchant', 'Share', 'Copy',
+ 'Collect receipt on this device', 'Back to payment options',
+ 'Open navigation menu', 'Payment required']
+```
+
+On a till that is not a cosmetic difference: "Payment required" is what a
+cashier glances at to decide whether to let the customer go.
+
+## Why it happens
+
+`merchant-terminal/src/main/java/net/taler/merchantpos/MainActivity.kt`:
+
+```kotlin
+PosDestination.ProcessPayment.route ->
+{
+ stringResource(
+ when
+ {
+ currentPayment?.statusLoading == true -> R.string.order_details_loading
+ currentPayment?.claimed == true -> R.string.checkout_payment_claimed_title
+ else -> R.string.payment_process_label // "Payment required"
+ },
+ )
+}
+```
+
+`Payment.selfCollect` is the flag for "the whole order was settled outside
+Taler" -- `PaymentManager` sets it to `checkout.open.isZero()`. Eight places
+in `ProcessPaymentFragment` branch on it to turn the screen into a receipt:
+line 415 titles the body "Collect receipt", 686, 704 and 830 drop the Taler
+branding, 875 turns the action into "collect on this device". The title in
+`MainActivity` is the one place that does not look at it.
+
+## How it was found
+
+Walking a cash-settled checkout by hand on both layouts: enable Cash, charge
+an amount, record the whole amount in cash, press **Complete payment**. The
+scenario `checkout_cash_covers_it_all` goes through the same screen.
+
+## Severity
+
+Low to medium. Nothing is lost and the sale is complete; what is wrong is that
+the screen contradicts itself about whether money is owed, at the moment a
+cashier is deciding exactly that.
+
+## Suggested fix
+
+`receipt-screen-titled-payment-required.diff` -- one branch, using the string
+the body of the same screen already uses:
+
+```kotlin
+currentPayment?.selfCollect == true ->
+ R.string.checkout_collect_receipt_title
+```
+
+Not in the patch, because it needs a new string and its translations rather
+than a code change: the same screen also shows **"Payment possible until
+<time>"**. For a receipt that is a deadline for *collecting* it, not for
+paying, and the wording says the opposite.
+
+Filed as [11974](https://bugs.gnunet.org/view?id=11974).
diff --git a/pos-simulator/findings/refund-amount-swallows-extra-decimal-points.diff b/pos-simulator/findings/refund-amount-swallows-extra-decimal-points.diff
@@ -0,0 +1,18 @@
+diff --git a/taler-kotlin-android/src/main/java/net/taler/common/Amount.kt b/taler-kotlin-android/src/main/java/net/taler/common/Amount.kt
+index 34f534ca..c9d808c0 100644
+--- a/taler-kotlin-android/src/main/java/net/taler/common/Amount.kt
++++ b/taler-kotlin-android/src/main/java/net/taler/common/Amount.kt
+@@ -96,6 +96,13 @@ data class Amount(
+ fun fromString(currency: String, str: String): Amount {
+ // value
+ val valueSplit = str.split(".")
++ // Everything after a second separator used to be dropped in
++ // silence: "1.000.50" parsed as one unit and no fraction, so a
++ // caller that trusted this with user input got an amount nobody
++ // had typed. isValidAmountStr has always rejected it; this makes
++ // the parser agree with the validator.
++ if (valueSplit.size > 2)
++ throw AmountParserException("Malformed amount $str")
+ val value = checkValue(valueSplit[0].toLongOrNull())
+ // fraction
+ val fraction: Int = if (valueSplit.size > 1) {
diff --git a/pos-simulator/findings/refund-amount-swallows-extra-decimal-points.md b/pos-simulator/findings/refund-amount-swallows-extra-decimal-points.md
@@ -0,0 +1,130 @@
+# A refund amount with two decimal points refunds a different number
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+**Severity:** medium-high -- it is a money bug with no warning attached. The
+cashier types one amount, the terminal accepts it without comment, and the
+customer is refunded another.
+
+**Where:** `taler-kotlin-android/src/main/java/net/taler/common/Amount.kt:96`
+(`fromString`), reached from
+`merchant-terminal/src/main/java/net/taler/merchantpos/refund/RefundFragment.kt`
+(`submitRefund`).
+
+**Found by:** `pos-simulator`, scenario `refund_amount_edges`, which reported
+that a refund of `'1.0.0'` was accepted; `refund_amount_swallows_extra_dots`
+is the sharpened version.
+
+## What happens
+
+Refund a paid order and type an amount with two decimal points -- a slip, or
+the thousands separator of a locale that uses `.` for it. The terminal accepts
+it and goes straight to the refund code. What it refunds is not what was typed:
+
+| Typed | Refunded |
+| --- | --- |
+| `1.0.0` | 1.00 |
+| `1.000.50` | 1.00 |
+| `12.34.56` | 12.34 |
+| `10.5.0` | 10.50 |
+
+No error, no rounding notice, nothing. `1.000.50` on an order of ten units
+refunds one.
+
+Observed, on an order of KUDOS:10.00 paid by a real wallet against
+`backend.demo.taler.net`:
+
+```
+typing '1.000.50' as the refund amount on a KUDOS:10.00 order
+after approving: accepted=True, dialog='Refund':
+ 'Please let customer scan QR Code to offer refund ク1.00
+ Purchase reference: 2026.302-EWDB9FKBH4DJG' ['Abort']
+the backend recorded a refund of 'KUDOS:1'
+```
+
+The refund screen does print the amount it settled on -- "ク1.00" -- so a
+cashier who reads it carefully can catch this. Nothing draws their attention to
+it, and the screen they are reading is the one that says the refund has already
+been made.
+
+## What makes it a defect rather than a gap
+
+The form does validate. `refund_amount_edges` submits four malformed amounts
+on an order of 1.00 and the terminal catches three of them, each with a
+message that names the problem:
+
+| Typed | What the form said |
+| --- | --- |
+| `99.00` | "Greater than order amount of 1.00" |
+| `0.00` | "Needs to be positive amount" |
+| `abc` | "Invalid amount" |
+| `1.0.0` | *accepted* |
+
+So this is not a screen with no input checking; it is one case slipping
+through the checking that is there -- which is why it has survived, and why it
+is worth fixing at the parser rather than by adding one more branch to the
+form.
+
+## Why
+
+```kotlin
+fun fromString(currency: String, str: String): Amount {
+ // value
+ val valueSplit = str.split(".")
+ val value = checkValue(valueSplit[0].toLongOrNull())
+ // fraction
+ val fraction: Int = if (valueSplit.size > 1) {
+ val fractionStr = valueSplit[1]
+ ...
+```
+
+`split(".")` on `"1.000.50"` gives three pieces. The parser reads
+`valueSplit[0]` and `valueSplit[1]` and never looks at the rest, so everything
+after the second point is discarded in silence.
+
+The validator in the same companion object gets it right --
+
+```kotlin
+fun isValidAmountStr(str: String): Boolean {
+ if (str.count { it == '.' } > 1) return false
+```
+
+-- but `submitRefund` does not call it. It calls `fromString` directly, inside
+a `try` that only catches `AmountParserException`, and `fromString` does not
+throw one here: as far as it is concerned the input parsed fine.
+
+## Scope
+
+`Amount` is in `taler-kotlin-android`, so `fromString` is shared by the
+terminal, the wallet and the cashier app. The refund form is the place this
+round reached, because it is a free-text amount field fed straight to the
+parser; any other screen that parses user-typed text with `fromString` has the
+same hole. The order screen's custom-product dialog is worth checking next --
+it also takes a typed amount.
+
+## Reproducing it
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 suite.py refund_amount_swallows_extra_dots
+```
+
+It bills ten units, has the customer wallet pay, types `1.000.50` into the
+refund amount, and compares what the backend recorded against what was typed.
+
+## The fix
+
+`refund-amount-swallows-extra-decimal-points.diff`: two lines in `fromString`,
+rejecting more than one separator so that the parser agrees with the validator
+that has always been beside it.
+
+Verified with the patch applied: `:taler-kotlin-android:testDebugUnitTest`
+(20 tests, including the 9 of `AmountTest`), `:merchant-terminal:testSimUnitTest`
+(37 tests) and `:wallet:testFdroidDebugUnitTest` (116 tests) all pass. The
+change only turns input that was previously misread into input that is
+rejected, so nothing that was parsed correctly before parses differently now.
+
+Worth doing as well, though it needs a decision rather than a patch: the refund
+field accepts anything and only complains when Approve is pressed. Validating
+as the cashier types -- `isValidAmountStr` is right there -- would stop the
+whole class at the field rather than at the parser.
diff --git a/pos-simulator/findings/refund-form-unusable-on-a-phone.md b/pos-simulator/findings/refund-form-unusable-on-a-phone.md
@@ -0,0 +1,147 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# On a phone, a form with a text field loses its buttons to the keyboard
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+On a phone-sized screen the refund form opens, focuses its amount field, and
+raises the keyboard -- and everything between the order summary and the
+keyboard disappears. No amount field, no reason field, no **Approve refund**,
+no **Abort**.
+
+
+
+That is the whole screen. "Regular order" is the order summary, the band below
+it is empty, and the keyboard is up for a field that is not on screen: the
+cashier is typing a refund amount they cannot see, into a form they cannot
+submit. The only way out is Back.
+
+It is not a scrolling problem. The form does not scroll -- there is nothing to
+scroll to -- and the controls are not merely below the fold: they are absent
+from the view hierarchy entirely, which is how the harness noticed.
+
+## Why it happens
+
+`merchant-terminal/src/main/java/net/taler/merchantpos/refund/RefundFragment.kt`:
+
+```kotlin
+Column(
+ modifier = Modifier
+ .fillMaxSize()
+ .imePadding()
+ .padding(20.dp),
+ verticalArrangement = Arrangement.spacedBy(16.dp),
+) {
+ Text(item.summary)
+ OutlinedTextField(value = amountText, …) // focused by a LaunchedEffect
+ OutlinedTextField(value = reason, …)
+ Button(onClick = { submitRefund() }) { Text(…refund_confirm…) }
+ OutlinedButton(onClick = onAbort) { Text(…refund_abort…) }
+ Spacer(modifier = Modifier.weight(1f)…)
+}
+```
+
+Three things combine:
+
+* **The column cannot scroll.** There is no `verticalScroll`, so what does not
+ fit is not reachable.
+* **`imePadding()` takes the keyboard's height off the column.** In landscape
+ on a 411 dp-high screen the numeric keyboard leaves a couple of hundred dp,
+ and the fixed children -- two text fields at 56 dp each, two buttons, and
+ 40 dp of padding -- need more than that.
+* **The amount field focuses itself** in a `LaunchedEffect(Unit)`, so the
+ keyboard is up before the cashier has touched anything. The screen is never
+ shown in its usable state.
+
+The `Spacer` at the bottom carries a `detectTapGestures` that dismisses the
+keyboard, which would be the way out -- but it is the weighted child, so it is
+the first thing squeezed to zero height, and by the time the keyboard is up
+there is nothing left of it to tap.
+
+## How it was found
+
+The harness drives a phone-sized emulator as well as a tablet -- 1920x1080 at
+420 dpi, which is 731x411 dp -- because five of the terminal's screens pick
+their layout on `smallestScreenWidthDp`. `refund_full` and
+`refund_amount_edges` pass on the tablet and fail on the phone, four runs each
+way, and `order_custom_product_invalid_amount` typed a letter into the price
+field where it meant to press Add.
+
+What took three rounds to pin down is *where* it fails. `Pos.start_refund`
+finds the form fine, because it puts the keyboard away before looking; the
+failure lands later, on the tap for "Approve refund", after the amount has
+been typed and the keyboard is back. A list of labels cannot tell "the app
+clipped its controls" from "the driver is looking in the wrong place", so
+`Pos._reach_approve_refund` now photographs the screen in that state before
+doing anything about it. The picture above is that photograph.
+
+## Severity
+
+High on a phone, none on a tablet. A merchant running the terminal on a phone
+cannot refund anything through the UI at all. The terminal is landscape-locked,
+so turning the device is not a workaround; dismissing the keyboard with Back
+is, and nothing on the screen suggests it.
+
+## The same thing in the custom-product dialog
+
+It is not one screen. The order screen's **Add custom product** dialog puts two
+text fields above its Add and Abort buttons, and on a phone the keyboard covers
+the buttons:
+
+
+
+Here the dialog is clipped at the keyboard's top edge, with Add and Abort below
+it. This one is worse than it looks from a hierarchy dump, because the
+*buttons are still reported* at their layout coordinates -- the dialog is its
+own window and knows nothing about the keyboard -- so a tap aimed at Add lands
+on the key underneath. In the picture the field reads `nonsenseu`: the "u" is
+the letter the harness pressed while trying to press Add.
+
+A cashier does the same thing: the button they can see is a keyboard key. The
+difference from the refund form is only that a `Material3 AlertDialog` is
+dismissible by tapping outside it, so there is a way out.
+
+## Suggested fix
+
+Let the column scroll, so nothing can be squeezed out of reach:
+
+```kotlin
+Column(
+ modifier = Modifier
+ .fillMaxSize()
+ .imePadding()
+ .verticalScroll(rememberScrollState())
+ .padding(20.dp),
+ …
+)
+```
+
+and consider not focusing the amount field on open, or keeping the buttons
+outside the scrolling area so they are always on screen. The dialog wants the
+same treatment: its `text` slot should scroll, so that the `confirmButton` and
+`dismissButton` keep their place.
+
+## Reproducer
+
+```bash
+POS_AVD_DEVICE=medium_phone POS_LCD_WIDTH=1920 POS_LCD_HEIGHT=1080 \
+ POS_LCD_DENSITY=420 emu/emu.sh create 3
+emu/emu.sh boot 3 && emu/emu.sh prepare 3
+POS_WORKER=3 python3 driver/suite.py refund_full
+```
+
+The screenshot lands in `$POS_SIM_ROOT/out/refund-form-without-its-buttons.png`.
diff --git a/pos-simulator/findings/repro_encoded_path_separator.py b/pos-simulator/findings/repro_encoded_path_separator.py
@@ -0,0 +1,93 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""The terminal asks for its configuration at `/private%2Fpos`.
+
+Starts a merchant backend that routes on exact paths, points the terminal at it
+through the login form, and prints every request that arrived with the path
+separator percent-encoded.
+
+ cd /tmp/taler-pos-sim/driver && . ../env.sh
+ python3 ../findings/repro_encoded_path_separator.py
+
+Exits 0 when the encoded request reproduces, 1 when it does not.
+"""
+
+import os
+import sys
+import threading
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent / "driver"))
+sys.path.insert(0, str(HERE.parent / "backend"))
+
+import mockd
+from device import Device, serial_for
+from pos import Pos
+
+SERIAL = serial_for()
+PORT = int(os.environ.get("POS_MOCK_PORT", "19443"))
+INSTANCE = "mockshop"
+
+
+def main() -> int:
+ print(f"1. a merchant backend on https://localhost:{PORT}, routing on exact paths")
+ server, state = mockd.build_server("healthy", PORT, INSTANCE,
+ f"localhost:{PORT}")
+ threading.Thread(target=server.serve_forever, daemon=True).start()
+ time.sleep(1)
+
+ dev = Device(SERIAL)
+ app = Pos(dev)
+ dev.adb("reverse", f"tcp:{PORT}", f"tcp:{PORT}", check=False)
+
+ print("2. provisioning the terminal against it through the login form")
+ app.fresh_start()
+ try:
+ app.provision_by_form(f"localhost:{PORT}", INSTANCE, "mock-secret",
+ expect_success=False)
+ finally:
+ pass
+
+ print("3. waiting for the configuration request")
+ deadline = time.monotonic() + 45
+ while time.monotonic() < deadline:
+ if any("private" in p for p in state.paths()):
+ break
+ time.sleep(2)
+ time.sleep(3)
+
+ print()
+ print("paths the terminal asked for:")
+ for path in state.paths():
+ print(f" {path}")
+ encoded = state.encoded_slash_requests()
+ server.shutdown()
+ server.server_close()
+
+ print()
+ if encoded:
+ print(f"REPRODUCED: {len(encoded)} request(s) with an encoded path "
+ f"separator, e.g. {encoded[0]}")
+ print("A reverse proxy that does not decode encoded slashes -- Apache "
+ "with its default AllowEncodedSlashes Off -- answers 404 for "
+ "that, and the terminal cannot be configured at all.")
+ return 0
+ print("not reproduced: every path arrived with real separators.")
+ return 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/pos-simulator/findings/repro_fresh_instance_unusable.py b/pos-simulator/findings/repro_fresh_instance_unusable.py
@@ -0,0 +1,95 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""A freshly provisioned merchant instance cannot be used at all.
+
+An instance with no products and no categories is refused outright -- so a
+merchant who has just created one cannot even charge an amount, which needs no
+inventory.
+
+ cd /tmp/taler-pos-sim/driver && . ../env.sh
+ python3 ../findings/repro_fresh_instance_unusable.py
+
+Exits 0 when the refusal reproduces, 1 when the terminal comes up anyway.
+"""
+
+import os
+import sys
+import threading
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE.parent / "driver"))
+sys.path.insert(0, str(HERE.parent / "backend"))
+
+import mockd
+from device import Device, serial_for
+from pos import Pos
+
+SERIAL = serial_for()
+PORT = int(os.environ.get("POS_MOCK_PORT", "19443"))
+INSTANCE = "freshshop"
+
+
+def main() -> int:
+ print("1. a merchant instance with no categories and no products")
+ server, state = mockd.build_server("fresh", PORT, INSTANCE,
+ f"localhost:{PORT}")
+ threading.Thread(target=server.serve_forever, daemon=True).start()
+ time.sleep(1)
+
+ dev = Device(SERIAL)
+ app = Pos(dev)
+ dev.adb("reverse", f"tcp:{PORT}", f"tcp:{PORT}", check=False)
+
+ print("2. logging the terminal in to it")
+ app.fresh_start()
+ app.provision_by_form(f"localhost:{PORT}", INSTANCE, "mock-secret",
+ expect_success=False)
+
+ print("3. waiting to see where the terminal ends up")
+ dialog = None
+ deadline = time.monotonic() + 60
+ while time.monotonic() < deadline:
+ screen = dev.dump()
+ if screen.find(r"Charge|Create order|Bill|Everything"):
+ break
+ dialog = app.read_dialog(screen)
+ if dialog:
+ break
+ time.sleep(2)
+
+ screen = dev.dump()
+ print()
+ print(f"paths requested: {state.paths()}")
+ print(f"screen: {screen.texts()[:10]}")
+ server.shutdown()
+ server.server_close()
+
+ print()
+ if dialog:
+ print(f"REPRODUCED: the terminal refused the instance with")
+ print(f" {dialog}")
+ print("An instance with no categories fails OrderManager's "
+ "configuration check (config_error_category), ConfigManager "
+ "treats a receiver error as a configuration failure, and the "
+ "terminal never reaches a screen -- not even the amount keypad, "
+ "which needs no inventory at all.")
+ return 0
+ print("not reproduced: the terminal came up on an order screen.")
+ return 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/pos-simulator/findings/repro_qr_tab_crash.py b/pos-simulator/findings/repro_qr_tab_crash.py
@@ -0,0 +1,97 @@
+# This file is part of GNU Taler
+# (C) 2026 Taler Systems S.A.
+#
+# GNU Taler is free software; you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 3, or (at your option) any later version.
+#
+# GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+"""Selecting the QR configuration tab crashes the terminal.
+
+Four steps from a fresh install: open the app with no configuration, tap
+"QR config", wait for the camera's first frame, and the process is gone.
+
+ cd /tmp/taler-pos-sim/driver && . ../env.sh
+ python3 ../findings/repro_qr_tab_crash.py
+
+Exits 0 when the crash reproduces, 1 when it does not.
+"""
+
+import os
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "driver"))
+
+from device import ADB, PKG, Device, serial_for
+from pos import Pos
+
+SERIAL = serial_for()
+
+
+def main() -> int:
+ dev = Device(SERIAL)
+ app = Pos(dev)
+
+ print("1. a terminal with no configuration")
+ dev.stop()
+ dev.clear_data()
+ dev.grant_camera()
+ dev.launch()
+ screen = dev.wait_for(r"Merchant portal URL", timeout=90)
+ assert screen.find(r"^QR config$"), f"no QR tab: {screen.texts()}"
+
+ print("2. clearing the log so the crash cannot be confused with an older one")
+ dev.logcat(clear=True)
+ time.sleep(1)
+
+ print("3. tapping 'QR config'")
+ node = screen.find(r"^QR config$")
+ dev.tap_node(node, screen)
+
+ print("4. waiting for the camera's first frame")
+ time.sleep(10)
+
+ after = dev.dump()
+ # The default buffer set, not "-b crash": the crash buffer is empty on the
+ # emulator images this runs on, and naming it explicitly returns nothing at
+ # all -- which reads as "the app did not crash" while the launcher is on
+ # screen because it did.
+ log = subprocess.run([ADB, "-s", SERIAL, "logcat", "-d"],
+ capture_output=True, text=True).stdout
+ lines = log.splitlines()
+ crash = ""
+ for i, line in enumerate(lines):
+ if "FATAL EXCEPTION" in line:
+ block = "\n".join(lines[i:i + 16])
+ if PKG in block:
+ crash = block
+ break
+
+ print()
+ print(f"activity now: {after.activity}")
+ print(f"screen now: {after.texts()[:8]}")
+ if crash:
+ print()
+ print(crash)
+ print()
+ print("REPRODUCED: the QR configuration tab crashed the terminal.")
+ return 0
+ print()
+ print("not reproduced: the terminal survived the QR tab. Either this is a "
+ "patched build, or this device's camera reports a rotation of 0 or "
+ "180 degrees -- check "
+ "'logcat -d | grep rotationDegrees' and the AVD's hw.camera.back.")
+ return 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/pos-simulator/findings/serialization-error-shown-to-the-cashier.md b/pos-simulator/findings/serialization-error-shown-to-the-cashier.md
@@ -0,0 +1,97 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# A missing field is reported to the cashier by its Kotlin type name
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+A backend reply that is missing a field the terminal needs puts this on the
+counter:
+
+```
+Error fetching the order history
+Illegal input: Field 'orders' is required for type with serial name
+'net.taler.merchantlib.OrderHistory', but it was missing at path: $
+```
+
+That is kotlinx.serialization's own wording, shown verbatim. It names a Kotlin
+class, a serial name and a JSON path, none of which mean anything to the person
+holding the till, and it does not say the one thing that does: the backend sent
+something the terminal could not read, and retrying or checking the backend is
+what to do about it.
+
+## Why it happens
+
+`merchant-lib/src/main/java/net/taler/merchantlib/Response.kt`:
+
+```kotlin
+private suspend fun getFailureString(failure: Failure): String =
+ when (val exception = failure.exception) {
+ is ResponseException -> getExceptionString(exception)
+ is UnknownHostException, ... -> NETWORK_ERROR_MESSAGE
+ is IOException -> exception.message?.takeIf(String::isNotBlank)
+ ?: NETWORK_ERROR_MESSAGE
+ else -> exception.message?.takeIf(String::isNotBlank)
+ ?: exception.toString()
+ }
+```
+
+A `SerializationException` is none of the named types, so it takes the `else`
+arm and its `message` goes straight to the dialog. The status was 200 and the
+body was JSON; only its *shape* was wrong, which is the one failure mode that
+has no sentence of its own.
+
+This is the same arm that
+[a cut connection](transport-error-shows-the-library-wording.md) reaches, and
+the two want the same kind of fix: a sentence the terminal owns, with the
+library's text kept for the log rather than the screen.
+
+## How it was found
+
+`taler-twister` in front of the real demo backend, asked to delete one field
+from the next reply:
+
+```python
+c.tw.delete("orders")
+c.app.tap_button(r"Refresh history")
+```
+
+Scenario: `fault_history_unreadable`, which does this three ways -- a truncated
+body, a deleted field, and a character flipped inside a string value. The third
+is the interesting one for a different reason: the JSON still parses, so
+nothing throws and whatever the terminal draws it draws from a value that is
+wrong.
+
+Nothing a correctly behaving backend sends can reach this, and the mock cannot
+produce it either without being written to send a reply it believes in -- which
+is why it took a proxy over a real exchange.
+
+## Severity
+
+Low to medium, and the same judgement as the cut-connection case: nothing is
+lost, the next refresh works. What is wrong is that an internal type name is
+the error message. It also tells anyone looking over the counter what the app
+is built out of, which is not a serious disclosure but is not nothing either.
+
+## Suggested fix
+
+Give the deserialization failure its own arm, next to the network one:
+
+```kotlin
+is SerializationException -> MALFORMED_REPLY_MESSAGE
+```
+
+with the exception's own text logged rather than displayed.
diff --git a/pos-simulator/findings/setup-uri-drops-the-port.md b/pos-simulator/findings/setup-uri-drops-the-port.md
@@ -0,0 +1,89 @@
+# A `taler-pos://` setup URI loses the backend's port
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+**Severity:** medium -- a merchant whose backend does not listen on 443 cannot
+provision a terminal by QR code at all. The terminal silently configures itself
+for the wrong address and then reports a connection error, which looks like the
+backend being down.
+
+**Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/MainActivity.kt`,
+`handleSetupIntent`.
+
+**Found by:** `pos-simulator`, scenario `provision_port_is_dropped`.
+
+## What happens
+
+Deliver a setup URI that names a port:
+
+```
+taler-pos://backend.demo.taler.net:443/instances/sandbox#secret-token:...
+```
+
+The terminal configures itself for
+
+```
+https://backend.demo.taler.net/instances/sandbox
+```
+
+The port is gone. With `:443` that is harmless, because 443 is what https means
+anyway -- which is exactly why it is easy to miss. With any other port the
+terminal is now pointed somewhere else entirely.
+
+## Why
+
+```kotlin
+val host = data.host ?: return
+...
+val merchantUrl = Uri.Builder()
+ .scheme("https")
+ .encodedAuthority(host)
+ .appendPath("instances")
+ .appendPath(instance)
+ .build()
+ .toString()
+```
+
+`Uri.getHost()` returns the host *without* the port; the authority is
+`getAuthority()` (or `getHost()` plus `getPort()`). So `encodedAuthority(host)`
+rebuilds the URL with the port dropped.
+
+The login form does not have this problem -- `sanitizeMerchantUrlAndUpdateFields`
+keeps the port explicitly:
+
+```kotlin
+val port = if (uri.port != -1) ":${uri.port}" else ""
+val baseHost = "$host$port"
+```
+
+so the two provisioning paths disagree about the same input. That is also why
+the simulator's mock-backend scenarios provision through the form: a mock on
+`localhost:19443` is unreachable through a setup URI.
+
+## Reproducing it
+
+```bash
+cd /tmp/taler-pos-sim/driver && . ../env.sh
+python3 suite.py provision_port_is_dropped
+```
+
+Or by hand: `adb shell am start -a android.intent.action.VIEW -d
+'taler-pos://your-host:8443/instances/x#your-token'` and read the merchant URL
+back off the Settings screen's About block.
+
+## The fix
+
+`encodedAuthority(data.encodedAuthority)` instead of
+`encodedAuthority(host)` -- `data` is the `taler-pos://` URI and its authority
+is exactly the `host:port` the back office put in the QR code. (`host` is still
+needed above it for the `return` that rejects a URI with no host at all.)
+
+Worth checking at the same time: the scheme is hard-coded to `https`, so a
+backend reachable only over http cannot be provisioned either way. That is a
+defensible policy for a payment terminal, but it is a policy rather than an
+oversight, and it is the reason the simulator's own mock backend has to answer
+TLS.
+
+No patch: a one-line change, but which spelling is wanted depends on whether a
+non-default port is meant to be supported at all, which is a decision rather
+than a bug fix.
diff --git a/pos-simulator/findings/transport-error-shows-the-library-wording.md b/pos-simulator/findings/transport-error-shows-the-library-wording.md
@@ -0,0 +1,101 @@
+<!--
+ This file is part of GNU Taler
+ (C) 2026 Taler Systems S.A.
+
+ GNU Taler is free software; you can redistribute it and/or modify it under the
+ terms of the GNU General Public License as published by the Free Software
+ Foundation; either version 3, or (at your option) any later version.
+
+ GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ GNU Taler; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+-->
+
+# A connection that dies mid-response is reported in the HTTP engine's words
+
+> **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it.
+
+A cashier refreshing the order history over a connection that closes halfway
+through the reply is shown
+
+```
+Error fetching the order history
+unexpected end of stream
+```
+
+"unexpected end of stream" is OkHttp's phrasing of a truncated HTTP/1.1
+response. It is not a sentence anybody wrote for a cashier, it names nothing
+the cashier can act on, and `merchant-lib` already has the sentence that
+should be there.
+
+## Why it happens
+
+`merchant-lib/src/main/java/net/taler/merchantlib/Response.kt`:
+
+```kotlin
+private suspend fun getFailureString(failure: Failure): String =
+ when (val exception = failure.exception) {
+ is ResponseException -> getExceptionString(exception)
+ is UnknownHostException,
+ is UnresolvedAddressException,
+ is ConnectException,
+ is SocketTimeoutException -> NETWORK_ERROR_MESSAGE
+ is IOException -> exception.message?.takeIf(String::isNotBlank)
+ ?: NETWORK_ERROR_MESSAGE
+ else -> ...
+ }
+```
+
+Four exception types get `NETWORK_ERROR_MESSAGE` -- "Network error: check your
+internet connection and merchant URL." Every *other* `IOException` prefers
+`exception.message`, and a truncated response is exactly that: an
+`IOException` whose message comes from the engine. The four that are named are
+the four that happen *before* any bytes arrive; the ones that happen in the
+middle of a transfer are the ones that fall through.
+
+The arm is not dead code to be deleted -- some `IOException` messages are worth
+showing. But the ordering is the wrong way round for the commonest member of
+the class.
+
+## How it was found
+
+`driver/faults.py`'s TLS front, which terminates TLS in front of
+`taler-twister` so the terminal can reach it at all, also injects what twister
+has no notion of because it happens below HTTP. Its `cut` mode forwards the
+response headers and then closes the connection partway through the body:
+
+```python
+with c.front.transport("cut"):
+ c.app.tap_button(r"Refresh history")
+```
+
+Scenario: `fault_login_connection_cut`.
+
+Nothing else in the harness reaches this. A status code lands in
+`getExceptionString`; an unreachable host raises `ConnectException`, which is
+one of the four that are named; a backend that never answers raises
+`SocketTimeoutException`, which is another. Only a transfer that starts and
+does not finish gets here.
+
+## Severity
+
+Low to medium. Nothing is lost and the retry works -- the scenario checks that
+the next refresh fills the list again, and it does. What is wrong is the
+message: a cashier on a flaky counter network sees a phrase from an HTTP
+library instead of being told to check the network, which is the whole point of
+having the string.
+
+## Suggested fix
+
+Treat a mid-transfer `IOException` as a network error, and keep the message
+only where it adds something:
+
+```kotlin
+is IOException -> NETWORK_ERROR_MESSAGE
+```
+
+or, if an engine message is worth keeping for the unusual cases, put
+`NETWORK_ERROR_MESSAGE` in front of it rather than behind it.
diff --git a/pos-simulator/tls/.gitignore b/pos-simulator/tls/.gitignore
@@ -0,0 +1,9 @@
+# The CA's private key and the server key never leave the host they were
+# generated on. The certificates are committed because the "sim" build type
+# compiles ca.crt in as a trust anchor, and a certificate without its key
+# authorises nobody.
+ca.key
+srv.key
+srv.csr
+srv.pem
+ca.srl
diff --git a/pos-simulator/tls/README.md b/pos-simulator/tls/README.md
@@ -0,0 +1,38 @@
+# The simulator's own CA
+
+The terminal builds every merchant URL with a hard-coded `https://` scheme --
+`ConfigFragment.sanitizeMerchantUrlAndUpdateFields` and
+`MainActivity.handleSetupIntent` both -- so a merchant backend the harness
+controls has to answer TLS. Patching that out of the app would mean testing
+something other than the app, so instead the `sim` build type carries one extra
+trust anchor and `backend/mockd.py` serves under it.
+
+What is in the tree:
+
+| File | What it is |
+| --- | --- |
+| `ca.crt` | the CA certificate, also copied to `merchant-terminal/src/sim/res/raw/sim_ca.crt` |
+| `srv.crt` | a certificate for `localhost`, signed by that CA |
+| `srv.ext` | the SAN/extension file used to sign it |
+
+What is **not**, and must not be: `ca.key`, `srv.key`, `srv.csr`, `srv.pem`,
+`ca.srl`. They are generated per installation and `.gitignore`d. A certificate
+without its private key authorises nobody, which is why shipping `ca.crt` in a
+never-published debug build type is safe.
+
+To generate a set on a new host:
+
+```bash
+openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt -days 3650 \
+ -subj '/CN=Taler POS simulator CA/O=GNU Taler/OU=pos-simulator' \
+ -addext 'basicConstraints=critical,CA:TRUE' \
+ -addext 'keyUsage=critical,keyCertSign,cRLSign'
+openssl req -newkey rsa:2048 -nodes -keyout srv.key -out srv.csr \
+ -subj '/CN=localhost'
+openssl x509 -req -in srv.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
+ -out srv.crt -days 3650 -extfile srv.ext
+cp ca.crt ../../merchant-terminal/src/sim/res/raw/sim_ca.crt
+```
+
+and rebuild the APK: the trust anchor is compiled into it, so a new CA means a
+new build.
diff --git a/pos-simulator/tls/ca.crt b/pos-simulator/tls/ca.crt
@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDizCCAnOgAwIBAgIUBcwRvFUuVsajhrVa7ULaBCH41Y4wDQYJKoZIhvcNAQEL
+BQAwTTEfMB0GA1UEAwwWVGFsZXIgUE9TIHNpbXVsYXRvciBDQTESMBAGA1UECgwJ
+R05VIFRhbGVyMRYwFAYDVQQLDA1wb3Mtc2ltdWxhdG9yMB4XDTI2MTAyOTA4NTAw
+NloXDTM2MTAyNjA4NTAwNlowTTEfMB0GA1UEAwwWVGFsZXIgUE9TIHNpbXVsYXRv
+ciBDQTESMBAGA1UECgwJR05VIFRhbGVyMRYwFAYDVQQLDA1wb3Mtc2ltdWxhdG9y
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy1836CaICQy2ZPD7mXxz
+tSsYIcCK9J5AxOEEZ7+wJUOHXmTO95YGyBUm1UjClQD8K1l8q6EF8QA+wRN7tcEJ
+WfpLXM2yNBGM+K+pgi4Q+dRQ2VzgdrPwg7VNe5IDW1mfUb/in7J8KpujfS1xTHlO
+pTZhWYhjgDZZ0s2kiIRq9nRvmHxowxqCtKYarS5p4N6wOX+Fdl1GkkU8+LwUve89
+mz/E5AD5YpS+DDu20IAu7wpJLJjW99JwtAIwYyaWmWqnKCZjiq46kNSTZ9aYC9z0
+c3SGVKjmOq3y1yHj+1jQassPEhmh5C38xPGG2xGM6lv8CuCsj1GZl/5Ii87M93I1
+hwIDAQABo2MwYTAdBgNVHQ4EFgQUwyWynf2xYyHKwo+cwyW4rW+TWsAwHwYDVR0j
+BBgwFoAUwyWynf2xYyHKwo+cwyW4rW+TWsAwDwYDVR0TAQH/BAUwAwEB/zAOBgNV
+HQ8BAf8EBAMCAQYwDQYJKoZIhvcNAQELBQADggEBAH/TGHkLCk1srBN9MJZIC+jM
+7kSeluyAS8jOTTHD7KfTyskCzIbGh7I2YLxOvMAHY5+a3V1rKyEZaxmTxK66tMPZ
+g9cCzHssWI5ZHopaPc57D1CqIcCJuoFIxxNwv9YzIsft9Jwk0LHj+vplCiyhfZrP
+zsXeFH0YWkfGm1Q5GZIAN6SB99rVvDPV0OE/WmpLO4i5gc55KPqaRFFOGi3ZgSOr
+lmB375sk9K2Z3q+AqZgf3qIecChQLOD25PjX6TVS17r7gGXl/WC3YG/WkN+WM/hA
+QinLnOWBMwCm/gXbLpcKMQqWYF52yxOuanh+fX2LEqP0ZDGYg1MlmSOj0GrfdDM=
+-----END CERTIFICATE-----
diff --git a/pos-simulator/tls/srv.crt b/pos-simulator/tls/srv.crt
@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDijCCAnKgAwIBAgIUX1lsiPcIb1EAFC+DPjdF8HCOB8kwDQYJKoZIhvcNAQEL
+BQAwTTEfMB0GA1UEAwwWVGFsZXIgUE9TIHNpbXVsYXRvciBDQTESMBAGA1UECgwJ
+R05VIFRhbGVyMRYwFAYDVQQLDA1wb3Mtc2ltdWxhdG9yMB4XDTI2MTAyOTA4NTAw
+NloXDTM2MTAyNjA4NTAwNlowFDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkq
+hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsT9LtRVVFDWLYEatxvUHb9BnYrhAFa9e
+5tSCxW+JBKDbdae21W6pb85ErW66Rhn4OFbZnrkCMFa8qjMINMMoRnIEt1vaG1ZI
+2kODF+Wi0GfgmxygrGlMDPWKNgAgFmDDz9pfh8BF5VyRHodYIdrZ6av/B6/QQVT8
+XWvmJUaIp/mVp81KgG1F3VSvDqUrZqQVCA8G6E0h4oCyB5OKwY0w5xRk9RHqLiKz
+Mv5tVVcRuwYBh6JEP9Wbn1d4bwmHZV3BHHEFHCZSegyY7rOWaXmtxe/RxTRxEh0Z
+jlyq3wMeRrcPHaOgYVlvtcgTpbVR6jfpHUEgorv5Pf1+OcSw2b1/JQIDAQABo4Ga
+MIGXMDAGA1UdEQQpMCeCCWxvY2FsaG9zdIIOcG9zLW1vY2subG9jYWyHBH8AAAGH
+BAoAAgIwDgYDVR0PAQH/BAQDAgWgMBMGA1UdJQQMMAoGCCsGAQUFBwMBMB0GA1Ud
+DgQWBBQBGmLIMtqtYiyGTL1ryRVYaxxgnjAfBgNVHSMEGDAWgBTDJbKd/bFjIcrC
+j5zDJbitb5NawDANBgkqhkiG9w0BAQsFAAOCAQEAosWcjvHQwRyShcrDMUgCO/ka
+KmZeg06wwS1l/JB4V6VVI0YQraOLFYRpjanKKj2kWLGItCEoEX6ryE++oiPE1gFQ
+8/0MpNCjvu3yPuj5vgNwj7xwgcPNMU7tRSOk9Np3TvPI4FnHoZTPKeUKbjA6VDX3
+82Z/WYkqypqZmbikoF1Ns35OgIhnemeSSzTumRq3zC4qpw0ZpZ/mEj4YBs3rHya0
+CipVvWMd/Xn2zz09smveCg9ICQyilQnc8gph1iXYCKHUFlCmSgEewjxeLGQJ3xKF
+bJ83v5i7z4pjdw+7MawP635J6l7HkN4yS3QsMiJOUZiOHWYlPV0KDVgwo0EBaQ==
+-----END CERTIFICATE-----
diff --git a/pos-simulator/tls/srv.ext b/pos-simulator/tls/srv.ext
@@ -0,0 +1,3 @@
+subjectAltName = DNS:localhost, DNS:pos-mock.local, IP:127.0.0.1, IP:10.0.2.2
+keyUsage = critical,digitalSignature,keyEncipherment
+extendedKeyUsage = serverAuth
diff --git a/taler-kotlin-android/build.gradle b/taler-kotlin-android/build.gradle
@@ -39,6 +39,10 @@ android {
debug {
minifyEnabled minify_debug
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+ // Unit-test coverage, so that contrib/ci/jobs/5-coverage can
+ // report this module on lcov.taler.net. Costs nothing when the
+ // tests are not run.
+ enableUnitTestCoverage true
}
}
diff --git a/wallet/build.gradle b/wallet/build.gradle
@@ -55,6 +55,10 @@ android {
minifyEnabled minify_debug
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
applicationIdSuffix ".debug"
+ // Unit-test coverage, so that contrib/ci/jobs/5-coverage can
+ // report this module on lcov.taler.net. Costs nothing when the
+ // tests are not run.
+ enableUnitTestCoverage true
}
}
flavorDimensions = ["distributionChannel"]