testwins 0.4.0__py3-none-any.whl

testwins/__init__.py

@@ -0,0 +1,2 @@
+"""Testwins: evidence-first UI, shell and desktop verification."""
+__version__ = "0.4.0"

testwins/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

testwins/api_contracts.py

@@ -0,0 +1,145 @@
+"""Opt-in HTTP contracts, separate from the rendered-only GUI diagnosis and device matrix."""
+from __future__ import annotations
+import hashlib
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.request
+import uuid
+from pathlib import Path
+from urllib.parse import urljoin
+from xml.etree import ElementTree as ET
+import yaml
+from .util import atomic_json, origin, file_digest, utc_now
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self,req,fp,code,msg,headers,newurl):return None
+
+
+def pointer(data, path: str):
+    if path=='':return data
+    if not path.startswith('/'):raise ValueError('JSON pointer must start with /')
+    for token in path[1:].split('/'):
+        token=token.replace('~1','/').replace('~0','~')
+        if isinstance(data,list):
+            if not re.fullmatch(r'0|[1-9][0-9]*',token):raise KeyError(token)
+            data=data[int(token)]
+        else:data=data[token]
+    return data
+
+
+def load(path: Path) -> dict:
+    if path.stat().st_size>2_000_000:raise ValueError('API config too large')
+    cfg=yaml.safe_load(path.read_text('utf-8'))
+    allowed={'schema','id','base_url','timeout_seconds','max_body_bytes','headers','header_env','requests'}
+    if not isinstance(cfg,dict) or set(cfg)-allowed or cfg.get('schema')!='testwins.api/v1':raise ValueError('Invalid API contract')
+    if not re.fullmatch(r'[a-z][a-z0-9_-]{0,63}',cfg.get('id','')):raise ValueError('Invalid API id')
+    base=origin(cfg['base_url'])
+    cfg.setdefault('timeout_seconds',10);cfg.setdefault('max_body_bytes',1_000_000)
+    for key,low,high in [('timeout_seconds',1,60),('max_body_bytes',1,10_000_000)]:
+        if type(cfg[key]) is not int or not low<=cfg[key]<=high:raise ValueError('Invalid '+key)
+    for key in ('headers','header_env'):
+        cfg.setdefault(key,{})
+        if not isinstance(cfg[key],dict):raise ValueError('Invalid '+key)
+        for name,value in cfg[key].items():
+            if not re.fullmatch(r'[A-Za-z0-9-]+',name) or not isinstance(value,str) or '\n' in value or '\r' in value:
+                raise ValueError('Invalid header')
+            if name.lower() in ('host','content-length','transfer-encoding','connection'):raise ValueError('Transport headers are managed by the client')
+            if key=='header_env' and not re.fullmatch('[A-Z_][A-Z0-9_]*',value):raise ValueError('Invalid environment variable')
+    requests=cfg.get('requests')
+    if not isinstance(requests,list) or not 1<=len(requests)<=50:raise ValueError('API suite requires 1..50 requests')
+    names=set()
+    for req in requests:
+        if not isinstance(req,dict) or set(req)-{'id','path','method','body','allow_mutation','expect'}:raise ValueError('Invalid request')
+        name=req.get('id','')
+        if not re.fullmatch(r'[a-z][a-z0-9_-]{0,63}',name) or name in names:raise ValueError('Invalid/duplicate request id')
+        names.add(name)
+        if not isinstance(req.get('path'),str) or origin(urljoin(cfg['base_url'],req['path']))!=base:raise ValueError('API request leaves the configured origin')
+        req.setdefault('method','GET')
+        if req['method'] not in {'GET','HEAD','POST','PUT','PATCH','DELETE'}:raise ValueError('Unsupported HTTP method')
+        if req['method'] not in ('GET','HEAD') and req.get('allow_mutation') is not True:raise ValueError('Mutation requires explicit allow_mutation')
+        if req['method'] in ('GET','HEAD') and 'body' in req:raise ValueError('GET/HEAD body forbidden')
+        if len(json.dumps(req.get('body'),allow_nan=False))>1_000_000:raise ValueError('Request body too large')
+        exp=req.get('expect',{})
+        if not isinstance(exp,dict) or set(exp)-{'status','json_equals','headers','json_min_length','json_any'}:raise ValueError('Invalid API expectation')
+        if type(exp.get('status')) is not int or not 100<=exp['status']<=599:raise ValueError('Explicit expected status required')
+        if not isinstance(exp.get('json_equals',{}),dict):raise ValueError('json_equals must be a map of JSON pointers')
+        for key in exp.get('json_equals',{}):
+            if not isinstance(key,str) or key and not key.startswith('/'):raise ValueError('Invalid JSON pointer')
+        if not isinstance(exp.get('headers',{}),dict) or not all(isinstance(k,str) and isinstance(v,str) for k,v in exp.get('headers',{}).items()):raise ValueError('Invalid expected headers')
+        if not isinstance(exp.get('json_min_length',{}),dict):raise ValueError('json_min_length must be a map')
+        for key,value in exp.get('json_min_length',{}).items():
+            if not isinstance(key,str) or not key.startswith('/') or type(value) is not int or not 0<=value<=100000:raise ValueError('Invalid minimum JSON length')
+        if not isinstance(exp.get('json_any',[]),list):raise ValueError('json_any must be a list')
+        for rule in exp.get('json_any',[]):
+            if not isinstance(rule,dict) or set(rule)!={'path','field','contains'} or not all(isinstance(v,str) for v in rule.values()) or not rule['path'].startswith('/'):
+                raise ValueError('Invalid JSON array predicate')
+    return cfg
+
+
+def run(path: Path, output: Path, *, approve_mutations: bool=False) -> Path:
+    cfg=load(path)
+    if any(r['method'] not in ('GET','HEAD') for r in cfg['requests']) and not approve_mutations:
+        raise ValueError('This API suite can mutate state. Review it and explicitly use --approve-mutations against disposable data.')
+    headers=dict(cfg['headers'])
+    for key,env in cfg['header_env'].items():
+        value=os.environ.get(env)
+        if not value or '\r' in value or '\n' in value:raise ValueError('Missing or invalid API header environment variable: '+env)
+        headers[key]=value
+    root=output/('api-'+utc_now().replace(':','').replace('.','-')+'-'+uuid.uuid4().hex[:8])
+    root.mkdir(parents=True,exist_ok=False)
+    report={'schema':'testwins.api-report/v1','id':cfg['id'],'scope':'explicit API contracts, once per request; not GUI or device testing',
+            'created':utc_now(),'config_sha256':file_digest(path),'status':'incomplete',
+            'plan':[r['id'] for r in cfg['requests']],'checks':[{'id':r['id'],'status':'not_run'} for r in cfg['requests']],
+            'privacy':'No request headers, bodies, response bodies or raw exceptions retained'}
+    atomic_json(root/'report.json',report)
+    opener=urllib.request.build_opener(urllib.request.ProxyHandler({}),NoRedirect())
+    for req,check in zip(cfg['requests'],report['checks']):
+        started=time.monotonic()
+        response=None
+        try:
+            body=None if 'body' not in req else json.dumps(req['body'],allow_nan=False).encode()
+            req_headers=dict(headers)
+            if body is not None:req_headers.setdefault('Content-Type','application/json')
+            request=urllib.request.Request(urljoin(cfg['base_url'],req['path']),data=body,headers=req_headers,method=req['method'])
+            try:response=opener.open(request,timeout=cfg['timeout_seconds'])
+            except urllib.error.HTTPError as exc:response=exc
+            raw=response.read(cfg['max_body_bytes']+1)
+            if len(raw)>cfg['max_body_bytes']:raise ValueError('Response capture limit exceeded')
+            check.update(response_status=response.code,response_bytes=len(raw),response_sha256=hashlib.sha256(raw).hexdigest())
+            reasons=[];exp=req['expect']
+            if response.code!=exp['status']:reasons.append('status_mismatch')
+            if any(response.headers.get(k)!=v for k,v in exp.get('headers',{}).items()):reasons.append('header_mismatch')
+            if any(exp.get(k) for k in ('json_equals','json_min_length','json_any')):
+                try:
+                    payload=json.loads(raw)
+                    for key,value in exp.get('json_equals',{}).items():
+                        actual=pointer(payload,key)
+                        if json.dumps(actual,sort_keys=True)!=json.dumps(value,sort_keys=True):reasons.append('json_mismatch')
+                    for key,value in exp.get('json_min_length',{}).items():
+                        actual=pointer(payload,key)
+                        if not isinstance(actual,(list,dict,str)) or len(actual)<value:reasons.append('json_length')
+                    for rule in exp.get('json_any',[]):
+                        actual=pointer(payload,rule['path'])
+                        if not isinstance(actual,list) or not any(isinstance(x,dict) and isinstance(x.get(rule['field']),str) and rule['contains'] in x[rule['field']] for x in actual):reasons.append('json_array_predicate')
+                except (ValueError,KeyError,IndexError,TypeError):reasons.append('json_missing_or_invalid')
+            check.update(status='failed' if reasons else 'passed',reasons=sorted(set(reasons)))
+        except Exception as exc:
+            check.update(status='incomplete',exception_type=type(exc).__name__)
+        finally:
+            if response is not None:response.close()
+            check['duration_ms']=round((time.monotonic()-started)*1000,2)
+            atomic_json(root/'report.json',report)
+    statuses={c['status'] for c in report['checks']}
+    report['status']='incomplete' if statuses-{'passed','failed'} else 'failed' if 'failed' in statuses else 'passed'
+    report['exit_code']={'passed':0,'failed':1,'incomplete':2}[report['status']]
+    atomic_json(root/'report.json',report)
+    suite=ET.Element('testsuite',name='testwins.api',tests=str(len(report['checks'])),failures=str(sum(c['status']=='failed' for c in report['checks'])),errors=str(sum(c['status']=='incomplete' for c in report['checks'])))
+    for c in report['checks']:
+        test=ET.SubElement(suite,'testcase',name=c['id'],classname='api.contract')
+        if c['status']!='passed':ET.SubElement(test,'failure' if c['status']=='failed' else 'error',message=c['status'])
+    ET.ElementTree(suite).write(root/'junit.xml',encoding='utf-8',xml_declaration=True)
+    return root

