|
| 1 | +================================================ |
| 2 | +New Features (2026-06-18) — CLI & Integrations |
| 3 | +================================================ |
| 4 | + |
| 5 | +Eight headless capabilities that round out scripting, integration, and |
| 6 | +continuous-integration use: a real command-line interface, |
| 7 | +recording-to-code generation, and first-class HTTP / SQL / email / PDF / |
| 8 | +wait steps. Every feature ships a headless Python API, an ``AC_*`` |
| 9 | +executor command, an MCP tool, and a visual Script Builder entry, and is |
| 10 | +covered by headless tests — the network, SMTP, and PDF backends are |
| 11 | +injected, so nothing touches the outside world. |
| 12 | + |
| 13 | +.. contents:: |
| 14 | + :local: |
| 15 | + :depth: 2 |
| 16 | + |
| 17 | + |
| 18 | +Command-line interface |
| 19 | +====================== |
| 20 | + |
| 21 | +The package now installs a ``je_auto_control`` console script for running |
| 22 | +and inspecting action files from a shell or CI pipeline:: |
| 23 | + |
| 24 | + je_auto_control run script.json --var user=alice --dry-run |
| 25 | + je_auto_control validate script.json # alias: lint |
| 26 | + je_auto_control list-commands --filter mouse --json |
| 27 | + je_auto_control fmt script.json --check |
| 28 | + je_auto_control record out.json --duration 5 |
| 29 | + je_auto_control codegen script.json --target pytest -o test_flow.py |
| 30 | + je_auto_control version |
| 31 | + |
| 32 | +``run`` executes (``--dry-run`` validates and lists steps without acting), |
| 33 | +``validate`` / ``lint`` checks structure and rejects unknown commands, |
| 34 | +``fmt`` canonicalises the JSON, ``record`` captures input, ``codegen`` |
| 35 | +emits source (below), and ``list-commands`` prints the live executor |
| 36 | +catalogue. |
| 37 | + |
| 38 | + |
| 39 | +Code generation |
| 40 | +=============== |
| 41 | + |
| 42 | +Turn a recording or an action file into committable, runnable source:: |
| 43 | + |
| 44 | + from je_auto_control import generate_code, generate_code_file |
| 45 | + |
| 46 | + code = generate_code(actions, target="pytest", style="calls") |
| 47 | + generate_code_file("flow.json", "test_flow.py", target="pytest") |
| 48 | + |
| 49 | +``target`` is ``pytest`` / ``python`` / ``robot``. The default ``calls`` |
| 50 | +style maps each ``AC_*`` command to its facade call |
| 51 | +(``ac.click_mouse(...)``) and falls back to ``ac.execute_action([...])`` |
| 52 | +for flow control and private adapters; the ``actions`` style embeds the |
| 53 | +list and replays it through the executor. |
| 54 | + |
| 55 | +Executor command: ``AC_generate_code``. CLI: ``je_auto_control codegen``. |
| 56 | + |
| 57 | + |
| 58 | +HTTP / API |
| 59 | +========== |
| 60 | + |
| 61 | +A dependency-free HTTP(S) client for hybrid UI + API flows:: |
| 62 | + |
| 63 | + from je_auto_control import http_request |
| 64 | + |
| 65 | + resp = http_request( |
| 66 | + "https://api.example/items", method="POST", |
| 67 | + json_body={"name": "Sam"}, |
| 68 | + headers={"X-Trace": "1"}, |
| 69 | + auth={"type": "bearer", "token": "..."}, |
| 70 | + timeout=30.0) |
| 71 | + assert resp["status"] == 201 |
| 72 | + |
| 73 | +Returns ``{status, ok, headers, text, json, url}``; non-2xx responses are |
| 74 | +returned rather than raised, so you can assert on the status code. Only |
| 75 | +``http`` / ``https`` schemes are allowed. ``AC_http_to_var`` now shares |
| 76 | +the same client, so it can POST bodies and send headers / auth. |
| 77 | + |
| 78 | +Executor command: ``AC_http_request``. |
| 79 | + |
| 80 | + |
| 81 | +SQL |
| 82 | +=== |
| 83 | + |
| 84 | +Read-only, parameter-bound SQLite queries:: |
| 85 | + |
| 86 | + from je_auto_control import query_sqlite |
| 87 | + |
| 88 | + rows = query_sqlite("app.db", "SELECT id, name FROM users") |
| 89 | + count = query_sqlite("app.db", |
| 90 | + "SELECT COUNT(*) FROM users WHERE active = ?", |
| 91 | + params=[1], fetch="scalar") |
| 92 | + |
| 93 | +Queries are restricted to a single read-only ``SELECT`` / ``WITH`` |
| 94 | +statement, run over a read-only connection, with values always bound as |
| 95 | +parameters (never string-interpolated). |
| 96 | + |
| 97 | +Executor commands: ``AC_sql_to_var`` (rows / one row / scalar into a |
| 98 | +variable) and ``AC_assert_db`` (a scalar query asserted with |
| 99 | +eq / ne / lt / gt / contains / ...). |
| 100 | + |
| 101 | + |
| 102 | +Email (SMTP) |
| 103 | +============ |
| 104 | + |
| 105 | +Send mail — for example a flow's report — over the standard library:: |
| 106 | + |
| 107 | + from je_auto_control import send_email |
| 108 | + |
| 109 | + send_email( |
| 110 | + {"sender": "bot@x.com", "to": ["qa@x.com"], |
| 111 | + "subject": "Run passed", "body": "All green", |
| 112 | + "attachments": ["report.html"]}, |
| 113 | + {"host": "smtp.x.com", "port": 587, |
| 114 | + "username": "bot@x.com", "password": "..."}) |
| 115 | + |
| 116 | +TLS is enabled by default (STARTTLS, or implicit SSL when ``use_ssl`` is |
| 117 | +set) over a verified default context; supports multiple recipients, CC, |
| 118 | +HTML bodies, and file attachments. |
| 119 | + |
| 120 | +Executor command: ``AC_send_email``. |
| 121 | + |
| 122 | + |
| 123 | +PDF |
| 124 | +=== |
| 125 | + |
| 126 | +Extract text from and assert on PDF documents (optional ``pypdf`` |
| 127 | +backend — ``pip install je_auto_control[pdf]``):: |
| 128 | + |
| 129 | + from je_auto_control import extract_pdf_text, assert_pdf_text |
| 130 | + |
| 131 | + text = extract_pdf_text("invoice.pdf", pages=1) |
| 132 | + assert_pdf_text("invoice.pdf", "Total: $50.00") |
| 133 | + |
| 134 | +Executor commands: ``AC_pdf_to_var`` (text into a variable) and |
| 135 | +``AC_assert_pdf_text`` (text present / absent, optionally on a page). |
| 136 | + |
| 137 | + |
| 138 | +Smart waits |
| 139 | +=========== |
| 140 | + |
| 141 | +Two waits that replace unreliable ``sleep`` calls:: |
| 142 | + |
| 143 | + from je_auto_control import wait_until_file, wait_until_port |
| 144 | + |
| 145 | + wait_until_file("~/Downloads/report.pdf", stable_for_s=1.0) |
| 146 | + wait_until_port("127.0.0.1", 8080, timeout_s=30.0) |
| 147 | + |
| 148 | +``wait_until_file`` returns once a file exists, is at least ``min_size`` |
| 149 | +bytes, and its size has held steady for ``stable_for_s`` (a download has |
| 150 | +finished). ``wait_until_port`` returns once a TCP connection to |
| 151 | +``host:port`` succeeds — the companion to launching a server. Both return |
| 152 | +a ``WaitOutcome`` and honour a hard ``timeout_s`` cap. |
| 153 | + |
| 154 | +Executor commands: ``AC_wait_for_file``, ``AC_wait_for_port``. |
| 155 | + |
| 156 | + |
| 157 | +Security |
| 158 | +======== |
| 159 | + |
| 160 | +HTTP and SMTP enforce ``http`` / ``https`` or TLS with verified |
| 161 | +certificates and explicit timeouts; SQL is read-only and parameter-bound; |
| 162 | +all user-supplied file paths are resolved with ``realpath`` before I/O. |
0 commit comments