@1aboveio/skills 1.0.16 → 1.0.18

package/skills/app-dev/maestro/scripts/test_maestro_failure.py

@@ -0,0 +1,710 @@
+"""Focused tests for maestro_failure.py: fixture Maestro output, no device, no Maestro.
+
+The fixtures are the artifact layout Maestro's docs describe for a Flow folder
+(manifest.json, commands.json, screenshots/, screen-hierarchy/, logs/), with the
+commands.json entry shape taken from Maestro's source (TestOutputWriter and
+CommandDebugMetadata) because the docs name the fields but show no example.
+
+Run directly (`python3 test_maestro_failure.py`) or through
+`maestro-failure.test.mjs`, which is what CI discovers.
+"""
+
+import contextlib
+import io
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+
+from failure_record import NATIVE_FAILURE_PREFIX, RECORD_KEYS, RECORD_NAME, read_record  # noqa: E402
+from maestro_failure import (  # noqa: E402
+    COMMANDS_JSON,
+    MaestroOutputError,
+    convert,
+    describe_command,
+    error_text,
+    main,
+)
+
+CONVERTER = os.path.join(HERE, "maestro_failure.py")
+
+SESSION = "2026-07-31_173617"
+FLOW = "checkout_flow"
+CASE = "checkout smoke"
+
+LAUNCHED = {
+    "command": {"launchAppCommand": {"appId": "com.example.app", "optional": False}},
+    "metadata": {
+        "status": "COMPLETED",
+        "timestamp": 1700000000000,
+        "duration": 1200,
+        "sequenceNumber": 0,
+        "depth": 0,
+    },
+}
+
+TAPPED = {
+    "command": {
+        "tapOnElement": {
+            "selector": {"text": "Pay", "optional": False},
+            "label": "Tap Pay",
+            "optional": False,
+        }
+    },
+    "metadata": {
+        "status": "COMPLETED",
+        "timestamp": 1700000001300,
+        "duration": 300,
+        "sequenceNumber": 1,
+        "depth": 0,
+    },
+}
+
+FAILED_RECEIPT = {
+    "command": {
+        "assertConditionCommand": {
+            "condition": {"visible": {"text": "Thank you", "optional": False}},
+            "optional": False,
+        }
+    },
+    "metadata": {
+        "status": "FAILED",
+        "timestamp": 1700000001700,
+        "duration": 30000,
+        "sequenceNumber": 2,
+        "depth": 0,
+        "error": {
+            "message": 'Assertion is false: "Thank you" is visible',
+            "debugMessage": "Screen hierarchy has no match",
+        },
+        "artifacts": [
+            {"type": "SCREEN_HIERARCHY", "path": "screen-hierarchy/step-003-assertCondition.json"},
+            {"type": "SCREENSHOT", "path": "screenshots/step-003-assertCondition.png"},
+        ],
+    },
+}
+
+
+class MaestroOutputCase(unittest.TestCase):
+    def setUp(self):
+        self.directory = tempfile.TemporaryDirectory()
+        self.root = self.directory.name
+        self.output = io.StringIO()
+
+    def tearDown(self):
+        self.directory.cleanup()
+
+    def write(self, relative, payload):
+        path = os.path.join(self.root, relative)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        if isinstance(payload, bytes):
+            with open(path, "wb") as stream:
+                stream.write(payload)
+        else:
+            with open(path, "w", encoding="utf-8") as stream:
+                stream.write(payload)
+        return path
+
+    def write_json(self, relative, payload):
+        return self.write(relative, json.dumps(payload, indent=2))
+
+    def flow(self, steps, name=FLOW, session=SESSION, artifacts=None, manifest=True):
+        """A Flow folder with `steps` in commands.json and the optional artifact files."""
+        base = os.path.join(session, name) if session else name
+        self.write_json(os.path.join(base, "commands.json"), steps)
+        if manifest:
+            self.write_json(
+                os.path.join(base, "manifest.json"),
+                {
+                    "$schema": "https://storage.googleapis.com/maestro-schemas/artifact-manifest/v1.schema.json",
+                    "entries": [
+                        {"kind": "COMMAND_METADATA", "format": "JSON", "relativePath": "commands.json"}
+                    ],
+                },
+            )
+        for relative, payload in (artifacts or {}).items():
+            self.write(os.path.join(base, relative), payload)
+        return os.path.join(self.root, base)
+
+    def failing_flow(self, name=FLOW, session=SESSION):
+        """The worked example: a launch and tap that passed, then a failed assertion."""
+        return self.flow(
+            [LAUNCHED, TAPPED, FAILED_RECEIPT],
+            name=name,
+            session=session,
+            artifacts={
+                "screenshots/step-003-assertCondition.png": b"\x89PNG\r\n\x1a\n",
+                "screen-hierarchy/step-003-assertCondition.json": '{"attributes": {"text": "Pay now"}}',
+                "logs/device-logcat.txt": "07-31 E ActivityManager: no match\n",
+            },
+        )
+
+    def run_convert(self, maestro_dir, **options):
+        options.setdefault("stream", self.output)
+        return convert(maestro_dir, **options)
+
+    def cli(self, *argv):
+        """Run main() and keep its stderr out of the test output."""
+        with contextlib.redirect_stderr(io.StringIO()):
+            return main(list(argv))
+
+    def cli_result(self, *argv):
+        """Run main() and return (status, stderr, stdout) so a partial conversion is visible."""
+        stderr = io.StringIO()
+        stdout = io.StringIO()
+        with contextlib.redirect_stderr(stderr), contextlib.redirect_stdout(stdout):
+            status = main(list(argv))
+        return status, stderr.getvalue(), stdout.getvalue()
+
+    def record(self, evidence_dir):
+        path = os.path.join(evidence_dir, RECORD_NAME)
+        self.assertTrue(os.path.isfile(path), path)
+        with open(path, encoding="utf-8") as stream:
+            return json.load(stream)
+
+    def lines(self):
+        return [line for line in self.output.getvalue().splitlines() if line]
+
+
+class FailingFlowTest(MaestroOutputCase):
+    def test_the_failing_step_becomes_the_record_and_the_line(self):
+        flow_dir = self.failing_flow()
+        failure = self.run_convert(flow_dir)
+
+        self.assertIsNotNone(failure)
+        record = self.record(flow_dir)
+        self.assertEqual(list(record), list(RECORD_KEYS))
+        self.assertEqual(record["case"], FLOW)
+        self.assertEqual(record["step"], 'Assert condition "Thank you"')
+        self.assertEqual(
+            record["error"],
+            'Assertion is false: "Thank you" is visible: Screen hierarchy has no match',
+        )
+        self.assertEqual(record["screenshot"], "screenshots/step-003-assertCondition.png")
+        self.assertEqual(record["uiDump"], "screen-hierarchy/step-003-assertCondition.json")
+        self.assertEqual(record["logcatTail"], "logs/device-logcat.txt")
+        self.assertEqual(record["evidenceDir"], flow_dir)
+        self.assertEqual(record["cleanupErrors"], [])
+        for name in (record["screenshot"], record["uiDump"], record["logcatTail"]):
+            self.assertTrue(os.path.isfile(os.path.join(flow_dir, name)), name)
+
+        lines = self.lines()
+        self.assertEqual(len(lines), 1)
+        self.assertTrue(lines[0].startswith(NATIVE_FAILURE_PREFIX))
+        self.assertEqual(
+            json.loads(lines[0][len(NATIVE_FAILURE_PREFIX) :]),
+            {
+                "case": FLOW,
+                "step": 'Assert condition "Thank you"',
+                "error": record["error"],
+                "evidenceDir": flow_dir,
+            },
+        )
+
+    def test_an_explicit_case_name_is_used(self):
+        flow_dir = self.failing_flow()
+        self.run_convert(flow_dir, case=CASE)
+        self.assertEqual(self.record(flow_dir)["case"], CASE)
+
+    def test_a_labelled_step_uses_the_label(self):
+        labelled = json.loads(json.dumps(FAILED_RECEIPT))
+        labelled["command"] = {
+            "tapOnElement": {
+                "selector": {"text": "Pay", "optional": False},
+                "label": "Tap Pay",
+                "optional": False,
+            }
+        }
+        flow_dir = self.flow([TAPPED, labelled])
+        self.run_convert(flow_dir)
+        self.assertEqual(self.record(flow_dir)["step"], "Tap Pay")
+
+    def test_the_failing_step_wins_over_a_later_one(self):
+        later = json.loads(json.dumps(FAILED_RECEIPT))
+        later["metadata"]["timestamp"] = 1700000009000
+        later["metadata"]["sequenceNumber"] = 3
+        later["metadata"]["error"] = {"message": "second failure"}
+        later["metadata"]["artifacts"] = [
+            {"type": "SCREENSHOT", "path": "screenshots/step-004-tapOnElement.png"}
+        ]
+        flow_dir = self.flow(
+            [TAPPED, FAILED_RECEIPT, later],
+            artifacts={"screenshots/step-003-assertCondition.png": b"png"},
+        )
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertEqual(record["step"], 'Assert condition "Thank you"')
+        self.assertIn("Assertion is false", record["error"])
+        self.assertEqual(record["screenshot"], "screenshots/step-003-assertCondition.png")
+
+
+class PassingFlowTest(MaestroOutputCase):
+    def test_a_passing_flow_writes_nothing(self):
+        flow_dir = self.flow(
+            [LAUNCHED, TAPPED],
+            artifacts={"logs/device-logcat.txt": "07-31 I ActivityManager: clean\n"},
+        )
+        self.assertIsNone(self.run_convert(flow_dir))
+        self.assertFalse(os.path.exists(os.path.join(flow_dir, RECORD_NAME)))
+        self.assertEqual(self.output.getvalue(), "")
+
+    def test_a_flow_with_no_steps_writes_nothing(self):
+        flow_dir = self.flow([])
+        self.assertIsNone(self.run_convert(flow_dir))
+        self.assertEqual(self.output.getvalue(), "")
+
+    def test_a_folder_without_commands_json_is_not_converted(self):
+        self.write(os.path.join(SESSION, FLOW, "manifest.json"), "{}")
+        with self.assertRaises(MaestroOutputError):
+            self.run_convert(os.path.join(self.root, SESSION))
+        self.assertEqual(self.cli("--maestro-dir", os.path.join(self.root, SESSION)), 2)
+
+    def test_a_missing_folder_is_a_usage_error(self):
+        self.assertEqual(self.cli("--maestro-dir", os.path.join(self.root, "absent")), 2)
+
+
+class ExistingRecordTest(MaestroOutputCase):
+    def test_an_existing_record_is_kept_and_its_line_is_printed(self):
+        flow_dir = self.failing_flow()
+        kept = {
+            "case": CASE,
+            "step": "tap Pay",
+            "error": "RuntimeError: earlier failure",
+            "screenshot": None,
+            "uiDump": None,
+            "logcatTail": None,
+            "evidenceDir": flow_dir,
+            "cleanupErrors": [],
+        }
+        path = self.write_json(os.path.join(SESSION, FLOW, RECORD_NAME), kept)
+
+        failure = self.run_convert(flow_dir)
+
+        self.assertEqual(failure.case, CASE)
+        self.assertEqual(self.record(flow_dir), kept)
+        with open(path, encoding="utf-8") as stream:
+            self.assertIn("earlier failure", stream.read())
+        self.assertEqual(self.lines(), [failure.native_failure_line()])
+
+    def test_a_record_already_in_an_override_evidence_dir_is_kept(self):
+        flow_dir = self.failing_flow()
+        evidence_dir = os.path.join(self.root, "run-evidence")
+        kept = {"case": CASE, "step": None, "error": "RuntimeError: earlier failure", "cleanupErrors": []}
+        self.write_json(os.path.join("run-evidence", RECORD_NAME), kept)
+
+        self.run_convert(flow_dir, evidence_dir=evidence_dir)
+
+        self.assertEqual(self.record(evidence_dir)["error"], "RuntimeError: earlier failure")
+        # The first failure owns the folder, so no Maestro artifact was copied into it.
+        self.assertFalse(os.path.exists(os.path.join(evidence_dir, "screenshots")))
+
+
+class MissingOptionalFilesTest(MaestroOutputCase):
+    def test_absent_artifacts_are_null_and_noted_without_losing_the_error(self):
+        flow_dir = self.flow([TAPPED, FAILED_RECEIPT], manifest=False)
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertIsNone(record["screenshot"])
+        self.assertIsNone(record["uiDump"])
+        self.assertIsNone(record["logcatTail"])
+        self.assertEqual(record["step"], 'Assert condition "Thank you"')
+        self.assertIn("Assertion is false", record["error"])
+        self.assertEqual(len(record["cleanupErrors"]), 3)
+        self.assertTrue(record["cleanupErrors"][0].startswith("screenshot: "))
+        self.assertTrue(record["cleanupErrors"][1].startswith("uiDump: "))
+        self.assertTrue(record["cleanupErrors"][2].startswith("logcatTail: "))
+
+    def test_the_error_survives_a_listed_artifact_that_is_not_on_disk(self):
+        broken = json.loads(json.dumps(FAILED_RECEIPT))
+        broken["metadata"]["artifacts"] = [
+            {"type": "SCREENSHOT", "path": "screenshots/step-003-assertCondition.png"}
+        ]
+        flow_dir = self.flow([broken], artifacts={"logs/device-logcat.txt": "log\n"})
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertIsNone(record["screenshot"])
+        self.assertEqual(record["logcatTail"], "logs/device-logcat.txt")
+        self.assertIn(
+            "screenshots/step-003-assertCondition.png is not in the Maestro output",
+            " ".join(record["cleanupErrors"]),
+        )
+        self.assertIn("Assertion is false", record["error"])
+
+    def test_an_unreadable_commands_json_is_not_silently_a_pass(self):
+        flow_dir = self.flow([FAILED_RECEIPT])
+        self.write(os.path.join(SESSION, FLOW, "commands.json"), "{not json")
+        with self.assertRaises(MaestroOutputError):
+            self.run_convert(flow_dir)
+
+
+class UnsafeArtifactPathTest(MaestroOutputCase):
+    """A path Maestro names is read and copied only inside the two folders involved."""
+
+    def refused(self, record, reason="outside the Maestro output"):
+        self.assertIsNone(record["screenshot"])
+        self.assertIn("Assertion is false", record["error"])
+        self.assertTrue(
+            any(
+                note.startswith("screenshot: ") and reason in note
+                for note in record["cleanupErrors"]
+            ),
+            record["cleanupErrors"],
+        )
+
+    def failing_flow_listing(self, artifacts):
+        """The worked example, with the failing step naming `artifacts` instead."""
+        listed = json.loads(json.dumps(FAILED_RECEIPT))
+        listed["metadata"]["artifacts"] = artifacts
+        return self.flow([listed], artifacts={"logs/device-logcat.txt": "log\n"})
+
+    def test_an_absolute_artifact_path_is_not_read(self):
+        outside = self.write("outside.png", b"secret")
+        flow_dir = self.failing_flow_listing([{"type": "SCREENSHOT", "path": outside}])
+
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.refused(record)
+        self.assertEqual(record["logcatTail"], "logs/device-logcat.txt")
+
+    def test_a_traversal_artifact_path_does_not_escape_the_evidence_folder(self):
+        self.write(os.path.join(SESSION, "outside.png"), b"secret")
+        flow_dir = self.failing_flow_listing(
+            [{"type": "SCREENSHOT", "path": "../outside.png"}]
+        )
+        evidence_dir = os.path.join(self.root, "run-evidence")
+
+        self.run_convert(flow_dir, evidence_dir=evidence_dir)
+
+        self.refused(self.record(evidence_dir))
+        self.assertFalse(os.path.exists(os.path.join(self.root, "outside.png")))
+
+    def test_an_artifact_behind_an_outside_symlink_is_refused(self):
+        outside = os.path.join(self.root, "outside")
+        os.makedirs(outside)
+        with open(os.path.join(outside, "step-003-assertCondition.png"), "wb") as stream:
+            stream.write(b"secret")
+        flow_dir = self.failing_flow_listing(
+            [{"type": "SCREENSHOT", "path": "screenshots/step-003-assertCondition.png"}]
+        )
+        os.symlink(outside, os.path.join(flow_dir, "screenshots"))
+        evidence_dir = os.path.join(self.root, "run-evidence")
+
+        self.run_convert(flow_dir, evidence_dir=evidence_dir)
+
+        self.refused(self.record(evidence_dir))
+        self.assertFalse(os.path.exists(os.path.join(evidence_dir, "screenshots")))
+
+    def test_an_evidence_folder_symlink_outside_is_refused(self):
+        outside = os.path.join(self.root, "outside")
+        os.makedirs(outside)
+        evidence_dir = os.path.join(self.root, "run-evidence")
+        os.makedirs(evidence_dir)
+        os.symlink(outside, os.path.join(evidence_dir, "screenshots"))
+        flow_dir = self.failing_flow()
+
+        self.run_convert(flow_dir, evidence_dir=evidence_dir)
+
+        record = self.record(evidence_dir)
+        self.refused(record, reason="would leave the evidence folder")
+        self.assertEqual(os.listdir(outside), [])
+        self.assertEqual(record["uiDump"], "screen-hierarchy/step-003-assertCondition.json")
+        self.assertEqual(record["logcatTail"], "logs/device-logcat.txt")
+
+
+class CommandsValidationTest(MaestroOutputCase):
+    """Entries the converter cannot read are an error, never a silent pass."""
+
+    def test_a_list_holding_a_non_object_entry_is_not_a_pass(self):
+        flow_dir = self.flow([42])
+
+        with self.assertRaisesRegex(MaestroOutputError, "entry 0 is not an object"):
+            self.run_convert(flow_dir)
+
+        self.assertEqual(self.cli("--maestro-dir", flow_dir), 2)
+        self.assertFalse(os.path.exists(os.path.join(flow_dir, RECORD_NAME)))
+
+    def test_an_unknown_status_is_not_a_pass(self):
+        unknown = json.loads(json.dumps(FAILED_RECEIPT))
+        unknown["metadata"]["status"] = "ERROR"
+        flow_dir = self.flow([LAUNCHED, unknown])
+
+        with self.assertRaisesRegex(MaestroOutputError, "unsupported status 'ERROR'"):
+            self.run_convert(flow_dir)
+
+        self.assertEqual(self.cli("--maestro-dir", flow_dir), 2)
+        self.assertFalse(os.path.exists(os.path.join(flow_dir, RECORD_NAME)))
+
+    def test_an_empty_command_list_is_still_a_pass(self):
+        flow_dir = self.flow([])
+
+        self.assertIsNone(self.run_convert(flow_dir))
+        self.assertEqual(self.cli("--maestro-dir", flow_dir), 0)
+        self.assertFalse(os.path.exists(os.path.join(flow_dir, RECORD_NAME)))
+
+
+class IncompleteConversionTest(MaestroOutputCase):
+    """A Flow that cannot be read makes the conversion partial, not a pass."""
+
+    def unreadable(self, name):
+        self.flow([LAUNCHED], name=name)
+        return self.write(os.path.join(SESSION, name, COMMANDS_JSON), "{not json")
+
+    def test_a_failing_flow_is_recorded_and_the_unreadable_one_is_reported(self):
+        failing_flow = self.failing_flow()
+        self.unreadable("login_flow")
+        session_dir = os.path.join(self.root, SESSION)
+
+        status, stderr, stdout = self.cli_result("--maestro-dir", session_dir)
+
+        self.assertEqual(status, 2)
+        self.assertIn("incomplete conversion", stderr)
+        self.assertIn("login_flow", stderr)
+        record = self.record(failing_flow)
+        self.assertIn("Assertion is false", record["error"])
+        self.assertTrue(
+            any("unreadable commands.json" in note for note in record["cleanupErrors"]),
+            record["cleanupErrors"],
+        )
+        lines = [line for line in stdout.splitlines() if line]
+        self.assertEqual(len(lines), 1)
+        self.assertTrue(lines[0].startswith(NATIVE_FAILURE_PREFIX))
+
+    def test_every_unreadable_flow_is_reported(self):
+        failing_flow = self.failing_flow()
+        self.unreadable("login_flow")
+        self.unreadable("cart_flow")
+
+        status, stderr, _ = self.cli_result("--maestro-dir", os.path.join(self.root, SESSION))
+
+        self.assertEqual(status, 2)
+        self.assertIn("login_flow", stderr)
+        self.assertIn("cart_flow", stderr)
+        record = self.record(failing_flow)
+        self.assertIn("Assertion is false", record["error"])
+        unreadable = [note for note in record["cleanupErrors"] if "unreadable" in note]
+        self.assertEqual(len(unreadable), 2, record["cleanupErrors"])
+
+    def test_a_session_of_only_unreadable_flows_writes_nothing(self):
+        login = self.unreadable("login_flow")
+        cart = self.unreadable("cart_flow")
+        session_dir = os.path.join(self.root, SESSION)
+
+        with self.assertRaises(MaestroOutputError):
+            self.run_convert(session_dir)
+
+        self.assertEqual(self.cli("--maestro-dir", session_dir), 2)
+        self.assertEqual(self.output.getvalue(), "")
+        for path in (login, cart):
+            self.assertFalse(os.path.exists(os.path.join(os.path.dirname(path), RECORD_NAME)))
+
+    def test_a_malformed_flow_does_not_discard_a_readable_failure(self):
+        failing_flow = self.failing_flow()
+        self.flow([42], name="login_flow")
+        session_dir = os.path.join(self.root, SESSION)
+
+        status, stderr, stdout = self.cli_result("--maestro-dir", session_dir)
+
+        self.assertEqual(status, 2)
+        self.assertIn("entry 0 is not an object", stderr)
+        self.assertIn("incomplete conversion", stderr)
+        record = self.record(failing_flow)
+        self.assertIn("Assertion is false", record["error"])
+        self.assertTrue(any("entry 0 is not an object" in note for note in record["cleanupErrors"]))
+        self.assertEqual(len(stdout.splitlines()), 1)
+
+
+class SessionFolderTest(MaestroOutputCase):
+    def test_the_session_folder_finds_the_failing_flow(self):
+        self.flow([LAUNCHED, TAPPED], name="login_flow")
+        failing_flow = self.failing_flow()
+        session_dir = os.path.join(self.root, SESSION)
+
+        failure = self.run_convert(session_dir)
+
+        self.assertEqual(failure.evidenceDir, failing_flow)
+        self.assertEqual(self.record(failing_flow)["case"], FLOW)
+
+    def test_the_earliest_failing_step_decides(self):
+        earlier = json.loads(json.dumps(FAILED_RECEIPT))
+        earlier["metadata"]["timestamp"] = 1700000000500
+        earlier["metadata"]["error"] = {"message": "earlier failure"}
+        earlier_dir = self.flow([LAUNCHED, earlier], name="login_flow")
+        later_dir = self.failing_flow(name="checkout_flow")
+
+        self.run_convert(os.path.join(self.root, SESSION))
+
+        self.assertEqual(self.record(earlier_dir)["error"], "earlier failure")
+        self.assertFalse(os.path.exists(os.path.join(later_dir, RECORD_NAME)))
+
+    def test_the_output_root_above_the_session_folder_works(self):
+        failing_flow = self.failing_flow()
+        self.run_convert(self.root)
+        self.assertTrue(os.path.isfile(os.path.join(failing_flow, RECORD_NAME)))
+
+
+class EvidenceDirTest(MaestroOutputCase):
+    def test_an_override_evidence_dir_holds_copies_and_relative_names(self):
+        flow_dir = self.failing_flow()
+        evidence_dir = os.path.join(self.root, "run-evidence")
+
+        failure = self.run_convert(flow_dir, evidence_dir=evidence_dir)
+
+        record = self.record(evidence_dir)
+        self.assertEqual(record["evidenceDir"], evidence_dir)
+        self.assertEqual(failure.evidenceDir, evidence_dir)
+        self.assertEqual(record["screenshot"], "screenshots/step-003-assertCondition.png")
+        self.assertEqual(record["uiDump"], "screen-hierarchy/step-003-assertCondition.json")
+        self.assertEqual(record["logcatTail"], "logs/device-logcat.txt")
+        for name in (record["screenshot"], record["uiDump"], record["logcatTail"]):
+            self.assertTrue(os.path.isfile(os.path.join(evidence_dir, name)), name)
+
+
+class DocumentedShapeTest(MaestroOutputCase):
+    def test_the_documented_flat_entry_shape_is_accepted(self):
+        flow_dir = self.flow(
+            [
+                {"command": "launchApp", "status": "COMPLETED", "duration": 1200, "sequenceNumber": 0},
+                {
+                    "command": "tapOn: Pay",
+                    "status": "FAILED",
+                    "duration": 300,
+                    "sequenceNumber": 1,
+                    "error": "Element not found: Pay",
+                    "artifacts": ["screenshots/step-002-tapOn.png"],
+                },
+            ],
+            artifacts={
+                "screenshots/step-002-tapOn.png": b"png",
+                "logs/device-logcat.txt": "log\n",
+            },
+        )
+
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertEqual(record["step"], "tapOn: Pay")
+        self.assertEqual(record["error"], "Element not found: Pay")
+        self.assertEqual(record["screenshot"], "screenshots/step-002-tapOn.png")
+        self.assertEqual(record["uiDump"], None)
+
+    def test_a_step_named_screenshot_is_found_without_an_artifacts_list(self):
+        unlisted = json.loads(json.dumps(FAILED_RECEIPT))
+        del unlisted["metadata"]["artifacts"]
+        unlisted["metadata"]["sequenceNumber"] = 1
+        flow_dir = self.flow(
+            [unlisted],
+            artifacts={
+                "screenshots/step-002-assertCondition.png": b"png",
+                "screen-hierarchy/step-002-assertCondition.json": "{}",
+                "logs/device-logcat.txt": "log\n",
+            },
+        )
+
+        self.run_convert(flow_dir)
+
+        record = self.record(flow_dir)
+        self.assertEqual(record["screenshot"], "screenshots/step-002-assertCondition.png")
+        self.assertEqual(record["uiDump"], "screen-hierarchy/step-002-assertCondition.json")
+
+    def test_an_ios_device_log_is_used_when_there_is_no_logcat(self):
+        flow_dir = self.flow(
+            [FAILED_RECEIPT],
+            artifacts={"logs/device-simulator.log": "simulator log\n"},
+        )
+        self.run_convert(flow_dir)
+        self.assertEqual(self.record(flow_dir)["logcatTail"], "logs/device-simulator.log")
+
+
+class ReadingTest(unittest.TestCase):
+    def test_a_command_without_a_label_reads_as_its_type_and_target(self):
+        self.assertEqual(describe_command({"scrollCommand": {"optional": False}}), "Scroll")
+        self.assertEqual(
+            describe_command({"launchAppCommand": {"appId": "com.example.app"}}),
+            'Launch app "com.example.app"',
+        )
+        self.assertEqual(describe_command("tapOn: Pay"), "tapOn: Pay")
+        self.assertIsNone(describe_command(None))
+
+    def test_error_text_keeps_the_debug_detail(self):
+        self.assertEqual(error_text({"error": "boom"}), "boom")
+        self.assertEqual(
+            error_text({"error": {"message": "boom", "debugMessage": "screen has no Foo"}}),
+            "boom: screen has no Foo",
+        )
+        self.assertEqual(error_text({"error": {"message": "boom"}}), "boom")
+        self.assertEqual(error_text({}), "Maestro marked the step FAILED and gave no error message")
+
+    def test_read_record_ignores_a_non_record(self):
+        with tempfile.TemporaryDirectory() as directory:
+            self.assertIsNone(read_record(directory))
+
+
+def run_python(arguments, cwd):
+    """Run a Python command with no inherited PYTHONPATH, so imports come from `arguments`."""
+    environment = {key: value for key, value in os.environ.items() if key != "PYTHONPATH"}
+    return subprocess.run(
+        [sys.executable, *arguments],
+        cwd=cwd,
+        env=environment,
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+
+
+class CommandLineTest(MaestroOutputCase):
+    def test_the_command_line_converts_from_another_working_directory(self):
+        flow_dir = self.failing_flow()
+        elsewhere = os.path.join(self.root, "elsewhere")
+        os.makedirs(elsewhere)
+
+        result = run_python([CONVERTER, "--maestro-dir", flow_dir, "--case", CASE], cwd=elsewhere)
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        lines = [line for line in result.stdout.splitlines() if line]
+        self.assertEqual(len(lines), 1)
+        self.assertTrue(lines[0].startswith(NATIVE_FAILURE_PREFIX))
+        record = self.record(flow_dir)
+        self.assertEqual(record["case"], CASE)
+        self.assertEqual(record["step"], 'Assert condition "Thank you"')
+        self.assertEqual(json.loads(lines[0][len(NATIVE_FAILURE_PREFIX) :])["case"], CASE)
+
+
+class StagedLayoutTest(MaestroOutputCase):
+    """A copied ``skills/maestro/scripts`` folder, with no Android skill beside it."""
+
+    def stage_converter(self, root):
+        scripts = os.path.join(root, "skills", "maestro", "scripts")
+        os.makedirs(scripts)
+        for name in sorted(os.listdir(HERE)):
+            if name.endswith(".py"):
+                shutil.copyfile(os.path.join(HERE, name), os.path.join(scripts, name))
+        return os.path.join(scripts, "maestro_failure.py")
+
+    def test_the_converter_runs_from_a_staged_skill_folder(self):
+        flow_dir = self.failing_flow()
+        with tempfile.TemporaryDirectory() as staged:
+            converter = self.stage_converter(staged)
+            elsewhere = os.path.join(staged, "elsewhere")
+            os.makedirs(elsewhere)
+            result = run_python([converter, "--maestro-dir", flow_dir], cwd=elsewhere)
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        record = self.record(flow_dir)
+        self.assertEqual(record["case"], FLOW)
+        self.assertEqual(record["screenshot"], "screenshots/step-003-assertCondition.png")
+        self.assertEqual(len([line for line in result.stdout.splitlines() if line]), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()