testwins/baseline.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+import json
+import shutil
+from pathlib import Path
+from PIL import Image, ImageChops, ImageDraw
+from .util import atomic_json, digest, confined
+from .model import Finding
+
+
+def baseline_key(meta: dict) -> str:
+    return digest({k:meta[k] for k in ("project","browser","device","stage","viewport_profile","locale","timezone","color_scheme")})
+
+
+def compare(current: Path, reference: Path, diff_path: Path, color_delta: int=24) -> dict:
+    with Image.open(current) as a0, Image.open(reference) as b0:
+        a,b=a0.convert("RGB"),b0.convert("RGB")
+        if a.size!=b.size:return {"ratio":1.0,"dimensions_changed":True,"current":list(a.size),"baseline":list(b.size)}
+        diff=ImageChops.difference(a,b)
+        channels=diff.split();maximum=ImageChops.lighter(ImageChops.lighter(channels[0],channels[1]),channels[2])
+        mask=maximum.point(lambda p:255 if p>color_delta else 0)
+        hist=mask.histogram();changed=hist[255];total=a.width*a.height
+        overlay=b.copy();overlay.paste((255,32,100),(0,0,a.width,a.height),mask)
+        diff_path.parent.mkdir(parents=True,exist_ok=True);overlay.save(diff_path)
+        return {"ratio":changed/total,"changed_pixels":changed,"pixels":total,"dimensions_changed":False}
+
+
+def assess(image: Path, meta: dict, cfg: dict, dest: Path) -> tuple[list[dict],str]:
+    directory=cfg["baseline"]["directory"]
+    if not directory:return [],"disabled"
+    root=Path(directory);key=baseline_key(meta);ref=root/(key+".png");md=root/(key+".json")
+    if not ref.exists() or not md.exists():return [],"missing"
+    previous=json.loads(md.read_text())
+    # Engine version changes invalidate a pixel baseline, rather than create hundreds of bogus bugs.
+    if previous.get("browser_version")!=meta.get("browser_version"):return [],"incompatible_browser_version"
+    if previous.get("render_environment")!=meta.get("render_environment"):return [],"incompatible_render_environment"
+    res=compare(image,ref,dest,cfg["baseline"]["color_delta"])
+    if res["ratio"]<=cfg["baseline"]["threshold"]:return [],"matched"
+    candidate=not cfg["baseline"]["fail_on_difference"]
+    f=Finding("TW-VISUAL-REGRESSION","Zmiana względem zatwierdzonego obrazu",
+              f"Różnica przekracza próg: {res['ratio']:.3%}. Zmiana obrazu sama nie dowodzi błędu.",
+              ["viewport"],[],"normal",.70 if candidate else .98,candidate,res)
+    return [f.to_dict()],"different"
+
+
+def approve(run: Path, destination: Path, *, authorized: bool) -> int:
+    if not authorized:raise ValueError("baseline approval requires --approve")
+    report=json.loads((run/"report.json").read_text())
+    if report["coverage"]["state"]!="complete":raise ValueError("cannot approve an incomplete matrix")
+    destination.mkdir(parents=True,exist_ok=True);done=set()
+    for s in report["snapshots"]:
+        if not s["stable"]:continue
+        key=baseline_key(s["meta"])
+        if key in done:continue
+        done.add(key)
+        shutil.copy2(confined(run,s["image"]),destination/(key+".png"))
+        atomic_json(destination/(key+".json"),s["meta"])
+    return len(done)

