Skip to content

v0.28.3

Choose a tag to compare

@ThorstenBrach ThorstenBrach released this 23 Oct 19:22
· 314 commits to main since this release

TcAgent 0.28.3

All changes since v0.26.2: 0.27.0, 0.28.1, 0.28.2 and 0.28.3 (0.28.0 was a local test build only).
Details: CHANGELOG.md. Guide for the new test window: docs/TCUNIT_TESTS.md.

Please read before updating:

  • Confirmations: when nobody can be asked, runtime actions are now refused. That happens in AI clients that have
    no question dialog. For pipelines or unattended agents, set TCAGENT_CONFIRM=off deliberately.
  • Plain-text ST files have a new format. st export rewrites text folders of earlier builds, and importing an old
    folder is refused until it has been exported again.
  • Report command: a report command in .tcagent\tcunit.json runs only after you approve it once.

Highlights

TcUnit Tests window (0.28.1, 0.28.2)

A window in Visual Studio 2022 and the TwinCAT XAE Shell, close to the Visual Studio Test Explorer. Open it with
View > Other Windows > TcUnit Tests, or with the Tests button of the TcAgent Chat.

  • Tree: PLC project > suite instance > test, read from the code. The /// comments are the descriptions.
  • Toolbar: Run all, Run selected, Run failed, Cancel, Refresh, Expand all and Collapse all.
  • Filters and columns: status filter buttons with counts (combinable) and a search box. Resizable columns
    Test / Duration / Traits / Error Message.
  • Progress: "Test n of N" with % done and the remaining time, and the counter "n of N selected".
  • Details: description, setup, steps and expected result from the code; EXP / ACT / MSG, duration and code
    position. A double-click opens the test method.
  • Selection: tri-state ticks for partly selected suites. Test selections can be saved and loaded (*.tcunit.json).
  • Report button: HTML test report of the last run.
  • The tree is read again after a build and when code files are saved.

Test runs without IDE login, for agents and the command line

  • TcAgent.exe tcunit list | run | report and the tool tc_test_run (action=list|run).
  • The selection uses the enable bools bRunSuite / bRun_<TestMethod>, written via ADS before the start. Tests
    without these bools run as before, everywhere (test / sil / hil and pipelines unchanged).
  • A run, step by step:
    1. Build and activate only if the code changed since the last download.
    2. Reset the PLC via ADS, write the selection and start.
    3. Follow the live results per test from TcUnit's own test table.
    4. Reset again. TwinCAT stays in Run mode.
  • Output and control: one JSON event per line, and a line cancel on stdin stops the run. Optional JUnit file
    and progress block.
  • Selections: --tests @file / tests=@file runs a saved selection.
  • Configuration per solution: <solution>\.tcagent\tcunit.json (plcProject, target, timeout, progress,
    report, reportGroupBy).
  • Remote target: it must be allowed in TCAGENT_ALLOW_TARGETS. The window asks once per run.

HTML test report for every project

  • Built from the descriptions in the code:
    • suites and tests with result, duration, failure text, code position and enable bool
    • run information: target, git commit, TcAgent version, selection
    • search and filters, a summary per suite
  • Test case texts in the code: below its first line, a /// comment can hold the sections Setup:, Steps:
    (1. lines), Expected: (- lines) and Link:. tcunit list returns them as details; the window and the
    report show them.
  • Grouping: reportGroupBy (for example Blocks) adds a second view, grouped by a /// section, switchable with
    the suite view.
  • Results per run: kept in %LOCALAPPDATA%\TcAgent\tcunit\<solution>-<hash>\ as last.xml (JUnit) and
    last.json, outside the repository.

Security

