Robot Companion.

Zwei Zeichen machen aus einem Kommentar ein Dokument

Robot Framework gibt dir [Documentation] — einen Block, ganz oben, weit weg von den Schritten, die er beschreibt. Also landet die eigentliche Erklärung dort, wo Erklärungen immer landen: in Kommentaren, direkt neben der Zeile, um die es geht — wo kein Werkzeug sie darstellt und außerhalb des Editors niemand sie je zu sehen bekommt.

Robot Companion liest zwei Kommentarmarker. #> macht aus einer Kommentarzeile Dokumentation, #>> hängt eine Ebene darunter. Mehr Syntax gibt es nicht. Alles Weitere — Überschriften, Aufzählungen, nummerierte Listen, Pfeilnotizen für erwartete Ergebnisse — ist gewöhnliches Markdown zwischen diesen Markern. Die Datei bleibt dabei eine völlig normale Robot-Datei: Nimm die Erweiterung weg, und übrig bleiben Kommentare.

suites/checkout.robotwas du schreibst

*** Test Cases ***
Express Checkout Delivers On The Promised Date
    [Documentation]
    ...    Covers the express lane end to end: a
    ...    basket is built, the order is placed with
    ...    express shipping, and then checked.
    ...
    ...    - Express orders must quote a delivery
    ...        date; standard orders need not.
    ...        -> The date shows on the receipt.
    [Tags]    Checkout    Checkout-Express    Smoke

    #> ## Prepare the basket
    #> - Start from a clean basket so the totals
    #>   stay predictable.
    ${sku}=       Set Variable    DESK-LAMP-002
    ${basket}=    Add Item To Basket    sku=${sku}
    #>> -> The basket id is reused by later steps.

    #> ## Place the order
    #> - Express shipping is the case under test.
    ${order}=    Place Order    basket_id=${basket}
    ...          shipping=EXPRESS
    #>> -> <success>Confirmation returned.</success>

    #> ### What we then assert
    #> 1. The payment was at least authorised.
    #> 2. A tracking id exists.
    #> 3. The delivery date is a real date.
    #>> -> <note>Demo fixtures, not real data.</note>
    Should Be Equal    ${order.payment_state}
    ...                AUTHORISED

Zu diesem Bild. Es zeigt das echte Markup der Documentation Preview: Der Renderer der Erweiterung ist über die Datei links gelaufen, eingefärbt ist das Ergebnis mit den Farbwerten von Dark Modern aus VS Code. Also echte Ausgabe, keine Attrappe — aber eben kein Foto eines laufenden Editorfensters, deshalb fehlt drumherum die Oberfläche von VS Code.

Text, der die Quelle überlebt

Quellzeilen sind kurz, weil Editoren schmal sind; Sätze sind es nicht. Aufeinanderfolgende Dokumentationskommentare wachsen deshalb wieder zu einer durchlaufenden Zeile zusammen, und eine Fortsetzung, die unter einem Aufzählungspunkt oder einem Pfeil eingerückt steht, bleibt bei diesem Punkt, statt ihn zu zerreißen. Willst du wirklich einen Umbruch, dann setz ein <br>. Für umbrochene Fortsetzungszeilen von [Documentation] gilt dasselbe.

Jede gesetzte Zeile weiß, woher sie stammt. Klicke im Panel auf einen Absatz, eine Aufzählung, eine Pfeilnotiz oder eine Überschrift, und der Editor springt genau auf die Quellzeile dahinter — auch auf spätere Zeilen in Blöcken, die einen [Documentation]-Kopf und weiter unten Inline-Marker mischen.

Farbe, die etwas bedeutet

Im Dokumentationstext kennt die Erweiterung fünf semantische Tags und acht schlichte Farb-Tags. Sie erscheinen im Panel und im druckfertigen Export; einen Markdown-Export überstehen sie unverändert, als genau die Tags, die du geschrieben hast. Alles andere — unbekannte Tags, Attribute, beliebiges HTML — kommt als reiner Text heraus, ausgeführt wird nichts davon.

• <note> Hintergrund
• <question> offener Punkt
• <warning> Risiko
• <error> bekannte Abweichung
• <success> bestätigt