testwins/browser.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+import asyncio
+import os
+import shutil
+import subprocess
+import tempfile
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import AsyncIterator, Any
+
+CDP_BROWSERS={"chromium","chrome","edge","brave"}
+CANDIDATES={"chrome":["google-chrome","google-chrome-stable"],
+            "edge":["microsoft-edge","microsoft-edge-stable"],"brave":["brave-browser"]}
+
+
+def browser_env() -> dict[str,str]:
+    # Do not hand local LLM, cloud or repository credentials to browser children.
+    allowed={"PATH","HOME","DISPLAY","LANG","LC_ALL","XDG_RUNTIME_DIR","DBUS_SESSION_BUS_ADDRESS",
+             "LD_LIBRARY_PATH","FONTCONFIG_PATH","PLAYWRIGHT_BROWSERS_PATH","TMPDIR"}
+    return {k:v for k,v in os.environ.items() if k in allowed}
+
+
+@asynccontextmanager
+async def launch(pw: Any, name: str, cfg: dict) -> AsyncIterator[tuple[Any,str]]:
+    browser=None; process=None; profile=None; logfile=None; external=False
+    try:
+        if name in CDP_BROWSERS:
+            endpoint=cfg["cdp_endpoints"].get(name)
+            if endpoint:
+                # Only operator-supplied endpoints; never reuse the host user's profile automatically.
+                external=True
+            else:
+                exe=cfg["executables"].get(name)
+                if not exe:
+                    exe=pw.chromium.executable_path if name=="chromium" else next((shutil.which(x) for x in CANDIDATES[name] if shutil.which(x)),None)
+                if not exe or not Path(exe).exists():raise RuntimeError(f"browser unavailable: {name}")
+                profile=Path(tempfile.mkdtemp(prefix="testwins-"+name+"-"))
+                logfile=(profile/"launcher.log").open("wb")
+                args=[exe,"--remote-debugging-port=0","--remote-debugging-address=127.0.0.1",
+                      "--user-data-dir="+str(profile),"--no-first-run","--no-default-browser-check",
+                      "--disable-background-networking","--disable-component-update","--disable-sync",
+                      "--password-store=basic","--use-mock-keychain","--enable-automation",
+                      "--window-size=1500,1000"]
+                if cfg["headless"]:args.append("--headless=new")
+                if not cfg["sandbox"]:args.append("--no-sandbox")
+                args.append("about:blank")
+                process=subprocess.Popen(args,stdout=logfile,stderr=subprocess.STDOUT,env=browser_env(),start_new_session=True)
+                active=profile/"DevToolsActivePort"
+                for _ in range(150):
+                    if process.poll() is not None:raise RuntimeError(f"{name} exited before CDP became available (check sandbox/platform prerequisites)")
+                    if active.exists() and len(active.read_text().splitlines())>=2:break
+                    await asyncio.sleep(.1)
+                else:raise TimeoutError(f"CDP startup timeout: {name}")
+                port=int(active.read_text().splitlines()[0]);endpoint=f"http://127.0.0.1:{port}"
+            browser=await pw.chromium.connect_over_cdp(endpoint,timeout=15000)
+            yield browser,"cdp"
+        else:
+            bt=getattr(pw,name)
+            kwargs={"headless":cfg["headless"],"env":browser_env()}
+            if cfg["executables"].get(name):kwargs["executable_path"]=cfg["executables"][name]
+            browser=await bt.launch(**kwargs)
+            yield browser,"playwright"
+    finally:
+        if browser:
+            try:await browser.close()
+            except Exception:pass
+        if process:
+            if process.poll() is None:
+                process.terminate()
+                try:await asyncio.to_thread(process.wait,5)
+                except subprocess.TimeoutExpired:process.kill();await asyncio.to_thread(process.wait)
+        if logfile:logfile.close()
+        if profile:shutil.rmtree(profile,ignore_errors=True)
+
+
+def context_options(cfg: dict, device: dict, name: str, scene: dict | None = None) -> dict:
+    # Firefox does not implement Playwright's is_mobile. Its mobile cell is honestly viewport+touch.
+    result={"viewport":{"width":device["width"],"height":device["height"]},
+            "device_scale_factor":device["dpr"],"has_touch":device["touch"],
+            "locale":cfg["locale"],"timezone_id":cfg["timezone"],
+            "color_scheme":cfg["color_scheme"],"reduced_motion":"reduce",
+            "service_workers":"block","accept_downloads":cfg.get("downloads",{}).get("enabled",False)}
+    if name!="firefox":result["is_mobile"]=device["mobile"]
+    from .sessions import state_for
+    state=state_for(cfg,scene)
+    if state is not None:result["storage_state"]=state
+    return result