0.28.3

  • Package manager: tc_packages_change no longer runs tcpkg through cmd.exe with administrator rights. Before,
    a feed name like x&calc went unchecked into that command line. Now TcAgent itself runs elevated (UAC prompt) and
    starts tcpkg.exe directly, without a shell, only from the program folders or C:\TwinCAT.
  • tcpkg values: checked before the confirmation and again in the elevated process. tc_packages checks them too.
    • package ids and versions: only [A-Za-z0-9._-]
    • feed names: words of these characters with single blanks
    • feed sources: an http(s) URL or an absolute folder
    • options: from a fixed set only
  • Confirmations: if nobody can be asked (no question dialog in the AI client, no TcAgentBridge dialog in the IDE),
    ads_write, activation, PLC start/stop and the other runtime actions are refused with a clear message. They no
    longer run unconfirmed. The command line (test, sil, hil, tcunit run) is not affected.
  • Report command: the report command of .tcagent\tcunit.json runs only after you approve it once per solution
    and command text, through a question in the window or tcunit report --approve <id>. Until then TcAgent's own report
    is made.
  • HTML report: all texts are HTML-encoded, links are only absolute http(s) URLs, and a Content-Security-Policy
    allows no external resources and no script but the report's own.
  • TcUnit runs:
    • The target of tcunit.json is named in the confirmation and checked against the whitelist.
    • Saved selections cannot set a target.
    • @file reads only *.tcunit.json / *.txt files.

0.27.0

  • Bridge pipe: TcAgentBridge.<pid> is open only for the user running Visual Studio / the XAE Shell, and only on
    this PC (own DACL, no network access). Before, Windows granted Everyone/Anonymous read access and the pipe was
    reachable over the network.
  • Bridge check: TcAgent only talks to a bridge served by Visual Studio or the XAE Shell, where the server process
    id must match the pipe name, and connects with impersonation level Identification. A foreign program behind the pipe
    name is refused, and a confirmation asked through it counts as "no".
  • Pipeline examples: pull requests from forks never run on the self-hosted TwinCAT runner. The GitHub workflows skip
    them, and the Azure Pipelines and GitLab examples name the setting that keeps them off.

Changed

  • Plain-text ST files (st export|check|import, tc_plaintext), new format:
    • every block: declaration, empty line, implementation indented by two blanks, END_ line
    • methods, properties and actions follow after the POU's own END_FUNCTION_BLOCK / END_PROGRAM / END_FUNCTION
    • no // @implementation lines any more
    • whitespace at line ends does not count as a change
    • round trip without changes for all checked objects
  • Dependencies: fixed versions of the shipped packages and a NuGet lock file (packages.lock.json), so the VSIX
    ships only license-checked versions. Beckhoff.TwinCAT.Ads is now 7.0.389 (current release line, MIT); PdfPig stays
    at 0.1.16.
  • THIRD-PARTY-NOTICES completed:
    • System.Reactive
    • the Adobe Glyph List (BSD-3-Clause)
    • the Adobe Core 14 AFM files embedded in PdfPig
    • the notices of the .NET runtime, shipped next to TcAgent.exe in the VSIX
  • setup-clients.ps1 also finds the configuration of newer Claude Desktop versions
    (%LOCALAPPDATA%\Claude-Data\...).
  • Agent guidance: agents write TcUnit suites with enable bools and a /// description per test, so the tests can
    later be selected one by one.
  • README: the source code contains no code from Beckhoff; the trademark owner is Beckhoff Automation GmbH & Co. KG.
  • Menu entry View > Other Windows > TcAgent Chat in Visual Studio 2022 and the XAE Shell.
  • Unit tests (dotnet test tests\TcAgent.Tests, no TwinCAT needed):
    • TcUnitDiscoveryTests for the test discovery and the selection
    • GuardsTests for the security checks
    • PlainTextRepositoryTests, objects of a real library with their reference text files
    • PlainTextLayoutTests, rewritten for the new format

Fixed

  • Updating %LOCALAPPDATA%\TcAgent\app\<version>\ while an AI client still runs TcAgent.exe from there: the
    running file is set aside and the new one copied. Before, the old TcAgent stayed in place ("still in use").
  • Test report, view grouped by reportGroupBy: the suite count of a group counts only the suites that ran.

Install

  1. Close Visual Studio / the XAE Shell.
  2. Double-click TcAgent-0.28.3.vsix.

If the same version is already installed, uninstall it first in Extensions > Manage Extensions. Your memory files in
%LOCALAPPDATA%\TcAgent are kept.