Dazu <red>, <orange>, <yellow>, <green>, <blue>, <pink>, <purple>, <gray> und <color value="#0f766e"> für den seltenen Sonderfall.

Was gibt mir dieses Keyword eigentlich zurück?

Die Frage, die du hundertmal am Tag stellst, wenn ein Robot-Test eine Python-Bibliothek steuert. Die Antwort steht in den Typannotationen der Bibliothek, drei Dateien weiter. Robot Companion liest die Python-Quellen deines Workspace und legt einen Index an — statisch, nur lesend; importiert oder ausgeführt wird nichts. Danach reicht ein Hover.

Die Erweiterung sammelt die Bibliotheksmethoden ein, die du mit @keyword dekoriert hast, mit ihren Parameter- und Rückgabeannotationen und ihrem Docstring. Danach geht sie den Rückgabetyp durch: Dataclasses, einfach annotierte Klassen, @property-Member und den Elementtyp in einem list[…] oder einem ähnlichen Container.

@keyword("Place Order")
def place_order(
    self,
    basket_id: str,
    shipping: ShippingMethod = ShippingMethod.STANDARD,
    gift_wrap: bool = False,
) -> OrderConfirmation:
    """Place the prepared basket and return the
    shop's confirmation.

    Args:
        basket_id: Identifier of a basket built by
            `Add Item To Basket`.
        shipping: Which shipping method was picked.

    Returns:
        The confirmation object.
    """

${order.order_id}
${order.total_cents}
${order.currency}
${order.payment_state}
${order.ship_to}
${order.parcels}
${order.total}

# second level
${order.ship_to.street}
${order.ship_to.postcode}
${order.ship_to.city}
${order.ship_to.country}
${order.parcels[0].tracking_id}
${order.parcels[0].method}
${order.parcels[0].delivers_on}

Achte darauf, was da steht: kein Diagramm eines Typs, sondern genau die Zeichenketten, die du als Nächstes tippen würdest — den Index in die Liste inklusive. Genau das bietet die Seitenansicht Robot Return Explorer für die Variable unter deinem Cursor an, und flacher bekommst du dasselbe beim Hover über jede Variable, die aus einem Keyword-Aufruf stammt.

Darunter sitzt ein technischer Abschnitt für die Fälle, in denen du nicht die Pfade willst, sondern die Form — der aufgelöste Typgraph, an jedem Knoten mit der Angabe, als was er erkannt wurde:

OrderConfirmation (dataclass)
  .order_id
  .total_cents
  .currency
  .payment_state
  PaymentState (typed class)
  .ship_to
  Address (dataclass)
    .street
    .postcode
    .city
    .country
  .parcels
  Parcel (dataclass)
    .tracking_id
    .method
    ShippingMethod (typed class)
    .delivers_on
  .total

Aus demselben Index kommen drei Arten von Vorschlägen, und alle drei gibt es nur in Wertpositionen benannter Argumente — hinter argument=, wo ein falscher Tipp dich einen Testlauf kostet:

• Enum-Member. Tippe shipping=, und du bekommst die Member des annotierten Enums. Eine Einstellung legt fest, ob dabei der Name des Members eingefügt wird, sein literaler Wert oder beides.
• Typgleiche lokale Variablen. Variablen aus diesem Test, deren aufgelöster Typ zu dem passt, was das Argument erwartet.
• Rückgabe-Member. Tippe ${order., und die Felder des aufgelösten Rückgabetyps stehen da, bis zu einer einstellbaren Tiefe.

Der Hover löst auch ganz schlichte lokale Werte auf: Stell den Cursor auf eine Variable, die weiter oben im selben Test aus Set Variable oder VAR kommt, und du siehst, was drinsteht. Auch den mehrdeutigen Fall: Hat eine Bedingung ihr zwei mögliche Werte gegeben, sagt der Hover genau das, statt sich für einen zu entscheiden.

Ehrliche Grenzen. Das hier ist statische Analyse von Python-Quelltext, keine Introspektion zur Laufzeit: Aufgelöst wird, was in den Annotationen steht. Keywords ohne @keyword-Dekorator, dynamische Bibliotheken und Rückgaben ohne Annotation bleiben unsichtbar. Und wenn eine Zuordnung mehrdeutig ist, sagt die Keyword-Dokumentationsansicht genau das, statt zu raten.

Falten entlang des Gedankengangs

Ein Test Case mit fünfhundert Zeilen ist vollständig aufgeklappt unlesbar und vollständig zugeklappt nutzlos. Weil die Erweiterung ohnehin weiß, welche Zeilen Überschriften sind, welche Dokumentationsschritte und welche die Robot-Schritte darunter, kann sie auf diese Ebenen falten statt auf Klammern: Headlines lässt die Abschnittstitel hinter #> ## stehen, Steps lässt die Dokumentationszeilen stehen, Unfold stellt alles wieder her.

Das Falten kommt als ganz gewöhnlicher Folding-Range-Provider von VS Code und fügt sich damit in den Editor ein, den du ohnehin hast. Willst du die Ebenen auf den üblichen Tastenkürzeln zum Falten haben, macht ein Befehl die Erweiterung zum Standardprovider für Robot-Dateien.

Über jedem Dokumentationsblock steht eine CodeLens — Open rendered documentation preview —, die ihn im Panel öffnet. Das Panel führt außerdem eine Liste aller dokumentierten Test Cases und Keywords der Datei; die ist zugleich das Inhaltsverzeichnis, mit einem Sprunglink je Eintrag.

Die Dokumentation ließ sich immer schon weitergeben

Irgendwann fragt jemand, was ein Test tut, und dieser Jemand hat VS Code nicht offen. Vier Export-Befehle nehmen den aktuellen Block oder eine Mehrfachauswahl von Blöcken und erzeugen daraus entweder eine Markdown-Datei — abgelegt, wo du willst, und die Farb-Tags bleiben, wie du sie geschrieben hast — oder eine für den Druck gesetzte Seite mit einer Schaltfläche Print / Save as PDF darauf.

Export as Markdownechte Ausgabe, auf die Breite umbrochen

# Express Checkout Delivers On The Promised Date

Covers the express lane end to end: a basket is built,
the order is placed with express shipping, and then
checked.

- Express orders must quote a delivery date; standard
  orders need not.
    -> The date shows on the receipt.
## Prepare the basket
- Start from a clean basket so the totals stay
  predictable.
  -> The basket id is reused by later steps.
## Place the order
- Express shipping is the case under test.
  -> <success>Confirmation returned.</success>
### What we then assert
1. The payment was at least authorised.
2. A tracking id exists.
3. The delivery date is a real date.
  -> <note>Demo fixtures, not real data.</note>

## Variables

- `${sku}`: DESK-LAMP-002

Beide Exporte nehmen die Abschnitte Variables und Returned Variables des Blocks mit: die lokalen Werte, die die Erweiterung aufgelöst hat, und zu jeder zurückgegebenen Variablen das Keyword, aus dem sie stammt. Das exportierte Dokument erklärt damit die Daten des Tests genauso wie seine Schritte.

Was die Erweiterung bewusst nicht tut

Das Regal mit Robot-Framework-Werkzeugen für VS Code ist gut gefüllt, und die meisten davon wollen den Editor für sich. Diese Erweiterung steuert zwei Webview-Ansichten bei, einen CodeLens-Provider, einen Folding-Range-Provider, einen Hover-Provider und einen einzigen Completion-Provider. Mehr Fläche beansprucht sie nicht.

• Kein Formatter, keine Diagnostics. Beides registriert sie gar nicht erst, also kann sie sich darüber auch nicht mit der Erweiterung streiten, die es tut.
• Kein Language Server, keine Laufzeitabhängigkeiten. Das Paket deklariert keine einzige, und mitgeliefert ist nichts, was neben deinem Editor laufen müsste.
• Deine Dateien fasst sie nicht an, solange du es nicht verlangst. Geschrieben wird an genau zwei Stellen: wenn du ein fehlendes benanntes Argument aus der Keyword-Dokumentationsansicht einfügen lässt, und wenn du Dokumentation in eine Datei exportierst, die du selbst aussuchst.
• Während einer Debug-Session geht sie aus dem Weg. Alles, was den Editor umbaut — das Falten etwa —, pausiert, solange eine Robot-Debug-Session läuft.

Wo sie doch etwas kostet, sagt sie es. Einen Workspace zu indexieren ist echte Arbeit, deshalb liegen der Index und die aufgelösten Rückgabetypen im Cache: im Speicher, auf Wunsch pro Workspace auch auf der Platte. Welche Wurzelverzeichnisse durchsucht werden, stellst du selbst ein, und wenn du ganz sichergehen willst, gibt es Invalidate All Caches.

Alles, was die Erweiterung beiträgt

Jeder davon ist in der Referenz beschrieben, mit seinen echten Grenzen und den Voraussetzungen, von denen er abhängt — einschließlich der Teile dieser Erweiterung, die stillschweigend nichts tun, solange deine Python-Keywords nicht eine bestimmte Form haben. Die Einstellungstabelle im README und der Marketplace-Eintrag führen dieselbe Liste mit allen Standardwerten.

Öffne eine .robot-Datei

Die Erweiterung liegt im Visual Studio Code Marketplace, unter der Kennung StochasticEntropy.robot-markdown-companion. Suche in der Extensions-Ansicht nach Robot Companion — oder nimm eine Zeile:

# in VS Code's Quick Open bar — Ctrl/Cmd + P
ext install StochasticEntropy.robot-markdown-companion

# or from a shell, with the code CLI on your PATH
code --install-extension StochasticEntropy.robot-markdown-companion

Wenn du sie lieber selbst baust, statt einem Eintrag im Marketplace zu vertrauen: Das Repository packt sein eigenes .vsix. Das package-Skript ist dasselbe, aus dem auch der veröffentlichte Build entsteht; es legt robot-markdown-companion-<version>.vsix im Klon ab.

git clone https://github.com/StochasticEntropy/robot-companion
cd robot-companion
npm install
npm run package
code --install-extension robot-markdown-companion-*.vsix

So oder so — das ist die ganze Einrichtung. Die Erweiterung aktiviert sich bei Robot-Dateien, indexiert den Workspace im Hintergrund, und die Panels erscheinen unter ihrem Symbol in der Activity Bar. Konfigurieren musst du vorher nichts; die 35 Einstellungen sind für später, wenn du weißt, was du ändern willst.

Das funktioniert auf jeder .robot- oder .resource-Datei, ganz gleich, ob eine andere Erweiterung die Sprach-ID von Robot Framework für sich beansprucht hat — die Provider greifen ebenso über das Dateimuster wie über die Sprache.

Der Eintrag, der Quelltext, der Posteingang

Nichts auf dieser Seite ist die maßgebliche Fassung von irgendetwas. Diese hier sind es.

• Marketplace-Eintrag. Der veröffentlichte Build, die vollständige Liste seiner Beiträge und die Installation mit einem Klick.
• Quelltext auf GitHub. Die Erweiterung selbst — kein minifiziertes Bundle, kein Build-Schritt zwischen dem Repository und dem, was läuft.
• README. Die maßgebliche Fassung von allem, was hier beschrieben wird: Funktionen, Befehle, Einstellungen und die Grenzen an den Rändern.
• Referenz der Inline-Dokumentation. Jede Regel, der der Renderer folgt: die beiden Marker, wie aufeinanderfolgende Kommentare zusammenwachsen, wo ein Umbruch erzwungen werden muss, und das Farbvokabular.
• Notizen zum Caching. Was indexiert wird, wann es verworfen wird und warum der Workspace nicht bei jedem Tastendruck neu durchsucht wird.
• Changelog. Was sich geändert hat, Release für Release.
• Issues. Der Ort für eine falsche Auflösung oder einen Marker, der nicht dargestellt wurde. Eine Datei, die den Fall reproduziert, ist eine Seite Beschreibung wert.
• MIT-Lizenz. Benutze sie, forke sie, liefere sie in etwas anderem mit.