testwins/cli.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+from .config import load, MATRICES
+from .util import atomic_json
+
+
+def parser() -> argparse.ArgumentParser:
+    p=argparse.ArgumentParser(prog='testwins',description='Rendered-UI audit lab: screenshots, DOM geometry and explicit UI contracts')
+    from . import __version__
+    p.add_argument('--version',action='version',version='testwins '+__version__)
+    sub=p.add_subparsers(dest='command',required=True)
+    r=sub.add_parser('run');r.add_argument('--config',type=Path,default=Path('configs/audit.yaml'))
+    r.add_argument('--url');r.add_argument('--matrix',choices=MATRICES);r.add_argument('--output',type=Path,default=Path('artifacts'))
+    r.add_argument('--headless',action='store_true',default=None);r.add_argument('--chromium-executable')
+    r.add_argument('--no-axe',action='store_true',help='Explicitly remove axe checks from this audit scope')
+    v=sub.add_parser('validate');v.add_argument('--config',type=Path,required=True)
+    v=sub.add_parser('verify');v.add_argument('run',type=Path)
+    b=sub.add_parser('baseline');b.add_argument('run',type=Path);b.add_argument('--directory',type=Path,required=True);b.add_argument('--approve',action='store_true')
+    t=sub.add_parser('publish');t.add_argument('proposals',type=Path);t.add_argument('--project',type=Path,required=True)
+    t.add_argument('--apply',action='store_true');t.add_argument('--include-candidates',action='store_true');t.add_argument('--ready',action='store_true');t.add_argument('--limit',type=int,default=25);t.add_argument('--offset',type=int,default=0)
+    t.add_argument('--receipt',type=Path,help='Write publication receipt outside the immutable input run')
+    sub.add_parser('doctor')
+    x=sub.add_parser('api',help='Separate explicit HTTP contracts; not a browser matrix')
+    x.add_argument('--config',type=Path,required=True);x.add_argument('--output',type=Path,default=Path('artifacts/api'));x.add_argument('--approve-mutations',action='store_true')
+    g=sub.add_parser('gate',help='Require every planned assertion; no confidence-based bypass')
+    g.add_argument('report',type=Path,help='Run directory (also checks integrity) or report.json')
+    g=sub.add_parser('auth-save',help='Open an isolated browser; save private state after a signed-in selector appears')
+    g.add_argument('--config',type=Path,required=True);g.add_argument('--output',type=Path,required=True)
+    g.add_argument('--ready-selector',required=True);g.add_argument('--timeout-ms',type=int,default=120000)
+
+    i=sub.add_parser('init');i.add_argument('directory',type=Path);i.add_argument('--profile',choices=['minimal','clonerd'],default='minimal')
+    for command in ('task','scenario','suite'):
+        t=sub.add_parser(command)
+        if command=='scenario':
+            t.add_argument('files',nargs='+');t.add_argument('--dry-run',action='store_true');t.add_argument('--url',default='http://sut:8080')
+        else:t.add_argument('--file',type=Path,required=True)
+        t.add_argument('--project',type=Path,default=Path('.'));t.add_argument('--output',type=Path,default=Path('artifacts/tasks'))
+        t.add_argument('--trusted-local',action='store_true',help='Explicitly execute reviewed scenarios on this host, without Docker isolation')
+        t.add_argument('--image',default='testwins-worker:local');t.add_argument('--network',default='none')
+    v=sub.add_parser('vision');v.add_argument('source',type=Path);v.add_argument('--output',type=Path,required=True)
+    v.add_argument('--env',type=Path,default=Path('.env'));v.add_argument('--goal',default='');v.add_argument('--before',type=Path);v.add_argument('--regions-json',type=Path)
+    c=sub.add_parser('cv');c.add_argument('image',type=Path);c.add_argument('--output',type=Path,required=True)
+    c.add_argument('--backend',choices=['opencv','yolo','regions'],default='opencv');c.add_argument('--weights',type=Path)
+    c.add_argument('--weights-sha256');c.add_argument('--trust-model',action='store_true');c.add_argument('--regions-json',type=Path)
+    d=sub.add_parser('draft');d.add_argument('image',type=Path);d.add_argument('--snapshot',type=Path,required=True)
+    d.add_argument('--goal',required=True);d.add_argument('--url',required=True);d.add_argument('--output',type=Path,required=True);d.add_argument('--env',type=Path,default=Path('.env'))
+    from .live.cli import register
+    register(sub)
+    return p
+
+
+def main(argv: list[str] | None=None) -> int:
+    p=parser();a=p.parse_args(argv)
+    try:
+        if a.command in {'watch','live-status','live-serve','live-export','capacity','diagnose','catalog'}:
+            from .live.cli import dispatch
+            return dispatch(a)
+        if a.command=='api':
+            from .api_contracts import run
+            root=run(a.config,a.output,approve_mutations=a.approve_mutations)
+            report=json.loads((root/'report.json').read_text())
+            print(json.dumps({'directory':str(root),'status':report['status'],'checks':len(report['checks'])}));return report['exit_code']
+        if a.command=='gate':
+            from .gate import evaluate
+            if a.report.is_dir():
+                from .verification import verify_run
+                verify_run(a.report);path=a.report/'report.json'
+            else:path=a.report
+            result=evaluate(json.loads(path.read_text('utf-8')))
+            print(json.dumps(result,indent=2));return result['exit_code']
+        if a.command=='auth-save':
+            from .sessions import capture_session
+            if not 1000<=a.timeout_ms<=600000:raise ValueError('timeout-ms must be 1000..600000')
+            asyncio.run(capture_session(load(a.config),a.output,a.ready_selector,a.timeout_ms))
+            print(json.dumps({'saved':True,'private_file':str(a.output),'included_in_reports':False}));return 0
+        if a.command=='doctor':
+            import importlib.metadata, importlib.util, shutil
+            result={'package':'testwins','python':sys.version.split()[0], 'docker':shutil.which('docker'),'packages':{}}
+            for name in ('testwins','testql','playwright','litellm','opencv-python-headless','ultralytics','mss','pyautogui','pexpect'):
+                try:result['packages'][name]=importlib.metadata.version(name)
+                except importlib.metadata.PackageNotFoundError:result['packages'][name]=None
+            try:
+                from testql.verification import VerificationRequest,run_verification
+                result['testql_public_api']=True
+            except ImportError:result['testql_public_api']=False
+            result['note']='Optional backends are reported individually; missing SDK never becomes an executed test.'
+            print(json.dumps(result,indent=2));return 0
+        if a.command=='init':
+            import shutil
+            from importlib.resources import files
+            if a.directory.exists():raise ValueError('Choose a new directory')
+            source=files('testwins').joinpath('resources',a.profile)
+            shutil.copytree(str(source),a.directory)
+            print(str(a.directory));return 0
+        if a.command in ('task','scenario','suite'):
+            from .tasks import load_task,run_task,exit_code
+            if a.command=='suite':
+                from .suite import run_suite
+                root=run_suite(a.file,a.output,trusted_local=a.trusted_local,image=a.image,network=a.network)
+                result=json.loads((root/'suite.json').read_text())
+            else:
+                task=load_task(a.file) if a.command=='task' else {'schema':'testwins.task/v1','id':'scenario','backend':'testql','files':a.files,'url':a.url,'dry_run':a.dry_run}
+                root=run_task(task,a.project,a.output,trusted_local=a.trusted_local,image=a.image,network=a.network)
+                result=json.loads((root/'result.json').read_text())
+            print(json.dumps({'directory':str(root),'result':result},ensure_ascii=False,indent=2));return exit_code(result)
+        if a.command=='cv':
+            from .cv import analyze
+            result=analyze(a.image,a.output,backend=a.backend,weights=a.weights,trust_model=a.trust_model,expected_sha256=a.weights_sha256,regions_file=a.regions_json)
+            print(json.dumps({'output':str(a.output),'regions':len(result['regions']),'defects':0}));return 0
+        if a.command=='vision':
+            from .llm import review,env_file
+            root=review(a.source,a.output,env_file(a.env),goal=a.goal,before=a.before,regions_file=a.regions_json)
+            result=json.loads((root/'vision.json').read_text());print(json.dumps({'output':str(root),'status':result['status'],'calls':result['calls']}))
+            return 2 if result['status']=='incomplete' else 0
+        if a.command=='draft':
+            from .llm import Client,Settings,env_file
+            from .drafting import draft
+            root=draft(a.image,a.snapshot,a.goal,a.url,a.output,Client(Settings.from_env(env_file(a.env))))
+            print(json.dumps({'output':str(root),'executed':False,'review_required':True}));return 0
+        if a.command=='run':
+            from .runner import run
+            c=load(a.config,base_url=a.url,matrix=a.matrix,headless=a.headless)
+            if a.chromium_executable:c['executables']['chromium']=a.chromium_executable
+            if a.no_axe:c['axe']['enabled']=False
+            root=asyncio.run(run(c,a.output));r=json.loads((root/'report.json').read_text('utf-8'))
+            print(json.dumps({'run':str(root),'coverage':r['coverage'],'summary':r['summary']},ensure_ascii=False,indent=2))
+            return r['gate']['exit_code']
+        if a.command=='validate':
+            load(a.config);result={'valid':True,'config':str(a.config)}
+        elif a.command=='verify':
+            from .verification import verify_run
+            result=verify_run(a.run)
+        elif a.command=='baseline':
+            from .baseline import approve
+            result={'approved_baselines':approve(a.run,a.directory,authorized=a.approve)}
+        elif a.command=='publish':
+            from .proposals import publish
+            result=publish(a.proposals,a.project,apply=a.apply,include_candidates=a.include_candidates,ready=a.ready,limit=a.limit,offset=a.offset)
+            if a.receipt:atomic_json(a.receipt,result)
+        print(json.dumps(result,ensure_ascii=False,indent=2));return 0
+    except (ValueError,KeyError,TypeError,OSError,ImportError,RuntimeError) as exc:
+        # Config/SDK errors, not raw application console output.
+        print(f'testwins: {type(exc).__name__}: {exc}',file=sys.stderr);return 2
+
+if __name__=='__main__':raise SystemExit(main())

