testzombie-windows 0.2.25__py3-none-any.whl

testzombie_windows/__init__.py

@@ -0,0 +1,6 @@
+"""TestZombie Windows integration: FlaUI, RPA.Windows and Python uiautomation."""
+__version__ = '0.2.25'
+
+from .uiautomation_adapter import UiautomationHealingClient
+
+__all__ = ['UiautomationHealingClient']

testzombie_windows/api.py

@@ -0,0 +1,152 @@
+"""Network contract for the additive Windows API endpoints (Phase 2.2)."""
+from __future__ import annotations
+import json
+import os
+import socket
+from .config import api_base_url, api_header_names
+import urllib.error
+import urllib.request
+
+
+class TestZombieApiError(RuntimeError):
+    pass
+
+
+# The InitController supplies these project settings in InitZombieResult.
+# Keep the allowlist explicit: no tokens, credentials or project secrets in logs.
+_HEALING_FIELDS = (
+    ('healingLocatorFallbackEnabled', 'Locator-Fallback'),
+    ('healingVisualPositionEnabled', 'Visual-Position'),
+    ('healingWaitEnabled', 'Wait'),
+    ('healingClickEnabled', 'Click'),
+    ('healingAiEnabled', 'AI'),
+    ('healingStrictness', 'Strictness'),
+    ('healingAuditModeEnabled', 'Audit'),
+)
+
+
+def format_healing_configuration(config):
+    """Render only settings actually supplied by initZombie, never infer defaults."""
+    if not isinstance(config, dict):
+        return ''
+    rendered = []
+    for key, label in _HEALING_FIELDS:
+        if key not in config or config[key] is None:
+            continue
+        value = config[key]
+        if isinstance(value, bool):
+            value = 'AN' if value else 'AUS'
+        else:
+            value = str(value)
+        rendered.append(f'{label}={value}')
+    return ' | '.join(rendered)
+
+
+def report_healing_configuration(api, *, emitter=print):
+    """Print project-controlled healing flags after a successful Init."""
+    summary = format_healing_configuration(getattr(api, 'healing_config', None))
+    if summary:
+        emitter('[TestZombie Windows] Healing-Konfiguration: ' + summary)
+
+
+class WindowsApiClient:
+    def __init__(self, url=None, api_key=None, email=None, timeout=None):
+        try:
+            self.url = api_base_url(url)
+            self.key_header, self.mail_header = api_header_names()
+        except ValueError as exc:
+            raise TestZombieApiError(str(exc)) from exc
+        self.healing_config = {}
+        self.api_key = api_key or os.environ.get('TZ_API_KEY', '')
+        self.email = email or os.environ.get('TZ_API_EMAIL', '')
+        try:
+            self.timeout = float(timeout if timeout is not None else os.environ.get('TZ_API_TIMEOUT', '3'))
+            # findWindowsElement may execute a synchronous AI provider request.
+            # Its deadline must not inherit the short normal API timeout.
+            self.heal_timeout = float(os.environ.get('TZ_API_HEAL_TIMEOUT', '120'))
+        except (TypeError, ValueError) as exc:
+            raise TestZombieApiError('TZ_API_TIMEOUT / TZ_API_HEAL_TIMEOUT muss eine Sekundenzahl sein.') from exc
+        if not (0 < self.timeout <= 60):
+            raise TestZombieApiError('TZ_API_TIMEOUT muss groesser 0 und maximal 60 Sekunden sein.')
+        if not (0 < self.heal_timeout <= 300):
+            raise TestZombieApiError('TZ_API_HEAL_TIMEOUT muss groesser 0 und maximal 300 Sekunden sein.')
+        if not self.api_key:
+            raise TestZombieApiError('TZ_API_KEY fehlt (Projekt-API-Key konfigurieren).')
+
+    def request_timeout(self, endpoint):
+        return self.heal_timeout if endpoint.strip('/').lower() == 'findwindowselement' else self.timeout
+
+    def post(self, endpoint, payload):
+        timeout = self.request_timeout(endpoint)
+        url = self.url + '/api/' + endpoint.lstrip('/')
+        body = json.dumps(payload, ensure_ascii=False).encode('utf-8')
+        headers = {
+            'Content-Type': 'application/json',
+            self.key_header: self.api_key,
+            self.mail_header: self.email,
+        }
+        # This marks a single Windows demo request. The server additionally
+        # requires a local/test Spring profile, explicit property and exact
+        # demo identity; a client-controlled header can never force AI alone.
+        if endpoint.strip('/').lower() == 'findwindowselement' and os.environ.get(
+                'TZ_WINDOWS_TEST_FORCE_AI', '').strip().lower() in ('1', 'true', 'yes', 'on'):
+            from urllib.parse import urlsplit
+            if urlsplit(self.url).hostname not in ('localhost', '127.0.0.1', '::1'):
+                raise TestZombieApiError('Force-AI test mode requires a localhost API URL')
+            headers['X-TestZombie-Windows-Test-Force-AI'] = 'true'
+        req = urllib.request.Request(url, body, method='POST', headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as response:
+                result = json.load(response)
+        except urllib.error.HTTPError as exc:
+            # Avoid echoing response bodies potentially containing user data.
+            raise TestZombieApiError(f'{endpoint}: HTTP {exc.code} (API response rejected)') from exc
+        except (urllib.error.URLError, TimeoutError, OSError, ValueError) as exc:
+            # urllib can wrap a socket timeout in URLError.reason. Do not
+            # include raw response bodies, credentials or user input in logs.
+            reason = getattr(exc, 'reason', exc)
+            if isinstance(reason, (TimeoutError, socket.timeout)) or 'timed out' in str(reason).lower():
+                detail = f'timeout after {timeout:g}s'
+            elif isinstance(exc, ValueError):
+                detail = 'invalid JSON response'
+            else:
+                detail = 'network error: ' + type(exc).__name__
+            raise TestZombieApiError(f'{endpoint}: {detail}') from exc
+        if not isinstance(result, dict) or result.get('success') is False:
+            raise TestZombieApiError(f'{endpoint}: unsuccessful API response')
+        data = result.get('data')
+        if isinstance(data, dict) and data.get('error'):
+            raise TestZombieApiError(f'{endpoint}: {data["error"]}')
+        return data if isinstance(data, dict) else {}
+
+    def put_discovery(self, test_run_id, payload):
+        """PUT to the existing DiscoveryController; success is HTTP 204 (no JSON)."""
+        from urllib.parse import quote
+        if not isinstance(test_run_id, str) or not test_run_id.strip():
+            raise TestZombieApiError('Discovery requires a valid testRunId')
+        endpoint = 'test-runs/' + quote(test_run_id, safe='') + '/discovery'
+        url = self.url + '/api/' + endpoint
+        body = json.dumps(payload, ensure_ascii=False).encode('utf-8')
+        req = urllib.request.Request(url, body, method='PUT', headers={
+            'Content-Type': 'application/json',
+            self.key_header: self.api_key,
+            self.mail_header: self.email,
+        })
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                if response.status not in (200, 201, 202, 204):
+                    raise TestZombieApiError('discovery: unexpected HTTP status')
+                return True
+        except urllib.error.HTTPError as exc:
+            raise TestZombieApiError(f'discovery: HTTP {exc.code}') from exc
+        except (urllib.error.URLError, TimeoutError, OSError, ValueError) as exc:
+            raise TestZombieApiError(f'discovery: network error: {type(exc).__name__}') from exc
+
+    def init_run(self, info='ROBOT_WINDOWS'):
+        self.healing_config = {}
+        data = self.post('initZombie', {'info': info})
+        run_id = data.get('testRunId')
+        if not run_id:
+            raise TestZombieApiError('initZombie did not return a testRunId')
+        self.healing_config = {key: data[key] for key, _ in _HEALING_FIELDS if key in data}
+        return run_id

testzombie_windows/code_update.py

@@ -0,0 +1,343 @@
+"""Opt-in, fail-closed source updates for successful Windows UIA healing.
+
+This module never touches the Java backend, a site-packages directory, or a file
+outside the explicitly allowed project root. Changes are literal-only, backed up
+and written atomically. If any source location is ambiguous we do nothing.
+"""
+from __future__ import annotations
+
+import ast
+import io
+from datetime import datetime, timezone
+import os
+from pathlib import Path
+import re
+import shutil
+import stat
+import tempfile
+import tokenize
+from typing import Optional
+
+_TRUE = {'1', 'true', 'yes', 'on'}
+_ROBOT_SPLIT = re.compile(r'(\t+| {2,})')
+_SKIPPED_DIRS = {'.git', '.venv', '.venv-uia', '__pycache__', 'results',
+                 'node_modules', 'dist', 'build', 'site-packages', '.tox'}
+_MAX_FILE_BYTES = 2 * 1024 * 1024
+
+
+def enabled_from_env() -> bool:
+    return os.environ.get('TZ_CODE_UPDATE', '').strip().lower() in _TRUE
+
+
+class WindowsCodeUpdater:
+    """Source updater: disabled unless TZ_CODE_UPDATE explicitly set to true.
+
+    root: Only source files INSIDE this directory may be edited. By default the
+    current working directory is used. CI/custom runners should explicitly set
+    TZ_CODE_UPDATE_ROOT to the checked-out test project directory.
+    """
+
+    def __init__(self, *, enabled: Optional[bool] = None, root=None):
+        self.enabled = (enabled_from_env() if enabled is None else
+                        enabled.strip().lower() in _TRUE if isinstance(enabled, str) else bool(enabled))
+        self.root = Path(root or os.environ.get('TZ_CODE_UPDATE_ROOT') or os.getcwd()).resolve()
+
+    def _allowed(self, path: Path, suffix: str) -> bool:
+        try:
+            resolved = path.resolve(strict=True)
+            relative = resolved.relative_to(self.root)
+            return (resolved.is_file() and resolved.suffix.lower() == suffix
+                    and not any(part in _SKIPPED_DIRS for part in relative.parts)
+                    and resolved.stat().st_size <= _MAX_FILE_BYTES)
+        except (OSError, ValueError):
+            return False
+
+    @staticmethod
+    def _read(path: Path):
+        # Respect PEP-263 encoding declarations and preserve existing newlines.
+        raw = path.read_bytes()
+        encoding, _ = tokenize.detect_encoding(io.BytesIO(raw).readline)
+        return raw.decode(encoding), encoding
+
+    @staticmethod
+    def _annotation(old: str, new: str, test_run_id, now=None):
+        def clean(value):
+            value = str(value if value is not None else '')
+            # Never let a malformed remote testRunId inject a second source line.
+            return re.sub(r'[\r\n\x00-\x1f\x7f]', ' ', value)[:550]
+
+        at = now or datetime.now(timezone.utc)
+        stamp = at.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+        return (f'TestZombie CodeUpdate | old={clean(old)} | new={clean(new)} '
+                f'| at={stamp} | testRun={clean(test_run_id)}')
+
+    @staticmethod
+    def _column_as_char(line, byte_column):
+        # Python AST stores UTF-8 byte offsets, even if source text is Unicode.
+        return len(line.encode('utf-8')[:byte_column].decode('utf-8'))
+
+    def _write(self, path: Path, before: str, after: str, encoding: str) -> bool:
+        if before == after or not self.enabled:
+            return False
+        backup = path.with_name(path.name + '.testzombie.bak')
+        lock = path.with_name(path.name + '.testzombie.lock')
+        try:
+            lock_fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        except OSError:
+            return False  # Someone else is already modifying this source.
+        try:
+            os.close(lock_fd)
+            actual, _ = self._read(path)
+            if actual != before:  # source changed since we evaluated the edit
+                return False
+            if backup.is_symlink():
+                return False
+            if not backup.exists():
+                shutil.copy2(path, backup)
+            mode = stat.S_IMODE(path.stat().st_mode)
+            fd, tmp_name = tempfile.mkstemp(prefix='.tz-update-', suffix='.tmp', dir=path.parent)
+            try:
+                with os.fdopen(fd, 'w', encoding=encoding, newline='') as f:
+                    f.write(after)
+                    f.flush()
+                    os.fsync(f.fileno())
+                os.chmod(tmp_name, mode)
+                os.replace(tmp_name, path)
+            finally:
+                if os.path.exists(tmp_name):
+                    os.unlink(tmp_name)
+            return True
+        except (OSError, UnicodeError):
+            return False
+        finally:
+            try:
+                lock.unlink()
+            except OSError:
+                pass
+
+    def update_python(self, *, frame, control_type, locator_keyword, old, new, test_run_id) -> bool:
+        """Update ONLY a string literal in this exact find_control call site.
+
+        A dynamic variable (or a customer wrapper that forwards variables) is
+        deliberately not rewritten; there is no safe automatic source location.
+        """
+        if not self.enabled or old == new or locator_keyword not in ('automation_id', 'name'):
+            return False
+        if not (isinstance(old, str) and isinstance(new, str) and new
+                and '\n' not in new and '\r' not in new):
+            return False
+        path = Path(frame.f_code.co_filename)
+        if not self._allowed(path, '.py'):
+            return False
+        try:
+            source, encoding = self._read(path)
+            tree = ast.parse(source, filename=str(path))
+        except (OSError, SyntaxError, UnicodeError):
+            return False
+        calls = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            func = node.func
+            if not isinstance(func, ast.Attribute) or func.attr != 'find_control':
+                continue
+            if not (node.lineno <= frame.f_lineno <= node.end_lineno):
+                continue
+            if not node.args or not isinstance(node.args[0], ast.Constant):
+                continue
+            if node.args[0].value not in (control_type, control_type + 'Control'):
+                continue
+            candidates = [k.value for k in node.keywords
+                          if k.arg == locator_keyword and isinstance(k.value, ast.Constant)
+                          and isinstance(k.value.value, str) and k.value.value == old]
+            if len(candidates) == 1:
+                calls.append(candidates[0])
+        if len(calls) != 1:
+            return False
+        node = calls[0]
+        if node.lineno != node.end_lineno:
+            return False  # no multiline string literals / implicit concatenation
+        lines = source.splitlines(keepends=True)
+        idx = node.lineno - 1
+        line = lines[idx]
+        try:
+            start = self._column_as_char(line, node.col_offset)
+            end = self._column_as_char(line, node.end_col_offset)
+        except (ValueError, UnicodeError):
+            return False
+        # Explicitly verify that AST token really is just a standalone literal.
+        literal = line[start:end]
+        try:
+            if ast.literal_eval(literal) != old or not isinstance(ast.parse(literal, mode='eval').body, ast.Constant):
+                return False
+        except (SyntaxError, ValueError):
+            return False
+        # Preserve the number of lines (otherwise the running Python frame's
+        # line numbers would no longer refer to the same source call sites).
+        new_line = line[:start] + repr(new) + line[end:]
+        no_eol = new_line.rstrip('\r\n')
+        eol = new_line[len(no_eol):]
+        annotation = self._annotation(old, new, test_run_id)
+        new_line = no_eol + '  # ' + annotation + eol
+        lines[idx] = new_line
+        updated = ''.join(lines)
+        try:
+            ast.parse(updated, filename=str(path))
+        except SyntaxError:
+            return False
+        return self._write(path, source, updated, encoding)
+
+    def _suite_sources(self, source_file):
+        """Only files referenced by the CURRENT Robot suite may be edited.
+
+        For safety, variable-based imports (that cannot be resolved offline) are
+        not followed. We never glob unrelated Robot suites to find a match.
+        """
+        if not source_file:
+            return []
+        source_file = Path(source_file)
+        if not self._allowed(source_file, source_file.suffix.lower()):
+            return []
+        pending = [source_file.resolve()]
+        visited = set()
+        while pending and len(visited) < 100:
+            path = pending.pop()
+            if path in visited or not self._allowed(path, path.suffix.lower()):
+                continue
+            visited.add(path)
+            try:
+                source, _ = self._read(path)
+            except (OSError, UnicodeError):
+                continue
+            in_settings = False
+            for line in source.splitlines():
+                stripped = line.strip()
+                if stripped.startswith('***') and stripped.endswith('***'):
+                    in_settings = stripped.casefold() == '*** settings ***'
+                    continue
+                if not in_settings or not stripped or stripped.startswith('#'):
+                    continue
+                fields = _ROBOT_SPLIT.split(stripped)
+                tokens = fields[::2]
+                if len(tokens) < 2 or tokens[0].casefold() != 'resource':
+                    continue
+                entry = tokens[1].replace('${CURDIR}', str(path.parent))
+                if '${' in entry or '%{' in entry:
+                    continue
+                child = Path(entry)
+                if not child.is_absolute():
+                    child = path.parent / child
+                if self._allowed(child, child.suffix.lower()) and child.suffix.lower() in ('.robot', '.resource'):
+                    pending.append(child.resolve())
+        return sorted(visited)
+
+    def update_robot(self, *, old, new, test_run_id, source_file=None) -> bool:
+        """Update unique Robot literal in current suite or imported resources.
+
+        Requires a current suite source. Unrelated files, unresolved variables,
+        multiple matching definitions and non-literal locators are not edited.
+        """
+        if not self.enabled or not isinstance(old, str) or not isinstance(new, str):
+            return False
+        if not old or not new or old == new or any(c in new for c in '\r\n\x00'):
+            return False
+        matches = []
+        for path in self._suite_sources(source_file):
+            try:
+                source, encoding = self._read(path)
+            except (OSError, UnicodeError):
+                continue
+            lines = source.splitlines(keepends=True)
+            for index, line in enumerate(lines):
+                stripped = line.strip()
+                if not stripped or stripped.startswith('#') or stripped.startswith('...'):
+                    continue
+                content = line.rstrip('\r\n')
+                chunks = _ROBOT_SPLIT.split(content)
+                for position in range(0, len(chunks), 2):
+                    token = chunks[position]
+                    if token.strip().startswith('#'):
+                        break
+                    if token == old:
+                        matches.append((path, source, encoding, lines, index, chunks, position))
+                        if len(matches) > 1:
+                            return False
+        if len(matches) != 1:
+            return False
+        path, source, encoding, lines, index, chunks, position = matches[0]
+        chunks[position] = new
+        old_line = lines[index]
+        eol = '\r\n' if old_line.endswith('\r\n') else ('\n' if old_line.endswith('\n') else '')
+        lines[index] = ''.join(chunks) + '    # ' + self._annotation(old, new, test_run_id) + eol
+        updated = ''.join(lines)
+        return self._write(path, source, updated, encoding)
+
+    def update_native_python(self, *, source_file, lineno, control_type,
+                             locator_keyword, old, new, test_run_id) -> bool:
+        """Update a unique native ``auto.EditControl(AutomationId='...')`` call.
+
+        The exact constructor source location is captured at instantiation,
+        not guessed from the later Exists()/Click() stack. No dynamic strings,
+        ambiguous calls or cross-file searches are edited.
+        """
+        if not self.enabled or old == new or locator_keyword not in ('AutomationId', 'Name'):
+            return False
+        if not all(isinstance(x, str) for x in (old, new)) or not new or any(c in new for c in '\r\n\x00'):
+            return False
+        try:
+            path = Path(source_file)
+            if not self._allowed(path, '.py'):
+                return False
+            source, encoding = self._read(path)
+            tree = ast.parse(source, filename=str(path))
+        except (OSError, SyntaxError, UnicodeError, ValueError):
+            return False
+        calls = []
+        for call in ast.walk(tree):
+            if not isinstance(call, ast.Call) or not (call.lineno <= lineno <= call.end_lineno):
+                continue
+            f = call.func
+            if not (isinstance(f, ast.Attribute) and f.attr == control_type + 'Control'):
+                continue
+            for kw in call.keywords:
+                if (kw.arg == locator_keyword and isinstance(kw.value, ast.Constant)
+                        and isinstance(kw.value.value, str) and kw.value.value == old):
+                    calls.append(kw.value)
+        if len(calls) != 1:
+            return False
+        literal = calls[0]
+        if literal.lineno != literal.end_lineno:
+            return False
+        lines = source.splitlines(keepends=True)
+        idx = literal.lineno - 1
+        line = lines[idx]
+        try:
+            start = self._column_as_char(line, literal.col_offset)
+            end = self._column_as_char(line, literal.end_col_offset)
+            token = line[start:end]
+            if ast.literal_eval(token) != old:
+                return False
+        except (ValueError, SyntaxError, UnicodeError):
+            return False
+        changed = line[:start] + repr(new) + line[end:]
+        # Line-count stability lets the still-running interpreter update the
+        # next native locator in the same test without misaddressed edits.
+        annotation = self._annotation(old, new, test_run_id)
+        eol = '\r\n' if changed.endswith('\r\n') else ('\n' if changed.endswith('\n') else '')
+        body = changed[:-len(eol)] if eol else changed
+        # A test can be healed again after a previous CodeUpdate (level 1 ->
+        # level 2). Preserve the earlier annotation in the same source line;
+        # do not produce a second Python comment or erase its provenance.
+        if 'TestZombie CodeUpdate |' in body:
+            if body.count('TestZombie CodeUpdate |') >= 12 or len(body) > 12000:
+                return False  # bounded audit trail, avoid unbounded source growth
+            changed_line = body + ' ; ' + annotation
+        else:
+            changed_line = body + '  # ' + annotation
+        lines[idx] = changed_line + eol
+        updated = ''.join(lines)
+        try:
+            ast.parse(updated, filename=str(path))
+        except SyntaxError:
+            return False
+        return self._write(path, source, updated, encoding)

testzombie_windows/config.py

@@ -0,0 +1,38 @@
+"""Shared API configuration for FlaUI, RPA.Windows and direct Python UIA.
+
+Production defaults to https://testzombie.ai/api. TZ_API_URL overrides it for
+local development, staging and CI. The network client appends /api/<endpoint>,
+so api_base_url() intentionally returns the service root without /api.
+"""
+from __future__ import annotations
+
+import os
+from urllib.parse import urlsplit, urlunsplit
+
+DEFAULT_LIVE_API_URL = "https://testzombie.ai/api"
+DEFAULT_KEY_HEADER = "X-API-KEY"  # Must agree with ApiKeyFilter.API_KEY_HEADER.
+DEFAULT_MAIL_HEADER = "X-API-MAIL"  # Must agree with ApiKeyFilter.API_MAIL_HEADER.
+
+
+def api_base_url(explicit_url: str | None = None) -> str:
+    """Resolve base URL. Accept both .../api and ... (normalize to base)."""
+    candidate = (explicit_url or os.environ.get('TZ_API_URL') or DEFAULT_LIVE_API_URL).strip()
+    if not candidate:
+        raise ValueError(
+            'Keine TestZombie API URL konfiguriert; pruefe TZ_API_URL oder den Live-Default.'
+        )
+    parts = urlsplit(candidate)
+    if parts.scheme not in ('http', 'https') or not parts.netloc or parts.query or parts.fragment:
+        raise ValueError('TZ_API_URL muss eine absolute http(s)-Basis-URL ohne Query/Fragment sein.')
+    path = parts.path.rstrip('/')
+    if path.endswith('/api'):
+        path = path[:-4]
+    return urlunsplit((parts.scheme, parts.netloc, path, '', '')).rstrip('/')
+
+
+def api_header_names() -> tuple[str, str]:
+    key = os.environ.get('TZ_API_KEY_HEADER', DEFAULT_KEY_HEADER).strip()
+    mail = os.environ.get('TZ_API_MAIL_HEADER', DEFAULT_MAIL_HEADER).strip()
+    if not key or not mail:
+        raise ValueError('TZ_API_KEY_HEADER und TZ_API_MAIL_HEADER duerfen nicht leer sein.')
+    return key, mail