testwins/collector.js

@@ -0,0 +1,154 @@
+/* All inputs are rendered DOM/layout. No application source, network log or private JS state. */
+(opts) => {
+  const started = performance.now();
+  const nodes = [], texts = [], masks = [], gaps = [], links = [];
+  const roots = [document]; const seen = new Set();
+  let truncated = false;
+  const visual=window.visualViewport,ox=visual?.offsetLeft||0,oy=visual?.offsetTop||0;
+  const rect = r => ({x:r.x-ox, y:r.y-oy, width:r.width, height:r.height});
+  const intersect = (a,b) => {const x=Math.max(a.x,b.x),y=Math.max(a.y,b.y);
+    return {x,y,width:Math.max(0,Math.min(a.x+a.width,b.x+b.width)-x),height:Math.max(0,Math.min(a.y+a.height,b.y+b.height)-y)};};
+  const vp = {x:0,y:0,width:opts.capture_viewport?.width||visual?.width||innerWidth,height:opts.capture_viewport?.height||visual?.height||innerHeight};
+  const parent = el => el.parentElement || (el.getRootNode() instanceof ShadowRoot ? el.getRootNode().host : null);
+  const contains = (a,b) => {for(let e=b;e;e=parent(e)) if(e===a) return true; return false;};
+  const pathCache = new WeakMap();
+  const path = el => {
+    if(!el || el.nodeType!==1) return '';
+    if(pathCache.has(el)) return pathCache.get(el);
+    const root=el.getRootNode();
+    const prefix=root instanceof ShadowRoot ? path(root.host)+' >>> ' : '';
+    let p;
+    if(el.id && root.querySelectorAll('#'+CSS.escape(el.id)).length===1) p='#'+CSS.escape(el.id);
+    else if(el.hasAttribute('data-testid')) p='[data-testid='+JSON.stringify(el.getAttribute('data-testid'))+']';
+    else {
+      const parts=[]; let e=el;
+      while(e && parts.length<12){
+        let part=e.localName;
+        if(e.parentElement) part+=':nth-of-type('+(Array.from(e.parentElement.children).filter(x=>x.localName===e.localName).indexOf(e)+1)+')';
+        parts.unshift(part); if(e===root.documentElement) break; e=e.parentElement;
+      } p=parts.join(' > ');
+    }
+    p=prefix+p;pathCache.set(el,p);return p;
+  };
+  const isPrivate=el=>{for(let e=el;e;e=parent(e)){
+    if(opts.mask_selectors.some(s=>e.matches(s))) return true;
+  }return false;};
+  const hit=(x,y)=>{let e=document.elementFromPoint(x+ox,y+oy),old=null;
+    while(e && e!==old && e.shadowRoot){old=e;e=e.shadowRoot.elementFromPoint(x+ox,y+oy)||e;}return e;};
+  for(let ri=0;ri<roots.length;ri++) {
+    const root=roots[ri];
+    for(const el of root.querySelectorAll('*')) {
+      if(seen.has(el))continue;seen.add(el);
+      if(seen.size>opts.max_elements*4){truncated=true;break;}
+      if(el.shadowRoot) roots.push(el.shadowRoot);
+      if(nodes.length>=opts.max_elements){truncated=true;break;}
+      const cs=getComputedStyle(el), r=rect(el.getBoundingClientRect());
+      if(cs.display==='none'||cs.visibility!=='visible'||+cs.opacity===0||r.width<=0||r.height<=0)continue;
+      let hidden=false, clip={...vp}, intentional=false;
+      const ancestors=[];
+      for(let p=parent(el);p;p=parent(p)){
+        const pc=getComputedStyle(p);ancestors.push(path(p));
+        if(+pc.opacity===0||pc.visibility!=='visible'||pc.contentVisibility==='hidden'){hidden=true;break;}
+        // Closed <details> can expose descendant Range rects that are not painted.
+        // Only its first summary subtree remains rendered; never diagnose hidden answers.
+        if(p.localName==='details'&&!p.open){
+          const summary=Array.from(p.children).find(c=>c.localName==='summary');
+          if(!summary||!contains(summary,el)){hidden=true;break;}
+        }
+        const pr=rect(p.getBoundingClientRect());
+        const c={x:pr.x+p.clientLeft,y:pr.y+p.clientTop,width:p.clientWidth,height:p.clientHeight};
+        if(['hidden','clip','scroll','auto'].includes(pc.overflowX)){
+          const next=intersect(clip,{x:c.x,y:clip.y,width:c.width,height:clip.height});clip.x=next.x;clip.width=next.width;
+        }
+        if(['hidden','clip','scroll','auto'].includes(pc.overflowY)){
+          const next=intersect(clip,{x:clip.x,y:c.y,width:clip.width,height:c.height});clip.y=next.y;clip.height=next.height;
+        }
+        if(pc.textOverflow==='ellipsis'||parseInt(pc.webkitLineClamp)>0)intentional=true;
+      }
+      if(hidden)continue;
+      const privateNode=isPrivate(el), visibleRect=intersect(r,clip), selector=path(el);
+      const interactive=el.matches('button,a[href],input:not([type=hidden]),select,textarea,[role=button],[role=link],[tabindex]');
+      const n={selector,parent:path(parent(el)),ancestors,tag:el.localName,rect:r,visibleRect,
+        display:cs.display,position:cs.position,transform:cs.transform,overflowX:cs.overflowX,overflowY:cs.overflowY,
+        clientWidth:el.clientWidth,clientHeight:el.clientHeight,scrollWidth:el.scrollWidth,scrollHeight:el.scrollHeight,
+        textOverflow:cs.textOverflow,lineClamp:cs.webkitLineClamp,interactive,
+        private:privateNode,disabled:!!el.disabled,inert:el.closest('[inert]')!==null,
+        fontSize:parseFloat(cs.fontSize),alignItems:cs.alignItems,flexDirection:cs.flexDirection,
+        role:el.getAttribute('role'),name:privateNode?'[REDACTED]':(el.getAttribute('aria-label')||el.getAttribute('alt')||'').slice(0,160),
+        brokenImage:el instanceof HTMLImageElement && !!el.currentSrc && el.complete && el.naturalWidth===0,
+        occluded:0,hitSamples:0,covering:[],
+        focused:el===document.activeElement || el===el.getRootNode().activeElement,
+        ariaHiddenAncestor:!!el.closest('[aria-hidden="true"]'),
+        css:Object.fromEntries(['minWidth','maxWidth','minHeight','maxHeight','boxSizing','whiteSpace','overflowWrap',
+        'wordBreak','lineHeight','fontFamily','zIndex','opacity','transform','pointerEvents','isolation',
+        'flexShrink','flexGrow','gap','marginTop','marginRight','marginBottom','marginLeft',
+        'paddingTop','paddingRight','paddingBottom','paddingLeft','color','backgroundColor'].map(k=>[k,cs[k]]))};
+      if(privateNode && visibleRect.width && visibleRect.height) masks.push(visibleRect);
+      if(interactive && !n.disabled && !n.inert && cs.pointerEvents!=='none' && visibleRect.width>2 && visibleRect.height>2){
+        for(const [fx,fy] of [[.5,.5],[.2,.2],[.8,.2],[.2,.8],[.8,.8]]){
+          const x=visibleRect.x+visibleRect.width*fx,y=visibleRect.y+visibleRect.height*fy;
+          const top=hit(x,y);n.hitSamples++;
+          if(top && !contains(el,top) && !contains(top,el)){n.occluded++;n.covering.push(path(top));}
+        }
+        n.covering=Array.from(new Set(n.covering));
+      }
+      if(el.localName==='a'&&el.href&&visibleRect.width>0&&visibleRect.height>0) links.push(el.href);
+      if(el.localName==='iframe'&&visibleRect.width>0&&visibleRect.height>0)
+        gaps.push({kind:'iframe',selector,reason:'Frame interior is not inspected by the DOM collector; screenshot only.'});
+      if(el.localName==='canvas'&&visibleRect.width>0&&visibleRect.height>0)
+        gaps.push({kind:'canvas',selector,reason:'Canvas contents require screenshot interpretation or explicit UI assertions.'});
+      nodes.push(n);
+      if(privateNode)continue;
+      // Direct text nodes only: parent/child DOM rectangles are not mistaken for text collisions.
+      for(const child of el.childNodes){
+        if(child.nodeType!==Node.TEXT_NODE||!child.textContent.trim())continue;
+        const range=document.createRange();range.selectNodeContents(child);
+        let ownClip={...clip};
+        const border={x:r.x+el.clientLeft,y:r.y+el.clientTop,width:el.clientWidth,height:el.clientHeight};
+        const clipX=['hidden','clip'].includes(cs.overflowX),clipY=['hidden','clip'].includes(cs.overflowY);
+        if(clipX){const v=intersect(ownClip,{x:border.x,y:ownClip.y,width:border.width,height:ownClip.height});ownClip.x=v.x;ownClip.width=v.width;}
+        if(clipY){const v=intersect(ownClip,{x:ownClip.x,y:border.y,width:ownClip.width,height:border.height});ownClip.y=v.y;ownClip.height=v.height;}
+        for(const tr of range.getClientRects()){
+          if(texts.length>=opts.max_text_rects){truncated=true;break;}
+          const rr=rect(tr),vr=intersect(rr,ownClip);
+          if(rr.width<1||rr.height<1||vr.width<1||vr.height<1)continue;
+          let ancestorClipX=false,ancestorClipY=false;
+          for(let p=parent(el);p;p=parent(p)){const pc=getComputedStyle(p),pr=rect(p.getBoundingClientRect());
+            const cx=pr.x+p.clientLeft,cy=pr.y+p.clientTop;
+            if(['hidden','clip'].includes(pc.overflowX)&&(rr.x<cx-2||rr.x+rr.width>cx+p.clientWidth+2))ancestorClipX=true;
+            if(['hidden','clip'].includes(pc.overflowY)&&(rr.y<cy-2||rr.y+rr.height>cy+p.clientHeight+2))ancestorClipY=true;
+          }
+          texts.push({selector,ancestors,rect:rr,visibleRect:vr,text:child.textContent.trim().slice(0,160),
+            intentional: intentional||cs.textOverflow==='ellipsis'||parseInt(cs.webkitLineClamp)>0,
+            // Clip by viewport is navigation, not a defect. Only local CSS clipping is evaluated below.
+            localClipX:ancestorClipX || (clipX && (rr.x<border.x-1||rr.x+rr.width>border.x+border.width+1)),
+            localClipY:ancestorClipY || (clipY && (rr.y<border.y-1||rr.y+rr.height>border.y+border.height+1)),
+            transformed:cs.transform!=='none',fontSize:parseFloat(cs.fontSize)});
+        }
+      }
+    }
+  }
+  const alignments=opts.alignment.map(a=>({id:a.id,edge:a.edge,tolerance:a.tolerance_px,
+    nodes:Array.from(document.querySelectorAll(a.selector)).map(el=>({selector:path(el),rect:rect(el.getBoundingClientRect())})).filter(n=>n.rect.width&&n.rect.height)}));
+  const clone=document.documentElement.cloneNode(true);
+  // A non-executable semantic serialization, not original HTML/JS source.
+  for(const el of clone.querySelectorAll('script,style,link,iframe,object,embed,base,meta,template')) el.remove();
+  for(const el of [clone,...clone.querySelectorAll('*')]){
+    if(opts.mask_selectors.some(s=>el.matches(s))) {el.textContent='[REDACTED]';el.removeAttribute('value');}
+    for(const attr of Array.from(el.attributes)){
+      const k=attr.name;
+      if(!['id','class','role','type','alt','title','data-testid'].includes(k) && !k.startsWith('aria-')) el.removeAttribute(k);
+      else if(/token|secret|password|bearer/i.test(attr.value)&&k!=='type')el.setAttribute(k,'[REDACTED]');
+    }
+  }
+  let html='<!doctype html>\n'+clone.outerHTML;
+  if(new TextEncoder().encode(html).length>opts.max_html_bytes){html=new TextDecoder().decode(new TextEncoder().encode(html).slice(0,opts.max_html_bytes));truncated=true;}
+  return {schema:'testwins.snapshot/v1',viewport:{width:vp.width,height:vp.height},
+    visualViewport:{width:visual?.width||innerWidth,height:visual?.height||innerHeight,offsetX:ox,offsetY:oy,scale:visual?.scale||1},
+    layoutViewport:{width:innerWidth,height:innerHeight,rootWidth:document.documentElement.clientWidth,rootHeight:document.documentElement.clientHeight},
+    screen:{width:screen.width,height:screen.height},dpr:devicePixelRatio,
+    scroll:{x:scrollX+ox,y:scrollY+oy,layoutX:scrollX,layoutY:scrollY},document:{width:document.documentElement.scrollWidth,height:document.documentElement.scrollHeight},
+    hasViewportMeta:!!document.querySelector('meta[name=viewport]'),fontsStatus:document.fonts.status,
+    title:document.title.slice(0,200),nodes,texts,masks,alignments,links:Array.from(new Set(links)).slice(0,200),
+    gaps,truncated,html,elapsedMs:Math.round(performance.now()-started)};
+}