Cloud-Native

Data & KI

Produktentwicklung

Resilienz & IT-Security

Leistungen

Arbeitsweise

Projekte

Berlin

Bielefeld

Dortmund

Erfurt

Frankfurt am Main

Hamburg

Karlsruhe

Leipzig

München

Münster

Nürnberg

Solingen

Stuttgart

Standorte

Blog

Softwerker

Fachmedien

Webinare

Events

Wissens-Hub

Unsere Kultur

Deine Entwicklung

Jobs

Karriere

Über uns

Aktuelles

Kontakt

International contact

Alle Standorte

Du hast Fragen oder möchtest dich mit mir austauschen? Gern - trag einfach deine Kontaktdaten ein.

Kontakt aufnehmen

Marketing & Community Management

Konntest du keine Einträge zu deinem Thema finden?  

Senior IT Consultant | Senior Developer

User Experience Specialist

EnterJS

UX/UI

Webdevelopment

Nein! Doch! Oh!! – Diese 5 Dinge machen Webentwicklung 2023 besser!

<p>React.js ist eine JavaScript-Bibliothek, die auf Konferenzen, in den Sozialen Medien und nicht zuletzt bei der codecentric zunehmend ein Thema wird. Ich hatte es immer auf dem Schirm, bisher aber eher als Nischenthema abgetan. Spätestens jetzt ist es also überfällig, mich mit React.js genauer auseinanderzusetzen.<br /> <span></span></p><p>Spannend finde ich vor allem die Frage: Wann macht es für ein Projekt Sinn, React.js einzusetzen? Und daran anschließend:</p><ul><li>Welches Problem löst React.js für mich?</li><li>Wie reif ist die Bibliothek?</li><li>Wie steht es um die Community, die Dokumentation etc.?</li><li>Ist der resultierende Code wartbar und gut testbar?</li><li>Wie sieht die Integration in bestehende Applikationen aus und wie gut kann ich 3rd-Party-Artefakte integrieren?</li><li>Welche Toolunterstützung steht dem Entwickler zur Verfügung?</li></ul><p>Am Ende des Artikels hoffe ich, dass Du React.js etwas besser einordnen kannst und beurteilen kannst, unter welchen Umständen React was für Dich ist.</p><p>Um das Ganze noch ein wenig anschaulicher zu gestalten, habe ich eine kleine Beispielanwendung gebaut,an der ich einige Konzepte erläutern möchte.<br /> Die Anwendung findet man unter <a href="http://soccerreact.herokuapp.com/">http://soccerreact.herokuapp.com/</a>  und den Sourcecode gibt es unter <a href="https://github.com/holgergp/soccerReact">https://github.com/holgergp/soccerReact</a> <br /> In der Anwendung ist eine Bundesligatabelle nachgebaut, in der man selbst die Vereine hin und herschieben kann. Den ein oder anderen mag das vielleicht an die Beilage aus einem Fußballmagazin erinnern. Das ist reiner Zufall! 😉<br /> <a href="https://media.graphassets.com/9kb2NXrjSmORMEL4Z7sb"><img width="250" height="330" src="https://media.graphassets.com/9kb2NXrjSmORMEL4Z7sb" alt="screenshotSoccerReact" /></a> <br /> Als Bonus kann man die Vereinsnamen noch ändern, in dem man einfach auf den Namen klickt. So kann die Tabelle auch nächste Saison noch aktuell gehalten werden 😉<br /> Richtige Persistenz würde den Scope dieses Artikels sprengen. Der Einfachheit halber werden die anfallenden Daten nur clientseitig im Local Storage gehalten.</p><p>Also steigen wir doch gleich mal ein:</p><h2>Wie reif ist React.js?</h2><p><a href="https://facebook.github.io/react/">React.js</a>  wurde 2013 von Facebook ins Leben gerufen. Die Bibliothek ist u.a. auch bei Facebook selber im Einsatz und steht unter einer BSD-Lizenz. Somit kann man React.js schon eine gewisse Produktionsreife unterstellen. Obwohl, wie der Schwenk von AngularJS 1.x auf AngularJS 2.x gezeigt hat, das Backing von einem großen Konzern leider nicht viel heißen muss.</p><h2>Welches Problem löst React.js für mich?</h2><p>React.js ist, ähnlich wie AngularJS, eine cllientseitige Javascript-Bibliothek.<br /> Der Vergleich hinkt allerdings etwas. Wo AngularJS eine MVC-Struktur abbildet (ob das jetzt gut oder schlecht ist, möchte ich an dieser Stelle nicht diskutieren :)), unterstützt React.js den Entwickler „nur“ beim V (der View) seiner Applikation. Weiter treiben kann man es dann mit der so genannten FLUX-Architektur, in der Komponenten über einen unidirektionalen Kommunikationsfluss über Actions und Stores miteinander kommunizieren.. FLUX werde ich in diesem Artikel allerdings nicht beleuchten, dies würde schlicht zu weit führen.</p><p>Was macht React.js jetzt anders in der View-Schicht?<br /> Aus der Sicht der React-Entwickler ist es schlecht, zu viele Stellen in seiner Anwendung zu haben, die den State einer Anwendung verändern können. Two-way-Databinding ist so ein Beispiel. In größeren Anwendungen ist es zuweilen schwierig zu erkennen, wo Datenänderungen ihren Ursprung haben. In einer React.js Applikation wird forciert, dass es nur eine (oder wenige) Stellen gibt, an der State gehalten und verändert werden kann. Der Inhalt dieses States kann dann immutable in der Anwendung weiter verarbeitet werden.<br /> React.js hat den Ruf, schnell zu sein, besonders im Vergleich zu Angular, und auch mit größeren Datenmengen gut klarzukommen. Das liegt daran, dass im Kern alle State-Änderungen über eine Virtual DOM Implementierung vorgehalten werden und somit der Unterschied von zwei State-Änderungen effizient erkannt werden kann und nur das Ergebnis dieses Diffs in den DOM übertragen wird . Als Entwickler bekommt man hiervon allerdings nichts mit.</p><p>Des Weiteren besteht eine React-Applikation konsequenterweise aus „Komponenten“, also für sich eigenständige Applikationsteile. Hierfür verwendet React einen hierarchischen Ansatz, wobei der State oft in der Wurzel meines Komponentenbaums verortet ist.<br /> Es bietet sich deshalb an, die Anwendung zuerst auf dem Papier in Bereiche (Komponenten) aufzuteilen und den Datefluss zu definieren bevor mit dem Coding begonnen wird. Wie das geht schauen wir uns später genauer an.</p><p>Was wahrscheinlich noch auffällt bei der Verwendung von React.js ist der Einsatz von JSX. <a href="https://facebook.github.io/react/docs/jsx-in-depth.html">JSX</a>  ist ein JavaScript-Erweiterung, die Markup direkt als Sprachelement verwendet. Es ist somit recht einfach Komponenten zu definieren. Das Zusammenbauen von Komponenten sieht beispielsweise so aus:</p><div>

```javascript
render: function () {
    return (
      <div>
        <SampleComponent myProperty={this.state.myProperty}/>
        <SampleForm onConcertSubmit={this.handleConcertSubmit}/>
      </div>
    );
  }
```

</div><p>Man kann zwar auch reines JavaScript einsetzen, allerdings wirkt die Syntax im Vergleich doch eher unhandlich:</p><div>

```javascript
React.createElement(
       "div",
       null,
       React.createElement(SampleComponent, { myProperty: this.state.myProperty }),
       React.createElement(SampleForm, { onConcertSubmit: this.handleConcertSubmit })
    );
);
```

</div><p>Aber es geht. Der Nachteil ist natürlich, dass man für JSX einen Transpiler braucht.</p><h2>Wie steht es um die Community und die Dokumentation?</h2><p>Die Community wächst gefühlt stündlich. Um ein Gefühl zu bekommen ein paar Zahlen zum Vergleich (Stand November 2015):</p><table><tbody><tr><th></th><th>React.js</th><th>AngularJS</th><th>Knockout.js</th></tr><tr><td>Stackoverflow Fragen</td><td>6783</td><td>131663</td><td>14840</td></tr><tr><td>Github-Sterne</td><td>30681</td><td>43967</td><td>6900</td></tr><tr><td>Google Hits</td><td>695.000</td><td>12.600.000</td><td>558.000</td></tr></tbody></table><p>Aus den Zahlen würde ich zwei Sachen ziehen:</p><ul><li>Angular ist momentaner Mainstream</li><li>React hat durchaus schon Relevanz</li></ul><p>Die Dokumentation von React.js fand ich im Vergleich zu anderen Bibliotheken und Frameworks recht gut. Ich fühlte mich gut abgeholt, die Dokumentation geht aber auch bei Bedarf in die Tiefe. Hier schon einmal Daumen hoch. Die Qualität der <a href="https://facebook.github.io/react/docs/getting-started.html">Dokumentation</a>  von AngularJS, speziell im Bereich Testing, erreicht React.js aber noch nicht.</p><h2>Die Beispielanwendung</h2><p>Dies ist der Moment, an dem wir uns etwas mehr mit der Beispielanwendung befassen: Das Anlegen des Grundgerüsts über einen Yeoman-Generator (https://github.com/newtriks/generator-react-webpack) ging schnell von der Hand.<br /> Als erstes wird die App in Komponenten zerlegt. Heraus kommt eine recht einfache, aber hilfreiche Struktur:<br /> <a href="https://media.graphassets.com/g4J2FqQbQ9qqLdhpCLMU"><img loading="lazy" width="250" height="398" src="https://media.graphassets.com/g4J2FqQbQ9qqLdhpCLMU" alt="komponentenSoccerReact" /></a> </p><p>Diese Struktur findet sich auch direkt im Code wieder:<br /> Unter <em>src/components</em> liegen die Artefakte:</p><ul><li><em>App.js</em></li><li><em>LeagueTable.js</em></li><li><em>Position.js</em></li><li><em>Team.js</em></li></ul><p> die eine direkte Entsprechung in der Grafik haben. Dazu kommt noch <em>run.js</em>,das die Anwendung startet und noch ein Artefakt für Konstanten.</p><p>Den State der Anwendung verwalten wir, wie oben skizziert, an einer Stelle. Das ist hier die Ligatabelle (LeagueTable).  Die augenscheinlichste Methode einer React-Komponenten ist die <em>render</em>-Funktion. Diese wird immer dann aufgerufen, wenn React eine Änderung feststellt und die Komponente mit einem neuen Zustand rendern möchte.<br /> In der <a href="https://github.com/holgergp/soccerReact/blob/01_Plain/src/components/LeagueTable.js#L18-L37">Ligatabelle</a>  definieren wir das Grundgerüst der HTML-Struktur und einige Callbacks für die Logik. Zu den Callbacks komme ich allerdings erst später.</p><p>Zur Struktur:</p><div>

```javascript
var positionNodes = this.state.positions.map(function (posIter) {
      return (
        <Position position={posIter} key={posIter.position}/>
      );
    });
 
return (
 <div className="col-md-6">
   <div className="panel panel-primary">
     <div className="panel-heading">
       <h3 className="panel-title">Ligatabelle</h3>
     </div>
     <div className="panel-body">
       {positionNodes}
     </div>
   </div>
 </div>
);
```

</div><p>Sieht erstmal recht vertraut aus. Ungewohnt kann nur sein, dass wir hier Markup und JavaScript vermischen. Aber da habe ich mich schnell dran gewöhnt.<br /> Zwei Dinge sind an dieser Stelle noch spannend: Zum einen bauen wir hier einen – Tag, der die Position-Komponente referenziert (die wir <a href="https://github.com/holgergp/soccerReact/blob/01_Plain/src/components/LeagueTable.js#L2">oben im File</a>  referenziert haben).<br /> Zum anderen sieht man hier, dass wir (im Gegensatz zu den weiteren Komponenten) auf der <em>.state </em>Eigenschaft der Komponente arbeiten.</p><p>Die weiteren Komponenten sind dann im Kern viel simpler. Wenn wir kurz auf die <a href="https://github.com/holgergp/soccerReact/blob/01_Plain/src/components/Position.js">Positionen</a>  schauen. Hier sieht (ein Teil) der <em>render</em>-Funktion wie folgt aus:</p><div>

```javascript
render: function () {
    const position = this.props.position;
    const team = this.props.position.team;
    return (
      <div>
        <span>
         <Team team={team} positionNumber={position.position} />
      </span>
      </div>
    );
  }
```

</div><p>Hier und in den weiteren Kind-Komponenten greifen wir nicht mehr auf den State zu, sondern auf <em>.props</em>.Diese sind immutable. So haben wir nur eine Stelle, an der wir den State halten und ändern. Das <a href="https://github.com/holgergp/soccerReact/blob/01_Plain/src/components/Team.js">Team</a>  sieht in der statischen Struktur ähnlich aus.<br /> Schauen wir uns nun doch einmal die Logik an:<br /> Der erste Punkt, den ich umgesetzt habe, war <strong>DragAndDrop</strong>: Hier macht die Unterscheidung zwischen Team und Position Sinn. Die Positionen bleiben starr, nur die Zuordnung der Teams zu den Positionen ändert sich beim DragAndDrop.<br /> Um DragAndDrop umzusetzen, habe ich <a href="https://github.com/gaearon/react-dnd">react-dnd</a>  zur Hilfe genommen. In das Verdrahten von DragAndDrop will ich gar nicht einsteigen. Nur so viel: DropTarget sind die Positionen, DragSource sind die Teams.<br /> Spannend ist hier allerdings: <a href="https://github.com/holgergp/soccerReact/blob/04_WithDragAndDrop/src/components/Team.js#L18-L30">Am Ende eines Drag-Vorgangs</a>  rufen wir ein Callback auf, den wir in der LeagueTable <a href="https://github.com/holgergp/soccerReact/blob/04_WithDragAndDrop/src/components/LeagueTable.js#L78-L108">definiert</a>  und runtergereicht haben. Hier ist dann die zentrale Stelle, an der wir die Tabelle umsortieren.</p><p>Der zweite Punkt ist das <strong>Editing</strong> der Team-Namen: Hierfür habe ich <a href="https://github.com/bmcmahen/react-wysiwyg">react-wysiwyg</a>  verwendet. Das Pattern sieht hier ähnlich aus. In der Team-Komponente definieren wir das <a href="https://github.com/holgergp/soccerReact/blob/03_WithEditing/src/components/Team.js#L47-L57">Markup</a> :</p><div>

```javascript
<ContentEditable
  tagName='div'
  onChange={onChange}
  className='textPointer'
  html={team.name}
  autofocus={true}
  maxLength={200}
  editing={this.props.team.editing}
  preventStyling
  noLinebreaks
 />
```

</div><p>Der Callback ist wiederum in der <a href="https://github.com/holgergp/soccerReact/blob/03_WithEditing/src/components/LeagueTable.js#L68-L89">Ligatabelle</a>  definiert.</p><p>Der dritte erwähnenswerte Punkt ist <strong>LocalStorage</strong>. Hierfür ist wiederum die <a href="https://github.com/holgergp/soccerReact/blob/02_WithLocalStorage/src/components/LeagueTable.js#L10-L26">Ligatabelle</a>  verantwortlich: Hierfür verwenden wir weitere Funktionen einer React-Komponente: <em>getInitialState</em> und <em>componentDidUpdate</em>.</p><p><em>getInitialState</em> definiert den Anfangszustand einer Komponente. Hier überprüfe ich, ob LocalStorage vorhanden ist und ob passende Daten im LocalStorage hinterlegt sind. Abhängig davon werden entweder Default-Werte oder die gespeicherten Werte geladen.<br /> <em>componentDidUpdate</em> wird aufgerufen, wenn sich die Komponenten geändert haben. Hier lege ich den aktuellen Zustand im LocalStorage ab.</p><p>Um die Entwicklung des Sourcecodes besser nachvollziehen zu können, habe ich für jeden Entwicklungsschritt einen Branch angelegt: Angefangen von einer Variante <a href="https://github.com/holgergp/soccerReact/tree/01_Plain">ohne Dynamik</a> , bis zu <a href="https://github.com/holgergp/soccerReact/tree/04_WithDragAndDrop">vollständigen Version mit DragAndDrop.</a> </p><h2>Ist der resultierende Code gut wartbar und testbar?</h2><p>Ich habe für das Testing <a href="http://jasmine.github.io/">Jasmine</a>  verwendet und exemplarisch einige Unittests für die <a href="https://github.com/holgergp/soccerReact/blob/04_WithDragAndDrop/test/components/MainTest.js">LeagueTable</a> -Komponente geschrieben. Hier sind mir in der Tat gar nicht so viele Besonderheiten aufgefallen. Das Test-Arrangement ist etwas ungewöhnlich, das virtuelle Rendering mag etwas verwirren. Dies wird aber über React-Utilities gut unterstützt. Kann man React-Anwendungen also gut unittesten? Ja!</p><p>Dadurch dass React den Entwickler dazu ermutigt, die Anwendung in Komponenten zu zerschneiden und der State auch nur an wenigen Stellen gehalten wird, ist die Applikation schon von Grund auf recht gut wartbar. Was vielleicht etwas kritischer sein kann, ist dass die Zustandshaltende Komponente (hier die Ligatabelle) doch recht überfrachtet wirken kann. Mit der FLUX Architektur kann aber auch dieses Problem sehr elegant adressiert werden.</p><p>Was ich während der Entwicklung schön fand, waren die sehr gut unterstützenden Fehlermeldungen und Logs. Das kennt man schlechter! JSX kann vielleicht etwas ungewohnt wirken (“Warum noch eine Sprachvariante?”), ich sehe den Einsatz momentan aber als klares Plus.</p><p>Es hat zwar ein wenig gebraucht, um in die React-Denke reinzukommen, aber die Entscheidungen sind nachvollziehbar und das Ergebnis finde ich sehr schön.</p><h2>Integration</h2><p>Wie am Beispiel gezeigt, ist es nicht sonderlich aufwändig über Third-Party-Bibliotheken komplexere Funktionalität nachzurüsten, um auch anspruchsvollere Anforderungen umzusetzen. Die Integration in bestehende Anwendungen ist natürlich auch möglich. Als ein Beispiel sei hier <a href="https://github.com/ngReact/ngReact">ngReact</a>  genannt. Allerdings muss man dieses natürlich immer im Einzelfall beleuchten.</p><h2>Tooling</h2><p>Die verwendete Toolchain ist im Vergleich zu anderen JavaScript-Stacks ähnlich. Allerdings mag sich in einigen Konstellation das Verwenden eines Transpilers wie Babel noch ungewohnt anfühlen. Als Fallback böte sich dann JavaScript (ES5) an.<br /> Ich habe die Anwendung mit IntelliJ entwickelt und dort wurde ich ordentlich unterstützt, kann ich also empfehlen</p><h2>Wann macht React.js Sinn?</h2><p>React.js macht vielleicht nicht in jeder Situation Sinn, in der clientseitige Logik oder auch SPAs eingesetzt werden soll. Dafür ist das Investment in die Toolchain und die Art der Denke vielleicht noch zu weit weg vom Mainstream.<br /> In mindestens zwei Szenarien ist es aber meiner Ansicht nach sehr sinnvoll. Zum einen, wenn man ein in sich abgeschlossenes Widget baut (sowie vielleicht die Ligatabelle) oder aber wenn in der Applikation viele Daten verarbeitet und angezeigt werden sollen und Performance ein Thema ist. Desweiteren ist in diesem Kontext ein Blick auf <a href="https://facebook.github.io/react/docs/flux-overview.html">FLUX</a>  lohnenswert, um auch größere Anwendungen mit React zu bauen.</p><p>Viel Spaß beim Ausprobieren von React.js!</p>

React.js im Praxischeck

<p>Unit Tests sind in vielen Bereichen der Software-Entwicklung gesetzt und leisten gute Dienste. In vielen Java-Projekten zum Beispiel gehören sie zum Standard. Das Tooling ist gut, und es herrscht weitgehend Konsens unter den Entwicklern, dass Unit Tests dem Projekt helfen. Auch Test Driven Development (TDD) ist mit dieser Toolunterstützung sehr gut möglich.<br /> Bei der Entwicklung von Frontends in Web-Projekten sind Unit Tests und TDD weniger etabliert, obwohl wir gerade im Frontend-Bereich eine stark wachsende Komplexität beobachten können: Eine zeitgemäße Web-GUI soll einer Desktop-Anwendung in nichts nachstehen.<br /> Ein Grund aus meiner Sicht: Das Aufsetzen einer Unit-Test-Umgebung in JavaScript-Projekten ist umständlicher als zum Beispiel mit Maven oder Gradle in der Java-Welt.<br /> Als Software Craftsman möchte in diesem Blog Post einige Impulse geben, um Unit Tests stärker im JavaScript-Umfeld zu etablieren.<br /> Im Folgenden stelle ich mit <a href="https://facebook.github.io/jest/" target="_blank">Jest</a>  eine Testbibliothek von Facebook vor, die uns genau an dieser Stelle helfen kann. Es wurde bei Facebook im Umfeld von React entwickelt, ist aber nicht darauf beschränkt. Ich gebe eine kleine Einführung in den Funktionsumfang von Jest und zeige, wie schnell es für ein Projekt betriebsbereit ist.</p><h2>Am Anfang war der Coderetreat …</h2><p>Meine erste Berührung mit Jest hatte ich nicht im Rahmen eines Kundenprojekts, sondern während eines Coderetreats. In einem Coderetreat geht es darum, in relativ kurzer Zeit eine Lösung für ein überschaubares Problem testgetrieben zu entwickeln. Man möchte hier also nicht viel Zeit in die Technik und die Infrastruktur stecken. In diesem Kontext waren für mich lange Zeit Java und Maven gesetzt, weil sie so schnell einsatzbereit sind. Mit JavaScript habe ich auch öfters experimentiert, es war aber immer viel umständlicher. Mein Vorgehen lief dann meistens auf eine Kombination von <a href="https://jasmine.github.io/" target="_blank">Jasmine</a> , <a href="https://karma-runner.github.io/" target="_blank">Karma</a> , <a href="https://babeljs.io/">Babel</a>  und <a href="https://www.jetbrains.com/idea/" target="_blank">IntelliJ</a>  + x raus. Richtig zufriedenstellend war dies leider nie.<br /> Ähnlich sieht dies im Kundenprojekt für viele Entwickler aus: Das Setup zum Aufsetzen von Tests für unseren Java Code ist sehr einfach. Wir können uns sehr schnell auf die Tests zu der Fachlichkeit fokussieren.<br /> Beim Testen im Frontend fehlt oft die Zeit, die Hürden bei der Einrichtung der Umgebung zu umschiffen. Man braucht vergleichsweise lang, bis der Entwickler an den Punkt kommt, sich nur auf den Inhalt des Tests konzentrieren zu können.<br /> Ich habe dann während eines Coderetreat einmal <a href="https://github.com/facebookincubator/create-react-app" target="_blank">create-react-app</a>  ausprobiert. create-react-app ist ein Tool, das eine React-Applikation sehr schnell erzeugen (scaffolden) kann. Für ein Coderetreat viel zu viel. Aber das Tool bringt zudem eine sehr schöne Möglichkeit mit, Tests bei Codeänderung auszuführen, stellt die Testergebnisse sehr übersichtlich dar und kann ES6+ schon out-of-the-box ausführen. Super!<br /> Das Ganze kriege ich ohne Mehraufwand auch ohne React-Abhängigkeit hin: <strong>Mit Jest!</strong></p><h2>Schauen wir uns Jest also mal genauer an:</h2><p> Die Installation ist relativ unspektakulär: <code>npm install --save-dev jest</code><br /> Und folgenden Schnipsel in die package.json</p><div>

```javascript
{
  "scripts": {
    "test": "jest"
  }
}
```

</div><p>Oder vielleicht sofort:</p><div>

```javascript
{
  "scripts": {
    "test": "jest --watch"
  }
}
```

</div><p>Meine Tests kann ich dann per <code>npm test</code> starten und weise Jest per <code>--watch</code> an, bei Änderung von Dateien die Tests laufen zu lassen.<br /> Jest erkennt Tests automatisch im <a href="https://facebook.github.io/jest/docs/configuration.html#testmatch-array-string" target="_blank">Default</a>  daran, dass ein ‘.test’ im Namen vorkommt. Also zum Beispiel ist ein Test zu sum.js -> sum.test.js<br /> Jest basiert auf <a href="https://jasmine.github.io/" target="_blank">Jasmine</a>  und erfindet somit die Testformulierung auch nicht neu. Jest-Tests sollten also für viele Entwickler gut lesbar sein.<br /> Als Beispiel <em>sum.test.js</em></p><div>

```javascript
const sum = require('../src/sum');
 
test('adds 1 + 2 to equal 3', () => {
 expect(sum(1, 2)).toBe(3);
});
```

</div><p>Wir haben also bis hierhin: ES6 in Tests und einen Watchmodus, ohne etwas zu konfigurieren. Dazu noch eine Testsyntax, die – zumindest mir – immer sehr gefallen hat. Soweit so gut.<br /> Was ich nun super finde, ist die Übersichtlichkeit, mit der Jest seine Testergebnisse (auf der Kommandozeile) darstellt.<br /> Ändern wir mal in <em>sum.js</em>:</p><div>

```javascript
function sum(a, b) {
 return a + b +1;
}
```

</div><p><a href="https://media.graphassets.com/lBGHPmjR4KSlM0oATIWw"><img width="700" height="294" src="https://media.graphassets.com/lBGHPmjR4KSlM0oATIWw" alt /></a> </p><p>Sehr schön! Und klappt out-of-the-box!<br /> Fügt man nun noch den Parameter <code>--coverage</code> hinzu, spendiert uns Jest direkt noch eine Code-Coverage-Analyse:</p><p><a href="https://media.graphassets.com/nGzxwPcTPCZgWfWXFCnh"><img loading="lazy" width="700" height="321" src="https://media.graphassets.com/nGzxwPcTPCZgWfWXFCnh" alt /></a> </p><h2>Wait! There’s more: Snapshot Testing</h2><p> Ein richtig tolles Features ist auch das sogenannte Snapshot Testing:<br /> Die Idee hier ist, dass ich das Ergebnis einer Funktion aufzeichnen und dann in folgenden Testläufen den Wert des ersten Laufs mit dem Wert der folgenden Läufe vergleichen kann. Dies kann zu sehr knappem Testcode führen. Snapshot Testing ist hilfreich, falls das Aufbauen einer Vergleichsstruktur so aufwändig ist, dass es die Testintention verwässert:<br /> Snapshot Tests kommen wie gerufen, wenn man wie in React viel Markup und Änderungen im Markup testen möchte.<br /> Dieses Vorgehen ist aber auch praktisch, wenn man zum Beispiel Strings vergleichen möchte. Ein kleines Beispiel, um die Idee zu verdeutlichen:<br /> Wir haben eine Funktion, die einen String zurückgibt:</p><div>

```javascript
exports.renderSomething = () => {
   return "My rendered String"
}
```

</div><p>Der zugehörige Test kann wie folgt aussehen:</p><div>

```javascript
test('renders correctly', () => {
 expect(foo.renderSomething()).toMatchSnapshot();
});
```

</div><p>Im ersten Testdurchlauf wird ein sogenannter Snapshot angelegt – und kein Vergleich durchgeführt. Im Hintergrund hat Jest im Testordner ein Verzeichnis <code>__snapshots__</code> und eine Snapshot-Datei erzeugt. Der Inhalt sieht wie folgt aus:</p><div>

```javascript
exports[`renders correctly 1`] = `"My rendered String"`;
```

</div><p>Dann ändern wir eine Kleinigkeit in unserer Funktion:</p><div>

```javascript
exports.renderSomething = () => {
   return "My rendered String changed"
}
```

</div><p>Daraufhin meldet Jest uns:</p><p><a href="https://media.graphassets.com/dKvWxlJQRaagSzmNEkiH"><img loading="lazy" width="700" height="279" src="https://media.graphassets.com/dKvWxlJQRaagSzmNEkiH" alt /></a> </p><p>Jest weißt uns darauf hin, dass sich der Wert geändert hat. Wir mussten uns nicht selbst um Testdaten kümmern. Sehr elegant!<br /> Wenn wir nun feststellen, dass der neue Wert korrekt ist, können wir mit <code>jest -u</code> den Snapshot aktualisieren. Keine Angst, es gibt auch die Möglichkeit, über Pattern einzelne Snapshots zu <a href="https://facebook.github.io/jest/docs/cli.html#updatesnapshot" target="_blank">aktualisieren</a> . Die Snapshot-Dateien werden sinnvollerweise auch im VCS mit eingecheckt.</p><p>Dieses einfache Beispiel können wir noch ein wenig weiter denken: auch beim Testen von Legacy Code und der Verwendung eines <a href="http://craftedsw.blogspot.de/2012/11/testing-legacy-code-with-golden-master.html" target="_blank">Golden Masters</a>  extrem praktisch.</p><p>In der Praxis muss man im Team meiner Ansicht nach eine Balance zwischen Snapshot-Tests und Tests mit echt formulierten Testdaten finden, um die Wartbarkeit der Tests nicht von dieser Seite zu untergraben: Snapshot Tests sollen bewusst dort helfen, wo vielleicht sonst gar keine Tests geschrieben worden wären.</p><h2>One more thing: Mocking:</h2><p>Auch eine Lösung für das Mocking bringt Jest direkt mit.<br /> Wie man das zum Beispiel von Mockito aus der Java-Welt kennt, können Mock-Funktionen erzeugt werden, die ich dann nach dem Aufruf befragen kann:</p><div>

```javascript
const myMock = jest.fn();
 
test('does mocking work', () => {
 bar(myMock)
 expect(myMock.mock.calls.length).toBe(1);
 expect(myMock.mock.calls[0][0]).toBe("First");
});
 
function bar(collab) {
   collab("First");
}
```

</div><p>In diesem Beispiel testen wir, dass unser Mock genau einmal aufgerufen wurde und dass der erste Parameter “First” ist.</p><p>Man kann auch noch einen anderen Weg wählen und ganze Module wegmocken.<br /> Nehmen wir einmal das nachfolgende Request-Modul, welches eine Funktion für eine HTTP-Anfrage bereitstellt:</p><div>

```javascript
function fetchData(callback) {
   let url="http://localhost:3000/hello";
   http.get(url, response => {
   let data = '';
     response.on('data', _data => data += _data);
     response.on('end', () =>  callback(data));   
   });
}
```

</div><p>Unser Modul spricht über das Netzwerk, und das wollen wir natürlich für den Test nicht:<br /> Wir wollen dies mit folgendem Mock ersetzen:</p><div>

```javascript
function fetchData(callback) {
   callback('{"hello":"world"}');
};
```

</div><p>Wie kann das nun im Test aussehen?</p><p>Mit</p><div>

```javascript
jest.mock('../src/request');
```

</div><p> weisen wir Jest nun an, unser Request Modul wegzumocken.<br /> Jest sucht dann auf gleicher Ebene wie das Testsubjekt einen Mock.</p>

```

├── __mocks__
│   └── request.js
├── foo.js
├── request.js
└── sum.js

```

<p>Unter <code>__mocks__/request.js</code> muss dann unser Mock liegen.</p><p>Dann könnte ein Test wie folgt aussehen:</p><div>

```javascript
const request = require('../src/request');
jest.mock('../src/request');
 
test('async callback', (done) => {
 function callback(data) {
 
   expect(JSON.parse(data)).toEqual({"hello":"world"});
   done();
 }
request(callback);
});
```

</div><p>Dies kann praktisch sein, allerdings finde ich die Konvention <code>__mocks__</code> gewöhnungsbedürftig.</p><h2>Eine Ausrede weniger</h2><p>Zusammengefasst ist es schon beeindruckend, wie weit man mit Jest alleine kommt, ohne Zusatzbibliotheken nutzen zu müssen.<br /> Darüberhinaus hat Jest noch einige Features, die speziell für React zugeschnitten sind – aber auch für ein Projekt ohne React Unterbau ist Jest ein sehr gute Wahl. Nicht nur, wenn es darum geht, möglichst schnell eine Testinfrastruktur aufzusetzen.<br /> Eine Ausrede weniger, keine JavaScript Tests zu schreiben.<br /> Ich hoffe euch hat dieser kleine Einblick in das Unit Testen mit Jest genauso viel Spaß gemacht wie mir! Die Codebeispiele findet ihr <a href="https://github.com/holgergp/jestPlayground" target="_blank">hier</a> . Happy Testing!</p>

JavaScript Unit Tests sind schwer aufzusetzen? Keep calm and use Jest!

Grunt, Karma, Webpack und Co. – Toolchains für JavaScript-Projekte

BDD und End-to-End-Tests – Cypress.io mit Cucumber verbinden

 <p><a href="https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html">TypeScript 4.5</a>  führt unter anderem einen neuen Utility Type ein: <code>Awaited</code>.<br /> In diesem Blogpost möchte ich erklären, was dieser tut, welche Probleme er löst und wo er für uns nützlich sein kann. Stefan Spittank und ich haben zu diesem Thema auf unserem Youtube-Kanal <a href="https://www.youtube.com/c/papperlapapp-dev">Papperlapapp</a>  auch ein <a href="https://youtu.be/sZsomKMSKTU">Video</a>  zu dem Thema aufgenommen. Schaut doch auch mal da rein.</p> <p><span></span></p> <p>Falls ihr mitprogrammieren wollt: Ihr findet <a href="https://github.com/holgergp/typescriptAwaited">hier</a>  meine Beispiel-Sourcen mit den Experimenten mit dem <strong>Awaited Type</strong>.<br /> Ich habe für das Wechseln zwischen zwei TypeScript-Versionen die VS-Code-Funktionalität zum Wechseln der TypeScript-Version verwendet.</p> <h2>TypeScript 4.5</h2> <p><a href="https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html">TypeScript 4.5</a>  erschien im November 2021. Eine neue Minor-Version von TypeScript löst bei mir normalerweise keine Begeisterungsstürme aus. Auch die Features lesen sich nett, aber sie sind für mich jetzt keine Revolution.<br /> Allerdings gibt es da ein Feature, das mich neugierig gemacht hat: der <strong>Awaited Type</strong>! Interessant auch, weil ich die Intention auf den ersten (und zweiten Blick) nicht verstanden habe. Aber bevor wir uns den Awaited Type anschauen, werfen wir doch einen schnellen Blick auf einige weitere Änderungen:</p> <h3>Import Assertions</h3> 

```typescript
import obj from "./something.json" assert { type: "json" };
```

<p>Ich kann nun beim Import den Typ der Datei überprüfen. Praktisch, aber für mich nicht weltbewegend.</p> 
<h3>Private Field Presence Checks</h3> 

```typescript
class Person {
   #name: string;
   constructor(name: string) {
       this.#name = name;
   }
   equals(other: unknown) {
       return other &&
           typeof other === "object" &&
           #name in other && // <- this is new!
           this.#name === other.#name;
   }
}
```
<p>Ich kann nun mit dem <code>in</code>-Operator überprüfen, ob es auf einem Object eine private Property gibt. <em>Private Property</em> meint hier: ECMA-Script private Property <code>#</code>, nicht das TypeScript <code>private</code>-Keyword.<br /> Auch nett. Ich arbeite allerdings recht selten mit Klassen, dies habe ich noch nicht vermisst.</p> 

<h3>Disabling Import Elision</h3>

 ```typescript
import { Animal } from "./animal.js";
eval("console.log(new Animal().isDangerous())");
```
<p>Ich kann nun mit dem Compiler-Flag <a href="https://www.typescriptlang.org/tsconfig#preserveValueImports">preserveValueImports</a>  verhindern, dass solcherlei Imports von TypeScript entfernt werden, da sie ja anscheinend nicht benutzt werden. 



Klingt erstmal unnötig, allerdings kann dies für Vue- oder Svelte-Entwicklung durchaus praktisch sein.</p> <p>Zum Beispiel für diesen Vue-Code hier:<br /> </p> 

```jsx
<script setup>
 import { someFunc } from "./some-module.js";
</script>
<button>Click me!</button>
```

<h3>Template String Types as Discriminants</h3> <p>TypeScript 4.5 kann nun auch Werte innerhalb eines Template Strings auswerten und Rückschlüsse auf den Typ ziehen:</p> 

```typescript
export interface Success {
  type: `${string}Success`;
  body: string;
}
 
export function handler(r: Success | Error) {
  if (r.type === "HttpSuccess") {
    // (parameter) r: Success
    const token = r.body;
  }
}
```

 <p>Das ist alles irgendwie ganz praktisch, hat für mich aber nicht so große praktische Auswirkungen!<br /> Aber irgendetwas hat dann doch meine Aufmerksamkeit geweckt.</p> <h2>Der Awaited Typ</h2> <p>Die <a href="https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#the-awaited-type-and-promise-improvements">Dokumentation</a>  beschreibt einen <strong>Awaited</strong> Typ!<br /> Ich habe mich schon <a href="https://www.youtube.com/watch?v=KUad1vqPjo8">länger</a>  mit <a href="https://www.youtube.com/watch?v=2NEHFd-NJ_E">Async/Await</a>  beschäftigt.<br /> Ich finde dass dies ein spannendes, allgegenwärtiges Thema ist, in dem aus meiner Sicht immer noch genug Fallstricke lauern.<br /> Und jetzt kommt da Compiler-Unterstützung! Ich war begeistert!<br /> In meinem Kopf wurde schon durch Type Inference für immer das Problem des vergessenen Await gelöst. Das klingt wunderbar. Dann klingelte der Wecker … oder so ähnlich.</p> <p>Der <strong>Awaited</strong> Typ ist super! Aber er löst eigentlich eine ganz andere Art Problem, wenn auch eine verwandte Art Problem.</p> <p>Aber fangen wir mal langsam an:</p> <p>Meine erste Begeisterung habe ich sofort in Code gegossen:</p>

```typescript
async function usingAwaitedAsAReturnType(): Awaited {
   const result = await Promise.resolve(true)
   return result;
}
```

 <p><code>Awaited</code> ist <em>natürlich</em> der Return Type einer async-Function! Richtig? <strong>Falsch</strong>!</p> <p>Der Compiler sagt dazu:</p> <blockquote><p><code>The return type of an async function or method must be the global Promise type. Did you mean to write 'Promise'?ts(1064) </code></p></blockquote> <p>Meh! Leicht enttäuscht habe ich mir dann widerwillig erstmal die Dokumentation angeschaut. Was macht <em>Awaited</em> überhaupt?</p> <blockquote> <p>This type is meant to model operations like await in async functions, or the .then() method on Promises – specifically, the way that they recursively unwrap Promises.</p> </blockquote> <p>Ah! Es geht also eher um den „<em>await</em>”-Teil als um den „<em>async</em>” Teil von async/await!<br /> <em>Recursively Unwrap</em> Promises! Moment! Gibt es überhaupt verschachtelte Promises in JavaScript? Also zumindest nicht zur Laufzeit! Was soll das Ganze dann? Scheinbar gibt es Situationen, in denen das TypeScript-Typsystem nicht erkennen kann, welcher Typ in verschachtelten Promises steckt. Interessant!</p> <h3>Ausprobieren!</h3> <p>Wir erzeugen uns mal drei Promises-Typen mit unterschiedlichem Verschachtelungsgrat. Auf Typsystem-Ebene geht das ja.</p> 

```typescript
let a: Promise<string>;
let b: Promise<Promise<string>>;
let c: Promise<Promise<Promise<string>>>
```

 <p>Dazu gibt es eine Variable mit dem neuen <strong>Awaited</strong> Type. <em>Awaited</em> ist ein generischer Typ. Wir geben mal den Typen von Variable <code>c</code> dort hinein:</p>

```typescript
let d: Awaited<typeof c>
```

<p>Und als letztes noch eine schnöde Variable vom Typ <code>string</code></p> 

```typescript
let e : string
```
 <p>Nun vergleichen wir die Variablen:</p> 

```typescript
a===b
// error always returns false
// This condition will always return 'false' since the types 'Promise<Promise<string>>' and 'Promise<Promise<Promise<string>>>' have no overlap.ts(2367)
b===c
// error always returns false
```
<p>Wenn wir <code>a</code>, <code>b</code> und <code>c</code> vergleichen, sagt uns der Compiler schon: Die Variablen können gar nicht gleich sein!<br /> 

Wenn wir dann <code>e</code> und <code>d</code> vergleichen, sagt uns der Compiler: Das sind beides Variablen vom Typ <code>string</code>. Spannend! Die könnten also zur Laufzeit <code>===</code> sein.</p> 

```typescript
e===d
```
<p>Schauen wir uns den gleichen Vergleich von oben mithilfe der Auflösung durch <code>await</code> an, so ist der Compiler im Gegensatz zu oben zufrieden.</p> 

```typescript
const awaitA = await a
const awaitB = await b
const awaitC = await c
await a === await b
await a === await d
````
 <p>Das heißt für mich an dieser Stelle, dass <em>Awaited</em> den Typen abbildet, der nach einem <code>await</code> aufgelöst wird. Klingt irgendwie sinnvoll! Aber wofür braucht man das?</p> <h3>Das Beispiel erklärt</h3> <p>Schauen wir uns doch mal das Beispiel aus der <a href="https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#the-awaited-type-and-promise-improvements">Dokumentation</a>  an. Das hilft sicher weiter.</p> <p>Es wird eingeleitet mit:</p> <blockquote><p>The Awaited type can be helpful for modeling existing APIs, including JavaScript built-ins like Promise.all, Promise.race, etc.</p></blockquote> <p>Es geht also auch darum, 3rd Party Code, bzw. Code, den wir nicht unter Kontrolle haben, besser zu typisieren. Mal im Hinterkopf behalten.</p> <p>Also:<br /> </p> <p>Das Beispiel fängt an mit einer Typdefinition:</p> 

```typescript
declare function MaybePromise<T>(value: T): T | Promise<T> | PromiseLike<T>;
```

<p>Uff! Also wir erklären dem Compiler, dass irgendwo die Funktion namens <code>MaybePromise</code> existiert. Das ist eine generische Funktion, die mit einem Typen <code>T</code> (z. B. string) genauer bestimmt werden kann. Diese Methode nimmt einen Wert dieses Typs <code>T</code> entgegen. Und als Rückgabewert liefert diese Funktion entweder einen Wert des Typs <code>T</code>, ein <code>Promise</code>, das durch den <code>T</code> resolved wird oder ein <code>PromiseLike</code>, das mit einem Wert des Typ <code>T</code> resolved wird.<br /> Puh! Ich habe Fragen!<br /> Zunächst mal: Was ist das für eine seltsame Funktion? Mit noch eigensinnigerem Rückgabewert! So etwas ist mir noch nie begegnet.<br /> Ich werde später sehen: Oh doch! 🙂<br /> Und was ist ein <code>PromiseLike</code>? Das ist nur am Rande wichtig für unser Beispiel. Also nur soviel: Ein <code>PromiseLike</code> ist eine Datenstruktur, welche eine <code>then</code>-Funktion besitzt. Es ist ein Überbleibsel aus den <code>Promise</code>-Anfangstagen. Als es verschiedene, ähnliche Promise-Implementierungen gab, wie z. B. <a href="https://github.com/kriskowal/q">Q</a> .</p> <p>Also wir haben eine Funktion, die entweder einen konkreten Wert oder ein Promise dieses konkreten Werts liefert. Gut!</p> <p>Weiter im Beispiel:</p>

```typescript
async function doSomething(): Promise<[number, number]> {
 const result = await Promise.all([MaybePromise(100), MaybePromise(200)]);
 return result;
}
```

 <p>Wir definieren eine asynchrone Funktion, die ein <code>Promise</code> liefert, welches ein <code>number</code>-Array enthält. Gut, async/await Methoden liefern ihre Werte immer gewrapped in einem <code>Promise</code>. So weit, so gut.<br /> Die erste Zeile lässt klar werden, warum wir es hier mit einem <code>number</code>-Array zu tun haben:<br /> Wir verwenden hier ein <code>Promise.all</code>. Wir erinnern uns:<br /> Ein <code>Promise.all() </code>liefert ein <code>Promise</code> mit einem Array mit allen Werten oder ein rejectetes <code>Promise</code>, falls ein <code>Promise</code> rejected.<br /> Wir verwenden das <code>Promise.all</code> allerdings nicht mit „normalen” Promises, sondern mit unserer Funktion von oben: <code>MaybePromise() </code>mit dem <code>number</code> Typ.<br /> „Normalerweise” würden wir <code>Promise.all()</code> in der Art</p> 

```typescript
const result = await Promise.all([Promise.resolve(10), Promise.resolve(20)]);
```

<p>aufrufen.<br /> Das Ergebnis wäre dann ein <code>Promise</code> mit den Array <code>[10,20]</code>. Hier ist der Eintrag in unserem Array irgendein noch nicht definierter Wert: Entweder eine <code>number</code>, ein <code>Promise</code> mit dieser <code>number</code> oder ein <code>PromiseLike</code> mit dieser <code>number</code>.</p> <p>Als letztes geben wir unseren Wert einfach zurück. Das sieht doch gut aus! Das sollte doch kompilieren!<br /> Also hätte ich jetzt gesagt. Und damit hatte ich auch fast Recht…</p> <h3>TypeScript 4.4 vs. 4.5</h3> <p>Aber schauen wir mal genauer drauf.<br /> Wenn wir das eingangs erwähnte Beispiel mit TypeScript 4.5 ausprobieren, klappt der einfach! Super!<br /> Mit <em>TypeScript 4.4</em> sehen wir hier allerdings einen Compilefehler:</p> 

```typescript
// Error!
//
//    [number | Promise<100>, number | Promise<200>]
//
// is not assignable to type
//
//    [number, number] 
```

<p>Und siehe da! Der Compiler teilt uns mit, dass er sich nicht ganz sicher ist, von welchem Typ das Ergebnis sein wird, bzw. welchen Typ ein Element unseres Arrays haben wird:<br /> <code>number</code> oder <code>Promise</code>.<br /> Wir als alte async/await-Hasen sagen sofort: „Ja komm: <code>await Promise<number></code> ist doch ne <code>number</code>.”<br /> Stimmt! Und genau dafür ist der <strong>Awaited Type</strong>!</p> <p>Aber Moment! Ich sehe hier keinen <em>Awaited</em> Typ! Da bin ich anfangs auch drüber gestolpert.<br /> Die schlauen TypeScript-Entwickler haben in TypeScript 4.4 und TypeScript 4.5 die Signatur von unter anderem <code>Promise.all</code> geändert.<br /> Schauen wir mal rein:</p> <h4>TypeScript 4.4</h4> <p>In TypeScript 4.4 ist die Signatur von <code>Promise.all()</code>:</p> 

```typescript
all<T1, T2>(values: readonly [T1 | PromiseLike<T1>, T2 | PromiseLike<T2>]): Promise<[T1, T2]>;
```

<p>Sieht doch erstmal gut aus: Fast! Und ah! Da sehen wir auch wieder unser <code>PromiseLike</code> wieder! Aber schauen wir uns mal den Return Typ an:<br /> <code>Promise<[T1, T2]></code><br /> Es kommt ein <code>Promise</code> mit einem Array von Werten zurück. Super!<br /> Das sind allerdings generische Werte. „Normalerweise” ein <code>string</code> oder ein <code>Object</code>.<br /> In unserem Beispiel allerdings ist unser <code>T1</code> und unser <code>T2</code> dieser Weiß-ich-nicht-Typ: Könnte eine <code>number</code> sein, vielleicht aber auch ein <code>Promise</code>.<br /> Und genau das bildet das Typsystem in TypeScript 4.4 hier noch nicht ab. Also der Compilefehler!</p> <p>Wie wurde das jetzt gelöst?<br /> Schauen wir rein:</p> <h4>TypeScript 4.5</h4> 

```typescript
all<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>[]>;
```

<p>Hier ist der Return-Wert ein <code>Promise<Awaited<T>[]></code>.<br /> Also fast so wie oben, nur, dass wir mit <em>Awaited</em> ausdrücken, dass wir auf jeden Fall hier ein aufgelöstes <code>Promise</code> haben werden! (Falls ein <code>Promise</code> rejected ist das ganze <code>Promise</code> rejected).<br /> Und schon klappt das! Elegant!</p> <h2>Fazit</h2> <p>Puh! Also der <strong>Awaited Type</strong> kann also Promises entschachteln.<br /> Wofür brauche ich das jetzt?<br /> Für mich bedeutet <em>Awaited</em>, dass die Arbeit mit externen Abhängigkeiten, wie z. B. sogar auch der JavaScript Runtime, in Grenzbereichen angenehmer wird. Der Compiler verhält sich mehr wie ich es erwarte. Die Funktionalität ist hilfreich, wenn ich mit Bibliotheken arbeite, die ich nicht unter Kontrolle habe, aber eigentlich ist dies etwas, das die Lib schon gemacht haben sollte.<br /> Letztendlich war die Motivation für diesen Typ ja auch genau das Auftreten dieser Schwierigkeiten mit <code>Promise.all()</code>.<br /> Wo wende ich selbst diesen Typ an? Ich glaube momentan: Gar nicht! Wenn ich selbst eine Bibliothek bereitstelle, dann ist das hilfreich, um das Konsumieren einfacher zu machen. Oder aber wenn ich im Code aus Gründen mit verschachtelten Promises zu tun habe.</p> <p>Also nehme ich einfach mit: Die Arbeit mit Promises in TypeScript ist noch ein Stückchen angenehmer geworden, ohne dass ich das vielleicht direkt sehe. Und das finde ich super!</p> <p>Habt ihr Ideen, für was ihr den <strong>Awaited Type </strong> einsetzen wollt? Wart ihr genauso gehyped wie ich? Habt ihr ähnlich wie ich an dem Beispiel geknabbert? Schreibt mir doch einen Kommentar!</p> 

TypeScript 4.5 und der Awaited Type

<p>React.js is a JavaScript library which is getting increasing attention at <a href="https://blog.codecentric.de/en/2015/07/react-europe-current-state-react-js/">conferences</a> , on social media and not least among codecentric developers. I heard about this library some time ago, but I used to treat it as a niche topic and just another JavaScript thingy. But I think now is the perfect time to dive deeper into React.js.<br /> <span><br /> For me the most interesting question is: What are the circumstances in which my project needs the help of React.js? For me this question comprises the following:</span></p><ul><li>What is the problem React.js helps me solve?</li><li>How mature is this library?</li><li>How large is the community?</li><li>How useful is the available documentation?</li><li>Does React.js guide me to maintainable and testable code?</li><li>How easy is it to integrate it in existing applications and how well can I integrate third party artefacts?</li><li>What tools can I use for my daily work with React.js?</li></ul><p>At the end of this article I hope that you’ll get a better understanding of what React.js really is about and when it is appropriate for you to apply to your project.</p><p>To make things a little more approachable, I have built a little example application with which I’d like to explain some of the concepts.<br /> This application can be found here: <a href="http://soccerreact.herokuapp.com/">http://soccerreact.herokuapp.com/</a>  and the sources can be found at GitHub: <a href="https://github.com/holgergp/soccerReact">https://github.com/holgergp/soccerReact</a> </p><p>With the application you can manage a soccer league table, which perhaps reminds you of a well known German soccer magazine:<br /> <a href="https://media.graphassets.com/9kb2NXrjSmORMEL4Z7sb"><img width="250" height="330" src="https://media.graphassets.com/9kb2NXrjSmORMEL4Z7sb" alt="screenshotSoccerReact" /></a> </p><p>You can drag and drop teams around, edit your team names (useful at the beginning of a new season) and the table shows if the teams perhaps qualify for some international tournaments, or are in trouble qualifying for the next season.<br /> We don’t look at persistence within this article, I think this would be too much for this kind of read. But we do store our data locally in the browser’s local storage, which we will see later.<br /> But let’s dive right in.</p><h2>How mature is React.js?</h2><p><a href="https://facebook.github.io/react/">React.js</a>  was brought to life in 2013 by Facebook (applying a BSD license). The library is actually in use at Facebook, but other big players are using it as well. Given this, we can assume some kind of production readiness. But only looking at the backing of a large company might be misleading as the vague strategy moving from AngularJS 1.x to AngularJS 2.x showed recently.</p><h2>Which problem does React.js help me solve?</h2><p>Similar to AngularJS, React.js can be described as a client side JavaScript library.<br /> But this comparison does not tell the whole story: AngularJS helps implement a MVC-structured application (whether this is a good thing or not won’t be discussed here ;)) React.js “only” supports you with the “V” (view)-part of your application.<br /> But you can enhance your React.js application using the so called FLUX architecture: This architectural style describes how “components” communicate (solely) unidirectional with “actions” and “stores”. But we won’t tackle any more details of FLUX here, as it would go beyond the scope of this article.</p><p>But where are the difference in the view-layer that React.js introduces?<br /> One of the main design goals of the React.js developers was to avoid having multiple places in an application where you alter state. Two-way databinding is seen as an example of that. In a large application it might be difficult to spot the origin of state mutation.<br /> A React.js-based application forces you to only have a single point of state storage and mutation (or at least very few points). You are then able to process the content of this state in an immutable manner, wherever your application sees fit.<br /> React.js is said to be doing things fast, especially in comparison to AngularJS, and doing well processing large datasets. That is because all state mutations are handled by a “virtual” DOM implementation. “Virtual DOM” means changes are not propagated to the underlying DOM directly. The difference of two state-changes is detected efficiently and only the result of this diff is sent to the DOM. But as a developer you won’t touch those details.</p><p>Furthermore React.js applications are solely composed from “components”. The React.js term component refers to application parts that are independent. To get there React.js applies a hierarchical approach. Within that hierarchy our state is often is located at the root of this component tree. Thus it is advisable to first structure your application on paper before you start hacking. On paper you identify functional areas (components) and dataflow. We will see later on in our example application how this can work.</p><p>Another thing that might catch your eye is JSX. <a href="https://facebook.github.io/react/docs/jsx-in-depth.html">JSX</a>  is an extension of JavaScript that allows using markup as a first-level citizen within your scripts. So it’s quite easy for you to define components and refer to them. This may look like this:</p><div>

```javascript
render: function () {
    return (
      <div>
        <SampleComponent myProperty={this.state.myProperty}/>
        <SampleForm onConcertSubmit={this.handleConcertSubmit}/>
      </div>
    );
  }
```

</div><p>You can use plain JavaScript, but the syntax lacks elegance in comparison:</p><div>

```javascript
React.createElement(
       "div",
       null,
       React.createElement(SampleComponent, { myProperty: this.state.myProperty }),
       React.createElement(SampleForm, { onConcertSubmit: this.handleConcertSubmit })
);
```

</div><p>But it works just as fine. The downside of the JSX approach is that you need a transpiler.</p><h2>What about community and documentation?</h2><p>The community is getting larger every hour, or at least it feels so. To get a feel, here are some numbers in comparison:</p><table><tbody><tr><th></th><th>React.js</th><th>AngularJS</th><th>Knockout.js</th></tr><tr><td>Questions on stackoverflow.com</td><td>6783</td><td>131663</td><td>14840</td></tr><tr><td>Github stars</td><td>30681</td><td>43967</td><td>6900</td></tr><tr><td>Google hits</td><td>695.000</td><td>12.600.000</td><td>558.000</td></tr></tbody></table><p>I’d conclude two things from these numbers:</p><ul><li>AngularJS is still mainstream today</li><li>React.js is already relevant today</li></ul><p>I think the <a href="https://facebook.github.io/react/docs/getting-started.html">documentation</a>  part of React.js is quite good, especially in comparison to other frameworks and libraries. It provides good starting points but goes into depth where needed. Thumbs up!<br /> However, the quality of the AngularJS docs, especially when looking at topics dealing with testing, is not yet there.</p><h2>The sample application</h2><p>Now I’d like to shift our focus to the sample application:<br /> Scaffolding for our application is nicely done with a Yeoman-Generator (<a href="https://github.com/newtriks/generator-react-webpack">https://github.com/newtriks/generator-react-webpack</a> ).<br /> First thing to do is to break down the app in its components. The result is a rather simple, but helpful structure, as you can see in the picture:<br /> <a href="https://media.graphassets.com/g4J2FqQbQ9qqLdhpCLMU"><img loading="lazy" width="250" height="398" src="https://media.graphassets.com/g4J2FqQbQ9qqLdhpCLMU" alt="componentModel" /></a> <br /> This structure is directly reflected in code:<br /> Looking at <em>src/components</em>, you’ll find these artefacts:</p><ul><li><em>App.js</em></li><li><em>LeagueTable.js</em></li><li><em>Position.js</em></li><li><em>Team.js</em></li></ul><p>that have a direct reference to the picture. Additionally there’s <em>run.js</em>, which starts the application and one artefact for constants.</p><p>We are managing the state of our application in one place (as outlined above). That one place is the LeagueTable. The most eye-catching function of a react-component is its <em>render</em>-function. This function is called whenever React.js detects a change and wants to rerender that component reflecting the new state.<br /> In the <a href="https://github.com/holgergp/soccerReact/blob/01_Plain/src/components/LeagueTable.js#L18-L37">LeagueTable</a>  we define the basic template of our HTML structure and some callbacks for our application logic. We will look at the callbacks in a second.<br /> The basic structure looks like this:</p><div>

```javascript
var positionNodes = this.state.positions.map(function (posIter) {
      return (
        <Position position={posIter} key={posIter.position}/>
      );
    });
 
return (
 <div className="col-md-6">
   <div className="panel panel-primary">
     <div className="panel-heading">
       <h3 className="panel-title">Ligatabelle</h3>
     </div>
     <div className="panel-body">
       {positionNodes}
     </div>
   </div>
 </div>
);
```

</div><p>Looks familiar, doesn’t it? But it may be a little odd that we mix markup and JavaScript. I grew to like it quite fast though. 🙂<br /> Two things are interesting at this stage:<br /> First we are building a – tag, which refers to the positions component (which we imported in <a href="https://github.com/holgergp/soccerReact/blob/01_Plain/src/components/LeagueTable.js#L2">the file above</a> ).<br /> Second we see here that we are working on the <em>.state</em> property of the component (as opposed to the components further down the tree).<br /> The following components are much simpler in their core.<br /> Taking a glimpse at the <a href="https://github.com/holgergp/soccerReact/blob/01_Plain/src/components/Position.js">positions</a> -component and its <em>render</em>-function, we see this:</p><div>

```javascript
render: function () {
    const position = this.props.position;
    const team = this.props.position.team;
    return (
      <div>
        <span>
         <Team team={team} positionNumber={position.position} />
      </span>
      </div>
    );
  }
```

</div><p>We do not access the state of our application here (and in the child components), but we use the <em>.props</em>-property. Those are immutable properties. Thus we only have one place where we manage our state. The <a href="https://github.com/holgergp/soccerReact/blob/01_Plain/src/components/Team.js">team</a>  looks similar in its static structure.<br /> But let’s take a look at the application logic:</p><p>The first thing I tackled was <strong>DragAndDrop</strong>: Here the distinction between team and position is starting to make sense. The positions remain static, only the mapping between a team and a position changes while dragging and dropping.<br /> To implement DragAndDrop I used <a href="https://github.com/gaearon/react-dnd">react-dnd</a> . I won’t go into the details of DragAndDrop here. Only this much: The positions form the DropTarget and the DragSource are the teams.<br /> Interesting here is: At the <a href="https://github.com/holgergp/soccerReact/blob/04_WithDragAndDrop/src/components/Team.js#L18-L30">end of a drag</a>  we call a callback, which we have <a href="https://github.com/holgergp/soccerReact/blob/04_WithDragAndDrop/src/components/LeagueTable.js#L78-L108">defined</a>  in the LeagueTable and have passed down (as a prop). This callback then is the central point where we resort our table.</p><p>The second point I implemented was <strong>editing</strong> of the teams names. I used <a href="https://github.com/bmcmahen/react-wysiwyg">react-wysiwyg</a>  to implement this. This is a simple wrapped around HTML5-Content-Editable.<br /> The pattern here looks similar. In the Team-component we define the <a href="https://github.com/holgergp/soccerReact/blob/03_WithEditing/src/components/Team.js#L47-L57">markup</a> .</p><div>

```javascript
<ContentEditable
 tagName='div'
 onChange={onChange}
 className='textPointer'
 html={team.name}
 autofocus={true}
 maxLength={200}
 editing={this.props.team.editing}
 preventStyling
 noLinebreaks
 />
```

</div><p>The callback is again defined in the <a href="https://github.com/holgergp/soccerReact/blob/03_WithEditing/src/components/LeagueTable.js#L68-L89">LeagueTable</a> .</p><p>The third interesting thing is <strong>LocalStorage</strong>. The <a href="https://github.com/holgergp/soccerReact/blob/02_WithLocalStorage/src/components/LeagueTable.js#L10-L26">LeagueTable</a> -component is responsible for this as well. We use additional functions of a react-component:<br /> <em>getInitialState</em> and <em>componentDidUpdate</em>.</p><p><em>getInitialState</em> defines the starting state of a component. Here I check if LocalStorage is present in the browser and if matching data is present in the LocalStorage.<br /> Then I load those stored values or I load some predefined defaults.<br /> <em>componentDidUpdate</em> is called whenever components did change. Here I store the current state to the LocalStorage.</p><p>To better track the different stages of the sourcecode, I supplied different git branches for every implementation step. Starting with a version <a href="https://github.com/holgergp/soccerReact/tree/01_Plain">without dynamics</a>  and ending with the full version containing <a href="https://github.com/holgergp/soccerReact/tree/04_WithDragAndDrop">DragAndDrop</a> .</p><h2>How maintainable is the resulting code and what about (unit) tests?</h2><p>To test the application I used <a href="http://jasmine.github.io/">Jasmine</a>  and I have written some sample unit tests for the <a href="https://github.com/holgergp/soccerReact/blob/04_WithDragAndDrop/test/components/MainTest.js">LeagueTable</a> -component. I did not notice that many peculiarities. Test arrangement is a bit uncommon, the concept of virtual rendering may confuse a little bit. But you get good support by React-Utilities. So to answer the question: Can you unit test React.js applications? Yes!</p><p>Due to the fact that React.js encourages the developer to slice the application in components and to hold state only in few places, the application is designed to be maintainable.<br /> What may be problematic is that the state-holding component (here the LeagueTable) may be a little overloaded with callbacks and logic. Applying the FLUX architecture, you can address this problem quite elegantly.</p><p>What I like during development is the well helpful error messages and logs. JSX may be a little uncommon (“Why another language variant?”), but I think this makes semantics more clear, and I like it.</p><p>It did take me some time to get my head around the React way of thinking, but the decisions are reasonable and I like the result.</p><h2>Integration</h2><p>As shown in the example, it is not that difficult to use third party libs to build more sophisticated functionality in order to tackle more complex requirements. The integration into existing applications is possible as well: As an example you can look at <a href="https://github.com/ngReact/ngReact">ngReact</a> . But this may be evaluated on a per-case basis.</p><h2>Tooling</h2><p>The toolchain that is used here is similar to other JavaScript stacks. The use of a transpiler like Babel might feel a little unfamiliar in some cases. But you can still fall back to plain JavaScript (ES5).<br /> I developed the application using IntelliJ and I was supported quite well. I can recommend it.</p><h2>When does it make sense to add React.js to my stack?</h2><p>React.js might not be suitable in every case where you want to use client-side logic or SPAs.<br /> The investment in the toolchain and in the way of thinking might still be too far away from the mainstream.<br /> But I can think of at least two scenarios where React.js shines:</p><ul><li>If you build self-contained widgets (such as a LeagueTable)</li><li>If the application has to handle and view large datasets and performance is your concern</li></ul><p>Further on it is advisable to look at <a href="https://facebook.github.io/react/docs/flux-overview.html">FLUX</a>  in this context, to build larger applications using React.js.<br /> Have fun playing around with React.js!</p>

Road testing React.js

<p><span>Heute möchte ich mich auf dem codecentric Blog einem Thema widmen, welches hier seltener bearbeitet wird: dem Thema User Experience (oder kurz UX). Dabei ist UX in aller Munde. Im letzten Jahr habe ich auf einer Konferenz einen Vortrag zum Thema „Die moderne Rolle des CFO“ gehört und gelernt, dass eine der Top-Prioritäten für den Finanzchef von heute eine gute User Experience ist. Was auch immer das konkret bedeuten mag… </span><span><br /> </span><span>Das Thema ist demnach längst im Mainstream angekommen. Also alles super, und alle UXler können sich getrost zur Ruhe setzen? Ihr Job ist ja schließlich getan, oder?</span><span><br /> </span><span>Der Projektalltag sieht jedoch häufig ganz anders aus. Da ist UX  leider oft die Streichmasse: „Das muss in der ersten Version noch nicht schön sein“ oder „Das machen wir später hübsch“ hallt es da durch den Flur. Was dabei übersehen wird, ist, dass User Experience und Usability eben nicht gleich „hübsch“ sind. Und viele Dinge macht man besser von Anfang an richtig, da es später umso schwieriger ist. Es sagt ja (hoffentlich) heute auch kein Entwickler mehr: „Ich überlege mir später mal, wie wir das testen können. Tests sind erstmal nicht so wichtig“.</span><span><br /> </span><span><br /> </span><span>Gerne wird dann auch mit dem 80:20-Prinzip argumentiert. „Bis hierhin ist es gut genug, mehr wäre nicht wirtschaftlich“. Ab jetzt steigt der Aufwand schließlich exponentiell, das weiß ja schließlich jeder.  Hört man oft. Leider habe ich schon zu oft erlebt, wie diese Regel von Entwicklern oder Product Ownern (PO) missbraucht wurde, um eine vermeintliche Abkürzung zu nehmen.</span></p><p><span>Es stellt sich also die Frage, wie man den steigenden Anforderungen an eine moderne User Experience gerecht werden kann – insbesondere in kleineren Teams, wenn kein eigenes Budget für UX zur Verfügung steht.</span></p><p><span>Ich werde in dieser Artikelreihe interessierten Entwicklern und Product Ownern einen Einblick in die Welt der User Experience und Usability geben. </span></p><p><span>Oft scheitert die Umsetzung in der Praxis daran, dass jeder ein eigenes Verständnis dieser Thematik hat. Daher werde ich zunächst einige Begriffe erklären, die immer wieder in Diskussionen auftauchen (Part 1). Im zweiten Teil werde ich beschreiben, was Mentale Modelle sind und warum sie bei der Software Entwicklung eine so bedeutende Rolle spielen.</span></p><p><span>Im dritten Teil meiner Usability-Reihe zeige ich, wie Usability Tests auch in kleinen Teams mit knappen Ressourcen durchgeführt werden können</span></p><p><span>Usability und User Experience werden oft synonym verwendet und leider ebenso häufig auf ästhetische Aspekte reduziert. Dabei geht es um viel mehr als um Pixelschubserei und bunte Bilder.</span></p><p><span>Nach </span><a href="https://www.academia.edu/2880396/The_hedonic_pragmatic_model_of_user_experience" target="_blank"><span>Hassenzahl</span></a> <span> nehmen Benutzer interaktive Systeme anhand zweier Dimensionen wahr: der pragmatischen Dimension und der hedonischen Dimension.</span></p><h2><span>Pragmatische Bewertung</span></h2><p><span>Die Bewertung einer Benutzerschnittstelle aus pragmatischer Sicht fokussiert darauf, wie gut ich als Anwender in der Erfüllung meiner Aufgaben unterstützt werde.</span></p><p><span>Bewertungskriterien, die sich daraus ergeben, könnten sein:</span></p><ul><li><span>Ist die Anwendung verfügbar wenn ich sie benötige? Bin ich vor Datenverlust geschützt? (</span><b>Zuverlässigkeit</b><span>)</span></li><li><span>Erschließt sich mir das Verhalten der Anwendung (</span><b>Verständlichkeit</b><span> / </span><b>Erwartungskonformität</b><span> – diesen Aspekt werde ich im 2. Teil der Artikelreihe zum mentalen Modell wieder aufgreifen)?</span></li><li><span>Werde ich bei der Erledigung meiner Aufgaben gut unterstützt? Werden mir unnötige Aufgaben abgenommen? (</span><b>Effizienz</b><span>)</span></li></ul><h2><span>Hedonische Bewertung</span></h2><p><span>Aus hedonischer <a href="#footnote"><sup>1</sup></a>  Sicht bewerte ich, wie die Interaktion mit dem System auf mich als Mensch wirkt. Fühle ich mich kompetent? Fühle ich besonders? Macht es mir Spaß mit dem System zu arbeiten? Hier spielen auch Aspekte eine Rolle, die über die Bedienung des Systems hinausgehen, z.B. das gute Gefühl ein Produkt einer besonders angesehenen Marke einzusetzen. </span></p><p><span>Pragmatische Kriterien könnten sein:</span></p><ul><li><span>Empfinde ich das Produkt als schön? (</span><b>Ästhetik</b><span>)</span></li><li><span>Motiviert mich die Arbeit mit dem System? (</span><b>Motivation</b><span>)</span></li><li><span>Macht es Spaß, das Produkt zu nutzen? (</span><b>Spaß</b><span>)</span></li><li><span>Empfinde ich das System als originell, unterstützt es mich in einer kreativen Arbeit? (</span><b>Kreativität</b><span>)</span></li></ul><h2><span>Usability </span></h2><p><span>Die Erfüllung der pragmatischen Kriterien zeigt uns, dass wir das Produkt so benutzen können, wie von uns gewünscht. Die Benutzbarkeit (Usability) ist also gegeben. Interessanterweise haben wir im Deutschen gleich zwei Begriffe, deren englische Übersetzung Usability ist: Benutzbarkeit und Gebrauchstauglichkeit.</span></p><p><span>Die Bewertung der Gebrauchstauglichkeit kann dabei nur im Zusammenhang mit dem jeweiligen Nutzungskontext erfolgen: Einsatzumgebung, Soft- oder Hardware, soziales Umfeld…</span></p><p><span>Ich fasse hier beide Begriffe unter dem englischen Begriff Usability zusammen.</span></p><h2><span>Joy of Use</span></h2><p><span>Die hedonischen Kriterien befassen sich mit emotionalen Aspekten, die oft als “Joy of Use” zusammengefasst werden.</span></p><h2><span>User Experience</span></h2><p><span>Eine gute User Experience ist für mich die Verbindung der pragmatischen und hedonischen Kriterien: Usability und Joy of Use vereint in einem Produkt.</span></p><p><span>Mir ist an dieser Stelle aber auch die Gewichtung dieser Kriterien wichtig. Gerade wenn wir Benutzerschnittstellen gestalten, die im Geschäftsumfeld eingesetzt werden, ist die Usability die Grundlage. Solange diese Grundlagen nicht stimmen, sollten wir auch keine Zeit investieren den Joy of Use unserer Anwendung zu verbessern. Im Gegenteil: Eine Investition in den Joy of Use unseres Interfaces bei einer Software, die nicht zuverlässig funktioniert, würde uns von unseren Anwendern sogar negativ ausgelegt werden.</span></p><p><a href="https://media.graphassets.com/3rHu3iykQSrlNInBBx8Q"><img loading="lazy" src="https://media.graphassets.com/3rHu3iykQSrlNInBBx8Q" alt="User Experience: criteria grouped by usability vs joy of use" width="700" height="485" /></a> </p><p><span>Gerade im Bereich Joy of Use ist zudem längst nicht immer jeder Punkt erstrebenswert. Eine Anwendung im medizinischen Sektor sollte meist explizit nicht originell sein. Diese Gewichtung muss also projektindividuell getroffen werden.</span></p><p><span>In diesem ersten Artikel haben wir einige grundsätzliche Anforderungen geklärt. Unser erstes Ziel bei der Gestaltung von Benutzeroberflächen für Business Software ist also eine einfache und verständliche Bedienung. Dazu müssen wir aber verstehen wie unsere Anwender denken. Das Verständnis von mentalen Modellen ist dazu ein unabdingbares Hilfsmittel. <a href="https://blog.codecentric.de/2017/07/user-experience-und-mentale-modelle/">Diesem Thema werden wir uns im zweiten Teil dieser Artikelserie widmen</a> .</span></p><h4>Fußnoten</h4><p>1. Hedonisch leitet sich aus dem griechischen Wort “hēdonḗ” für Lust ab</p>

User Experience – was habe ich damit zu tun?

<p><span>Nachdem wir im letzten Teil dieser Artikelserie zum Thema <a href="https://blog.codecentric.de/2017/07/user-experience-basics/">User Experience</a>  über <a href="https://blog.codecentric.de/2017/07/user-experience-und-mentale-modelle/">mentale Modelle</a>  gesprochen haben, sind diesmal Usability Tests das Thema. Zu Zeiten meines Studiums war die Durchführung von Usability Tests noch mit einem enormen Aufwand verbunden. Die allgemeine Vorstellung ihrer Durchführung war dadurch lange geprägt von kostspieligen Usability-Labs, in der die Probanden, wie in einer amerikanischen Krimiserie, durch eine einseitig durchsichtige Spiegelwand beobachtet wurden. Dazu teure Eyetracking-Vorrichtungen und natürlich eine große Anzahl an Testpersonen. Wir wollen ja schließlich relevante Ergebnisse…</span></p><p><span>Für die Einrichtung eines professionellen Testlabors kommen da schnell einige 10.000 € zusammen. Nicht, dass wir uns falsch verstehen: Wer die Möglichkeiten hat, auf eine solche Umgebung zuzugreifen – sei es als eigenes Labor oder über den Einkauf von Usability-Experten – kann sich glücklich schätzen. Gerade in kleinen und mittelständischen Betrieben wird es aber schwer sein ein Budget für diesen Einsatz zu finden.</span></p><p><span>Fehlendes Budget ist allerdings längst keine Entschuldigung mehr, keine Usability Tests durchzuführen. Ihre neu gewonnene Popularität verdanken sie wohl Jakob Nielsen oder Steve Krug mit seinem tollen Buch  “Don’t make me think”. Letzterer beschreibt eine sehr pragmatische Herangehensweise an Usability Tests, wie sie eigentlich in jeder Firma durchführbar sind. </span></p><p><span>Usability Tests sollten also in jedem Projekt zum Standard-Repertoire gehören. Und ich kann mich in meiner Laufbahn an nicht einen einzigen Test erinnern, der nicht hilfreich gewesen wäre. </span></p><p><span>Usability Tests erfüllen mich oft mit einer seltsamen Mischung aus Scham und Befriedigung: Scham, wenn man – als verantwortlicher Product Owner oder Entwickler – sieht wie der Anwender an Dingen scheitert, die man einfach nicht bedacht hat. Befriedigung, wenn man wertvolle Dinge gelernt hat und wenn Designs und Designanpassungen so funktionieren wie gewollt.</span></p><p><span>Was ist zu tun, wenn ich mit meinem Team anfangen möchte in die Welt der Usability Tests einzusteigen?</span></p><h2><span>Wann testet man?</span></h2><p><span>Eine der ersten Fragen die sich im Zusammenhang mit Usability Tests stellt, ist die Frage, wann der geeignet Zeitpunkt für Tests ist. Diese Frage lässt sich erstaunlich einfach beantworten: So früh wie möglich. Und das bedeutet wirklich früh: Schon bevor wir die erste Version der Software freigeben. </span></p><p><span>Ganz im Sinne der agilen Softwareentwicklung wollen wir kurze Feedbackzyklen. Aus dieser Sicht macht es keinen Sinn ein Design erst komplett auszuimplementieren, wenn wir es bereits vorher hätten verproben können.</span></p><p><span>Testen wir zu spät, laufen wir Gefahr, dass schlechte Design-Entscheidungen schon so weit zementiert sind, dass sie sich nicht oder nicht vertretbarem Aufwand mehr ändern lassen.</span></p><p><span>Usability Tests sind bereits sehr früh im Projekt möglich, sei es auf Basis von Papier-Prototypen, Klick-Dummies oder schon etwas weitergehende Prototypen. Dabei reicht es, wenn wir zum Zeitpunkt des Tests nur einen ganz bestimmten Pfad abbilden können. Dazu definieren wir Testaufgaben, die ausreichend scharf eingegrenzt sind (dazu später mehr).</span></p><h2><span>Zutaten für einen erfolgreichen Usability Test</span></h2><p><span>Für einen erfolgreichen Usability Test sind einige Dinge dringend erforderlich:</span></p><ol><li><span>Ziele des Tests</span></li><li><span>Schriftliche fixierte Testaufgaben</span></li><li><span>Ein Testmoderator</span></li><li><span>Ein Screensharing Tool </span></li><li><span>Probanden die den Test ausführen</span></li><li><span>Team-Mitglieder die die Testergebnisse protokollieren</span></li><li><span>Eine professionelle Vorbereitung</span></li><li><span>Eine gemeinsames Nachbesprechung</span></li></ol><h3><span>Ziele des Tests</span></h3><p><span>Wichtig bei einem Usability Test ist, dass wir nicht einfach nur einem Probanden einen Entwurf oder eine Software-Version zeigen und allgemein Feedback einholen. Vor dem Test werden die Ziele festgelegt. Beispiele für Ziele könnten sein:</span></p><ul><li><span>Findet der Anwender auf einem Touch-Gerät das Kontextmenü?</span></li><li><span>Kann der Anwender unser Tutorial erfolgreich durcharbeiten?</span></li><li><span>Kommt der Anwender damit zurecht, wenn wir alle Änderungen direkt speichern und keinen Speicher-Knopf mehr anbieten?</span></li></ul><h3><span>Testaufgaben</span></h3><p><span>Basierend auf den Test-Zielen werden nun Aufgaben festgelegt, die ein Proband im Rahmen eines Tests erledigen soll. Vom Umfang her sollten die Aufgaben so geschnitten werden, dass die Dauer eines Tests 30 Minuten nicht überschreitet.</span></p><h3><span>Testmoderator</span></h3><p><span>Die Aufgabe des Moderators ist die Durchführung des Tests. Zu Anfang wird dieser den Probanden willkommen heißen und ihm die Testaufgabe erklären.</span><span><br /> </span><span>Zudem sollte hier bereits klar gemacht werden, dass nicht der Proband getestet wird, sondern die Software. Das Letzte was wir wollen, ist das die Testperson sich schlecht fühlt, weil unser Entwurf nicht funktioniert.</span><span><br /> </span><span>Als Moderator ist es wichtig, die Testperson nicht zu beeinflussen. Gerade wenn man selbst an der Entwicklung beteiligt war, was sich in einem kleinen Team oft nicht vermeiden lässt, kann dies anfangs sehr schwer fallen. Unbewusst verfällt man gerne in Suggestivfragen oder eine Rechtfertigungshaltung. Wenn die eigene Arbeit also nicht so funktioniert, wie man es sich vorher überlegt hat, oder der Entwurf kritisiert wird, muss man das hier einfach ertragen. Denn genau dafür machen wir den Test ja.</span><span><br /> </span><span>Während der Testdurchführung ist die Hauptaufgabe des Moderators, den Probanden dazu zu bringen laut zu denken (think aloud protocol). Wann immer die Testperson an einer Stelle hängt und überlegt, ist für uns interessant, was Sie gerade denkt. Sucht die Testperson nach einem bestimmten Begriff? Ist etwas unklar? Ist vielleicht etwas passiert, was für den Probanden überraschend war?</span><span><br /> </span><span>All das ist von außen nur schwer ersichtlich. Also wollen wir an diesen Denkprozessen beteiligt werden. Hilfreich sind hier Fragen wie “Was überlegst du gerade?”, “Wonach suchst du?” oder wenn etwas scheinbar Unerwartetes passiert: “War das das, was du erwartet hast?”.</span><span><br /> </span><span>Während eines Tests kommt es oft vor, dass Anwender den Moderator um Hilfe bitten, zum Beispiel “Wo kann ich das Dokument den speichern?”. Solche Fragen sollte der Moderator nicht direkt beantworten. In der Realität sind wir ja auch nicht da, um ihm zu helfen. Stattdessen können wir die Frage zurückspiegeln: “Wo würdest du diese Funktion denn erwarten?” und “Was würdest du jetzt tun, wenn ich nicht neben dir sitzen würde?”.</span><span><br /> </span><span>Natürlich kann es aber vorkommen, dass sich ein Anwender durch einen Fehler in unserem Design in eine Sackgasse manövriert. Wenn es erkennbar keinen Fortschritt gibt oder der Anwender deutlich frustriert wirkt, sollten wir natürlich eingreifen.</span></p><h3><span>Screensharing-Tool</span></h3><p><span>Das Screensharing-Tool klingt in der Zutatenliste vielleicht zunächst etwas überraschend. Aber wir wollen den Testverlauf ja verfolgen und dokumentieren. Dies ist die Aufgabe der weiteren Teammitglieder, da der Moderator sich voll auf seine Aufgabe des Moderierens konzentrieren soll.</span></p><p><span>Der Moderator und der Proband sollen den Test ungestört durchführen, auch um nicht künstlichen Druck zu erzeugen.</span></p><p><span>Wenn wir keinen extra Beobachtungsraum mit einem Einweg-Spiegel haben, übernimmt diese Aufgabe die Screensharing Software. Mit ihrer Hilfe übertragen wir den Bildschirminhalt des Testrechners in einen Extraraum, in dem der Rest des Teams die Beobachterrolle einnimmt.</span></p><p><img src="https://media.graphassets.com/6PRweiDcTSKeRDJX0tlN" alt="Das Screensharing Tool teilt den Inhalt des Testrechners mit den Beobachtern" width="284" height="537" /></p><h3>Remote Usability Tests</h3><p><span>Vorteil dieses Vorgehens ist, dass sich auch Moderator und Proband physikalisch an unterschiedlichen Orten befinden können. Dies erleichtert oft die Rekrutierung von Probanden, da nicht noch zusätzliche Aufwände durch eventuell notwendige Anreise entstehen.</span></p><p><img loading="lazy" src="https://media.graphassets.com/CGe2QaaoTmusheps0crc" alt="Moderator und Proband können sich an unterschiedlichen Standorten befinden" width="843" height="530" /></p><h3><span>Probanden</span></h3><p><span>Die Probanden für den Test zu finden, ist oft eine Herausforderung. Idealerweise stehen uns “echte” Anwender für unseren Test zur Verfügung. Wie man diese rekrutieren kann, ist je nach Projekt sehr unterschiedlich. Realisiere ich ein Projekt für einen Kunden, ist es vielleicht einfach Tester aus einer Fachabteilung zu gewinnen. Verkauft man Software an Endkunden, hilft einem vielleicht ein Spezialanbieter.</span></p><p><span>Sollte kein “echter” Testanwender zur Verfügung stehen, ist ein Test nicht gleich unmöglich. In vielen Fällen können Tests auch mit alternativen Personen wie zum Beispiel Kollegen aus einem anderen Projekte oder Bekannten Sinn machen. Dies ist stark davon abhängig, wieviel Fachwissen zur Bedienung der Software notwendig ist und welche Aspekte wir testen wollen.</span></p><p><span>Neben der Frage, wer als Proband in Frage kommt, ist natürlich die Anzahl an Probanden zu klären. Um sinnvolle Testergebnisse zu erzielen, sind weitaus weniger Testteilnehmer notwendig als man erwarten könnte. Folgt man den Empfehlungen von Krug oder </span><a href="https://www.nngroup.com/articles/why-you-only-need-to-test-with-5-users/"><span>Nielson</span></a> <span> sind bereits 3-5 Benutzer ausreichend. Wenn man auf konkrete Projekte schaut, ist diese Anzahl aber schnell verständlich. Wir wollen ja nicht eine ultimative Liste aller Usability Probleme in unserer Software erstellen, sondern nur die schlimmsten identifizieren – und fixen!</span></p><p><span>Mit diesem Anspruch stellt man sehr schnell fest, dass sich auch bei einer geringen Anzahl an Testern die Ergebnisse schnell wiederholen. Fast jede Software hat viele schwerwiegende Usability Probleme, die sie einem förmlich zuruft. Man muss nur hinhören. Und genau das ermöglichen uns die Usability Tests.</span></p><h3><span>Vorbereitung</span></h3><p><span>Ein erfolgreicher Usability Test erfordert eine gründliche Vorbereitung. In dieser Vorbereitungsphase müssen folgende Punkte erledigt werden:</span></p><ul><li><b>Testaufgaben erstellen</b><span>: Die Aufgaben für den Test müssen schriftlich fixiert werden. Wenn der Umfang wie oben beschrieben auf ca. 30 Minuten ausgelegt ist, sollte man pro Testperson mit Einführung und abschließenden Fragen eine volle Stunde einplanen</span></li><li><b>Moderator bestimmen</b><span>: Idealerweise findet man einen Moderator, der nicht direkt an der Umsetzung beteiligt war. Hat die entsprechende Person noch keine Erfahrung mit Usability Tests, empfehlen sich einige Team-interne Proberunden um die Moderatorfähigkeiten zu schärfen.</span></li><li><b>Räume buchen</b><span>: Die Räume müssen gebucht werden. Wir brauchen einen Raum, in dem Moderator und Proband ungestört den Test durchführen können. Ein weiterer Raum wird für das Beobachter Team gebucht.</span></li><li><b>Hardware bereitstellen</b><span>: Im Beobachter-Raum muss ein Rechner samt Beamer für die Übertragung zur Verfügung stehen. Im Test-Raum brauchen wir den Testrechner und ein extra Mikrofon um eine ausreichende Sprachqualität bei der Aufzeichnung und Übertragung zu gewährleisten.</span></li><li><b>Software bereitstellen</b><span>: Neben der zu testenden Software benötigen wir noch die Screensharing-Software für die Übertragung in den Beobachter-Raum und die parallele Aufzeichnung. Zum Glück ist in vielen Unternehmen eine passende Software bereits vorhanden (WebEx, GoTo Meeting, Skype Business, Zoom um nur ein paar Namen zu nennen).</span></li><li><b>Dry Run durchführen</b><span>: Vor jedem Test ist ein Probedurchlauf Pflicht. Insbesondere folgende Punkte sollten dabei geprüft werden:</span><ul><li><span>Kann ich die gewählte Aufgabe mit dem zu testenden Artefakt überhaupt erfüllen?</span></li><li><span>Funktioniert die Übertragung?</span></li><li><span>Ist die Tonqualität ausreichend?</span></li><li><span>Funktioniert die Aufzeichnung?</span></li><li><span>Ist die Bildqualität der Aufzeichnung ausreichend?</span></li></ul></li></ul><p><span>All dies sind Punkte, die vor dem ersten Test geklärt sein müssen. Schließlich opfern die Probanden ihre Zeit für uns und können eine professionelle Durchführung erwarten.</span></p><h3><span>Nachbesprechung</span></h3><p><span>Nach der Durchführung treffen sich die Beobachter und der Moderator, aber nicht die Probande, zum gemeinsamen Debriefing.</span></p><p><span>Ziel dieses Meetings ist die gemeinsame Identifikation der schlimmsten Usability Probleme und die Definition von Maßnahmen. Im Debriefing nennt jeder Beobachter pro Test und Proband die schlimmsten Probleme (maximal eine Handvoll) die er im Test beobachtet hat.</span></p><p><span>Die Chance ist groß, dass bestimmte Probleme von mehreren Beobachtern identifiziert wurden. </span></p>

Usability Tests für jedermann

<p><span><a href="https://blog.codecentric.de/2017/07/user-experience-basics/">Der erste Teil dieser Artikelserie</a>  gab eine kurze Einleitung in das Thema User Experience (UX). Wer sich professionell mit UX befasst, führt viele Diskussionen über User Interface Entwürfe mit Stakeholdern, Entwicklern, Designern und anderen Interessierten. Zu Benutzerschnittstellen hat schließlich jeder eine Meinung. Oft werden diese Diskussionen sehr emotional geführt. Schließlich ist jeder von seiner eigenen Sichtweise überzeugt.</span><span><br /> </span><span>Um diese Diskussionen zu versachlichen, ist es notwendig, unsere Nutzer und ihre Erwartungshaltung besser zu verstehen. Hierbei hilft uns das Verständnis des mentalen Modells oder der mentalen Modelle eines Anwenders im Bezug auf eine Anwendung. </span></p><h2><span>Mentales Modell – was ist das eigentlich?</span></h2><p><span>Wann immer ein Anwender mit einem Produkt interagiert, hat er eine Vorstellung davon, wie dieses Produkt funktionieren wird.</span></p><p><span>In seinem Buch “The Design of Everyday Things” skizziert Don Norman ein Beispiel, welches ich hier aufgreifen möchte, um das mentale Modell zu erklären.</span></p><p><span>Bei einer Präsentation am Computer nutzen viele Sprecher einen sogenannten “Clicker”.</span></p><p><span>Diese kleine Fernbedienung erlaubt es dem Sprecher, sich frei im Raum zu bewegen und dabei die Präsentation fernzusteuern. Er ist also nicht mehr daran gebunden direkt am Computer zu stehen, um diesen zu bedienen.</span></p><p><span>Nehmen wir einmal an, dieser Clicker würde folgendermaßen aussehen:</span></p><p><img loading="lazy" src="https://media.graphassets.com/r0wVp1tVTbWlcn9i5TSa" alt="Bild eines Präsentations-Clickers mit zwei Knöpfen untereinander. Der obere mit einem Pfeil nach oben, der untere mit einem Pfeil nach unten." width="153" height="250" /></p><p><span>Welchen Knopf müsste man drücken, um zur nächsten Folie in der Präsentation zu gelangen?</span></p><p><span>Ich habe dieses Beispiel schon mehrfach in Vorträgen verwendet, und die Verteilung unter den Teilnehmern ist meist grob 60/40. Interessanterweise erhält meist die Option den größeren Zuspruch, die zuerst abgefragt wurde.</span></p><p><span>Offensichtlich ist die Benutzerschnittstelle des Clickers nicht so eindeutig, als dass jeder intuitiv das gleiche Verständnis zur Funktionsweise hätte. Jeder Anwender wählt aber intuitiv einen bestimmten Knopf, und für jeden Einzelnen ist die Wahl auch sehr eindeutig.</span></p><p><span>Offensichtlich haben die unterschiedlichen Anwender unterschiedliche mentale Modelle davon, wie der Clicker funktionieren könnte. </span></p><h2><span>Modell 1 “Bewegliche Kamera”</span></h2><p><span>Das erste Modell ist das der „Beweglichen Kamera“: Wir schauen durch eine Kamera auf die Folien, die alle untereinander an einer virtuellen Wand hängen. Durch Betätigung des Clickers bewegen wir die Kamera. Um also zur nächsten Folie zu gelangen, muss ich als Betrachter die Kamera nach unten bewegen. Ich drücke also den unteren Knopf.</span></p><p><a href="https://media.graphassets.com/eHI8gBHASiGpZLTEAhum"><img loading="lazy" src="https://media.graphassets.com/eHI8gBHASiGpZLTEAhum" alt width="800" height="450" /></a> </p><p> </p><h2><span>Modell 2 “Endlospapier”</span></h2><p><span>Beim zweiten Modell “Endlospapier” ist unsere Kamera nicht mehr beweglich, sondern steht starr an einer Stelle. Dafür hängen alle Folien aneinander – die älteren unter uns erinnern sich vielleicht noch an Drucker-Endlospapier. In diesem Modell ziehen wir die Folien quasi an der Kamera vorbei. Um zur nächsten Folie zu gelangen, drücke ich also den oberen Knopf. Damit ziehe ich den Satz Folien nach oben, um so die nächste Folie vor der virtuellen Kamera zu positionieren.</span></p><p><a href="https://media.graphassets.com/Ep8ACjwRTkytsmaLacYv"><img loading="lazy" src="https://media.graphassets.com/Ep8ACjwRTkytsmaLacYv" alt width="800" height="450" /></a> </p><p><span>Beide Modelle begegnen uns übrigens auch, wenn wir mit Desktop PCs und Touchgeräten arbeiten: Das Modell der beweglichen Kamera passt genau auf die Interaktion mit dem Rollbalken eines Fensters. Wenn wir zur nächsten Seite in einem Dokument wollen, bewegen wir den Rollbalken nach unten. Verwenden wir stattdessen ein Gerät mit Touchbedienung, schieben wir die Seite mit dem Finger nach oben, damit weitere Seiten sichtbar werden.</span></p><p><span>Das Entscheidende aber ist: Keines der Modelle ist besser oder schlechter als das andere. Es gibt kein richtiges und kein falsches mentales Modell. Das Modell ist einfach da und bei verschiedenen Anwendern unterschiedlich.</span></p><p><span>Ich finde dieses Beispiel unglaublich hilfreich, weil es zeigt, dass man im UX-Design von einer Lösung absolut überzeugt sein kann, der Anwender im Zweifelsfall aber trotzdem eine andere Sicht hat.</span></p><p><span>Unser Ziel ist es also, das mentale Modell unserer Anwender zu verstehen, wenn sie mit unserer Anwendung interagieren. Oder besser gesagt: die verschiedenen mentalen Modelle. Denn wie das obige Beispiel zeigt, gibt es nicht das eine gültige Modell – sondern viele, teilweise widersprüchliche Modelle. Nutzer eines Clickers können davon ein Lied singen, wenn sie mit einem “fremden” Clicker arbeiten, dessen Tasten genau anders belegt sind, als sie es erwarten.</span></p><p><span>Nach Möglichkeit sollten wir versuchen, unsere Benutzeroberfläche so zu gestalten, dass ihr Bedienkonzept dem mentalen Modell möglichst vieler Nutzer entspricht. </span></p><p><span>Im obigen Beispiel könnte man versuchen die Interaktion zu verbessern, indem man die beiden Knöpfe statt untereinander nebeneinander anordnet:</span></p><p> </p><p><img loading="lazy" src="https://media.graphassets.com/wFmXoolT7aJeL3kepbyh" alt width="72" height="124" /></p><p> </p><p> </p><p><span>In dieser Anordnung gibt es eine größere Mehrheit dafür, dass der rechte Knopf weiter blättert und der linke zurück. Vermutlich weil wir dieser Form der Interaktion häufig am Computer begegnen zum Beispiel in Wizards und bei Bildergalerien.</span></p><p><span>Um zu lernen, welches mentale Modell sich die Benutzer von unserer Anwendung machen, gibt es verschiedene Methoden. </span></p><p><span>Die aus meiner Sicht wichtigste Methode ist die Beobachtung von Anwendern und die Durchführung von Usability Tests, aber dazu mehr in einem folgenden Artikel.</span></p>

Mentale Modelle – Anwender besser verstehen

<p><strong>Angenommen</strong> ich möchte einen Alexa Skill entwickeln<br /> <strong>Wenn</strong> ich die Dialoge mit Alexa vorab als ausführbare Akzeptanztests ablegen könnte<br /> <strong>Dann</strong> wäre ein großer Schritt zu hochwertigen Skills getan</p><h2>Behavior-Driven Alexa Skill Development mit cucumber.js</h2><h3>Motiviation</h3><p>Eigentlich hatte ich diesen Blog-Artikel gar nicht geplant. Mich interessierte die Nutzerinteraktion von Anwendern mit Voice-UIs und ich wollte mich diesem Thema mit einem einfachen Alexa Skill nähern. Nun habe ich an vielen Stellen gelesen, wie einfach es doch ist, einen eigenen Skill zu schreiben. Allerdings sind mir die ersten Schritte dann leider doch recht schwer gefallen, also habe ich beschlossen meine Erfahrungen damit in einem Blog-Artikel zusammen zu fassen.</p><p>Schritt für Schritt kam dann der Wunsch nach Tests auf. Eigentlich wollte ich ja nur was ausprobieren und auf Tests komplett verzichten. Warum sich das für mich nicht bewährt hat erkläre ich im weiteren Verlauf.</p><p>Im ersten Teil dieser Blogserie beschreibe ich das initiale Skill-Setup.</p><h2>Die initialen Anforderungen</h2><ul><li>Meine initialen Anforderungen an die Skill-Entwicklung waren:<br /> Es sollte über ein einfaches “Hello World”-Beispiel hinausgehen. Für mich hält sich der Lerneffekt bei extrem vereinfachten Beispielen doch sehr in Grenzen. Das Thema ist nunmal komplex und diese Komplexität wollte ich erfahren und nicht ausblenden. Also habe ich mir als Thema einen Skill vorgenommen, der das lästige Punktenotieren bei einem Würfelspiel übernimmt.</li><li>Also erwartete ich auch mehr als nur ein paar Zeilen Code. Diesen wollte ich in einem Git Repository sichern.</li><li>Auf Programmierebene wollte ich möglichst viel Vertrautes einsetzen, einfach damit ich das Maximale über Skill-Entwicklung lerne. Das hieß für mich: modernen JavaScript-Code schreiben – inkl. Features wie async / await oder einfache imports.</li></ul><h2>Setup des Skills</h2><p>Ich habe mir das erstbeste Tutorial geschnappt um einfach mal loszulegen. Diesen Teil werde ich hier recht knapp halten. Dafür gibt es bereits gute Anleitungen im Netz (u.a. <a href="https://blog.codecentric.de/webseiten-mit-alexa-und-websockets-navigieren" target="_blank">auch hier im codecentric Blog</a> ). Da sich das Vorgehen aber leicht geändert hat, gebe ich zumindest einen kurzen Überblick.</p><p>Für die Skill-Entwicklung müssen wir mindestens zwei Artefakte erstellen:</p><ul><li>Das erste ist das Voice Interaction Model. In diesem Modell definieren wir, welche Befehle (Intents) ein Anwender in unserem Skill triggern kann und welche Spracheingaben (Utterances) welchen Intent auslösen.</li><li>Das zweite ist der Code der genau diese definierten Intents behandelt. Der also die Anfragen entgegennimmt, verarbeitet und (üblicherweise) mindestens mit einer Sprachausgabe antwortet. Dieser Code kann theoretisch als ein beliebiger Webservice angebunden werden, Amazon macht es einem aber einfacher, wenn man dafür eine Lambda-Funktion in der AWS-Cloud anlegt (so gehen wir hier vor).</li></ul><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/voice-interaction-model-to-lambda/"><img loading="lazy" src="https://media.graphassets.com/7qnCTtEWRDym4YNbLgSq" alt="Schematischer Ablauf des Aufrufs eines Alexa Skills wie im Text beschrieben." width="700" height="321" /></a> </p><h2>Das Voice Interaction Model</h2><p>Also unter: <a href="https://developer.amazon.com/alexa/console/ask" target="_blank">https://developer.amazon.com/alexa/console/ask</a>  einen neuen Skill anlegen, wofür zunächst ein Amazon Developer Account benötigt wird.</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/createnewskill/"><img loading="lazy" src="https://media.graphassets.com/734tya2FS1iiMLVvo6SC" alt="Screenshot der Seite zum Anlegen neuer Alexa Skills" width="700" height="286" /></a> </p><p>Da ich für diesen Blog-Eintrag einen “normalen” Skill erstellen wollte (kein Briefing, Smart Home oder Video Skill) muss als Model “Custom” gewählt werden. Zudem wird es für diesen Blog-Eintrag ein Skill in deutscher Sprache werden.<br /> Ist der Skill angelegt, werden wir von der Alexa Developer Console begrüßt. Dies ist die Seite in der das Sprachinterface (Voice Interaction Model) erstellt wird. Das Voice Interacation Model definiert, wie Anwender mit unserem Skill interagieren können, also welche ausgesprochenen Sätze erkannt und verarbeitet werden.<br /> Auf der rechten Seite ist Amazon so hilfreich uns eine Checkliste anzubieten. Um den Skill lauffähig zu bekommen müssen wir also folgendes tun:</p><ul><li>einen Invocation Name festlegen: der Name, den ein Anwender nennt um unseren Skill zu starten. In unserem Beispiel: Alexa, starte Fünferpasch (also ist der Invocation Name: “Fünferpasch”.</li><li>Intents, Samples and Slots definieren: die einzelnen Befehle die unser Skill entgegennimmt und wie der Anwender sie aufschreibt.</li><li>Das Modell abspeichern und bauen.</li><li>Den Endpoint definieren: der Endpoint ist der Code der aufgerufen wird um die Befehle zu verarbeiten. Im Allgemeinen eine AWS-Lambda-Funktion, obwohl auch ein anderer Webservice möglich ist.</li></ul><p>Der Invocation Name ist recht schnell festgelegt. Als nächstes folgt der erste Intent für den Skill. Für das Würfelspiel ist der erste Schritt, dass man ein Spiel mit x Spielern starten kann. Also benötigen wir einen Intent zum Start eines Spieles.<br /> Unter Intents:</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/initial-intents/"><img loading="lazy" src="https://media.graphassets.com/21d5Kl1lR2K3eF5vmE4Y" alt="Screenshot des Voice Interaction Model Editor in der alexa developer console" width="700" height="385" /></a> </p><p>wird nun ein neuer Intent “starteSpiel” angelegt. Unter “Sample Utterances” kann man Phrasen eintragen, die der Anwender sagen kann um diesen Intent auszulösen.</p><p>Innerhalb einer solchen Utterance kann man sogenannte Slots verwenden, als Platzhalter für variable Benutzereingaben.</p><p>Für das Würfelspiel starten wir mit einer einzigen Utterance:</p>

```
"Starte ein Spiel mit {spieleranzahl} Mitspielern"
```

<p>Die geschweiften Klammern kennzeichnen den Slot “spieleranzahl” dem im unteren Bereich des Bildschirms der Slot Typ “AMAZON.number” zugeordnet wird. Im Resultat kann ein Anwender nun den Intent mit einer beliebigen Anzahl an Mitspielern aufrufen.</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/startespielintent/"><img loading="lazy" src="https://media.graphassets.com/ZHjl45yaRcuQ7aCYWlu4" alt="Screenshot: Zuordnung eines Slot-Types zu einem Slot in einem Intent" width="700" height="381" /></a> </p><p>Wir könnten noch weitere Utterances ergänzen, oder Dialoge definieren mit denen Alexa fehlende Slots vom Anwender erfragen kann, aber an dieser Stelle wollen wir nur einen ersten Durchstich bis zur Implementierung der Lambda erzeugen.<br /> Das Modell kann nun gespeichert und gebaut werden.</p><h2>Setup der Lambda</h2><p>Um die Intents verwenden zu können, muss nun ein Service angelegt werden, der die Anfragen dazu verarbeitet.<br /> Verknüpft werden der Skill und die Lambda-Funktion unter dem Navigationseintrag “Endpoint”. Hier können wir momentan noch nicht die Lambda eintragen (die müssen wir ja erst anlegen), aber dort erfahren wir bereits die ID unseres Skill. Diese können wir im späteren Verlauf verwenden um den Zugriff auf unsere Lambda nur auf diesen einen Skill zu begrenzen.</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/skill-endpoint/"><img loading="lazy" src="https://media.graphassets.com/NAFblDGMQHuVpBJxO8SK" alt="Screenshot: Auslesen der Skill-Id auf der Seite zur Definition des Skill Endpoints" width="700" height="317" /></a> </p><p>Die neue Lambda wird angelegt aus der Lambda Management Console unter:<a href="https://eu-west-1.console.aws.amazon.com/lambda/home?region=eu-west-1#/functions" target="_blank">https://eu-west-1.console.aws.amazon.com/lambda/home?region=eu-west-1#/functions</a> </p><p>Für einen Alexa Skill in Deutschland muss die AWS Region (oben rechts) auf EU (Ireland) gestellt werden. Hier wählen wir “Funktion erstellen”.<br /> Auf der folgenden Seite können wir auswählen ob wir den Skill von Grund auf neu bauen, eine Vorlage verwenden oder uns im AW Serverless Application Repository bedienen.<br /> Hier habe ich schon den ersten Fehler gemacht und unter „Vorlagen“ eine Vorlage für einen Alexa Skill verwendet. Das ist aber sooo 2018. Damit erstellt man eine Lambda auf Basis des (natürlich völlig veralteten) Alexa-SDK. Wir wollen aber das aktuelle <a href="https://github.com/alexa/alexa-skills-kit-sdk-for-nodejs" target="_blank"><span>Alexa Skills Kit SDK for Node.js</span></a> <span> (kur ASK-SDK v2) verwenden. Dazu wählen wir das AWS Serverless Application Repository und verwenden dort die Applikation “alexa-skills-kit-nodejs-factskill” als Vorlage:<br /> <a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/aws-repository/"><img loading="lazy" src="https://media.graphassets.com/U6qeyGFkRmaqktWh7xXR" alt="Screenshot: Anlegen einer neuen Lambda Funktion basierend auf dem AWS Serverless Application Repository" width="700" height="347" /></a> </span></p><p>Auf dem folgenden Bildschirm vergeben wir noch einen Namen für die neue AWS-Anwendungen und schließen den Vorgang mit einem Klick auf Deploy ab.</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/create_lambda/"><img loading="lazy" src="https://media.graphassets.com/ATdIzwvQ1SCfuh416O3b" alt="Screenshot: Konfiguration des Namen der neuen Lambda Funktion" width="700" height="382" /></a> </p><p>Der Vorgang kann einige Zeit dauern. Aber die aktualisierte Vorlage legt automatisch auch eine Rolle mit Berechtigungen für die Ausführung der Lambda-Funktion an und erzeugt diese direkt für die Laufzeitumgebung node 8 (statt node 6). Wenn alles gut geht sieht der Bildschirm anschließend so aus:</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/deployment_status/"><img loading="lazy" src="https://media.graphassets.com/E3rnknkuQ7q9HtS3s4BZ" alt="Screenshot: Deployment Status der neu anzulegenden Lambda Funktion" width="700" height="366" /></a> <br /> Über den Button “Test App” kommen wir in die Anwendungsübersicht und von dort unter Ressourcen direkt zu unserem neuen Skill.</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/lambda_created/"><img loading="lazy" src="https://media.graphassets.com/EqCvDogQTGllLJ5FkNjy" alt="Screenshot: Übersicht über die neue Lambda Funktion mit dem Alexa Skill Kit Trigger" width="700" height="223" /></a> </p><p>Im Abschnitt Konfiguration > Designer ist bereits ein Auslöser (Trigger) für das Alexa Skills Kit eingetragen. Unsere neue Lambda-Funktion kann also durch einen Alexa Skill ausgelöst werden. Hier könnten wir auch die Skill-Id aus dem oberen Abschnitt hinterlegen um Zugriffe nur von diesem einen Skill zu erlauben.<br /> Wählen wir im Designer den Wurzelknoten für unsere Lambda aus (das ist bereits der Default wenn man die Seite öffnet), erscheint im unteren Bereich der Funktionscode unserer Lambda.<br /> Der Wizard hat uns dort einige Handler angelegt, leider für Intents die wir für unseren Skill gar nicht benötigen. Diesen Code könnten wir nun online in einer rudimentären IDE bearbeiten.<br /> Da wir aber mit git und unserer lokalen IDE arbeiten wollen, werden wir dies nun im nächsten Schritt ändern. Um aber einmal den Skill und die Lambda im Verbund testen zu können ersetzen wir nun den Code für die Index.js mit folgendem Code:</p><div>

```javascript
const Alexa = require('ask-sdk');
 
const LaunchRequestHandler = {
  canHandle(handlerInput) {
    const request = handlerInput.requestEnvelope.request;
    return request.type === 'LaunchRequest';
  },
  handle(handlerInput) {
    const speech = 'Willkommen bei Fünferpasch';
    return handlerInput.responseBuilder
      .speak(speech)
      .withSimpleCard(SKILL_NAME, speech)
      .getResponse();
    },
  };
 
const HelpHandler = {
  canHandle(handlerInput) {
    const request = handlerInput.requestEnvelope.request;
    return request.type === 'IntentRequest'
      && request.intent.name === 'AMAZON.HelpIntent';
  },
  handle(handlerInput) {
    return handlerInput.responseBuilder
      .speak('Hilfe kommt')
      .getResponse();
  },
};
 
const ExitHandler = {
  canHandle(handlerInput) {
    const request = handlerInput.requestEnvelope.request;
    return request.type === 'IntentRequest'
      && (request.intent.name === 'AMAZON.CancelIntent'
        || request.intent.name === 'AMAZON.StopIntent');
  },
  handle(handlerInput) {
    return handlerInput.responseBuilder
      .speak('Tschüss')
      .getResponse();
  },
};
 
const SessionEndedRequestHandler = {
  canHandle(handlerInput) {
    const request = handlerInput.requestEnvelope.request;
    return request.type === 'SessionEndedRequest';
  },
  handle(handlerInput) {
    console.log(`Session ended with reason: ${handlerInput.requestEnvelope.request.reason}`);
    return handlerInput.responseBuilder.getResponse();
  },
};
 
const ErrorHandler = {
  canHandle() {
    return true;
  },
  handle(handlerInput, error) {
  console.log(`Error handled: ${error.message}`);
    return handlerInput.responseBuilder
      .speak('Tut mir leid. Es ist ein Fehler aufgetreten')
      .reprompt('Der Techniker ist informiert')
      .getResponse();
  },
};
 
const SKILL_NAME = 'Fünferpasch';
 
const skillBuilder = Alexa.SkillBuilders.standard();
 
exports.handler = skillBuilder
  .addRequestHandlers(
    LaunchRequestHandler,
    HelpHandler,
    ExitHandler,
    SessionEndedRequestHandler
  )
  .addErrorHandlers(ErrorHandler)
  .lambda();
```

</div><p>Neben den Standard-Handlern für Error und Hilfe gibt es nun nur noch einen LaunchRequestHandler der ausgeführt wird, wenn unser Skill gestartet wird.<br /> Damit unser Skill dies auch auslöst, müssen wir nun unsere Lambda-Funktion als Endpoint für unseren Skill registrieren. Die ARN dazu finden wir am oberen rechten Bildschirmrand, praktischerweise versehen mit einem Button um diese direkt in die Zwischenablage zu kopieren.</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/arn/"><img loading="lazy" src="https://media.graphassets.com/M6m7HTJmTOSJak78T0Gu" alt="Screenshot: Ermitteln der ARN der Lambda Funktion" width="700" height="278" /></a> </p><p>Nun müssen wir wieder zurück zu unserem Skill wechseln und die ARN unter Endpoint in das Feld “Default Region” einfügen.</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/link-skill-to-lambda/"><img loading="lazy" src="https://media.graphassets.com/MvGyaZ69S1qcbpn3VUv6" alt="Screenshot: Verknüpfung des Alexa Skills mit der Lambda Funktion" width="700" height="276" /></a> </p><p>Nicht vergessen, diese Änderung mit “Save Endpoints” abzuspeichern.</p><p>Damit haben wir schon eine erste funktionsfähige Version unseres Skill. Bislang werden wir nur begrüßt, aber immerhin.<br /> Die einfachste Möglichkeit dies zu testen ist es, in der Hauptnavigation in den Tab “Test” zu wechseln. Dort könntet ihr über den Alexa Simulator per Tastatur mit dem Skill interagieren:</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/first-skill-test/"><img loading="lazy" src="https://media.graphassets.com/A4XEmcvXSLmyQMb5n86Z" alt="Screenshot: Test des Alexa Skills im Alexa Simulator" width="700" height="345" /></a> </p><p>Um den Skill aufzurufen, müsst ihr die Tests im Simulator zunächst erlauben. Dies stellt ihr im Dropdown-Feld oben links ein (im Screenshot markiert).</p><h2>Ausblick</h2><p>Damit hätten wir den ersten Schritt erreicht. <a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-2/">Der nächste Schritt</a>  wird sein, die Entwicklung der Lambda aus der Online IDE in eine lokale IDE zu verlegen.</p>

BDD für Alexa Skills – Teil 1: Initiales Setup

<p>Im <a href="https://blog.codecentric.de/2019/02/bdd-alexa-skills-teil1/">ersten Teil dieser Blogreihe</a>  haben wir einen Alexa Skill und die dazugehörige Lambda-Funktion angelegt, die die Befehle des Skills verarbeitet.<br /> Der nächste Schritt ist nun den Code für die Lambda in einer lokalen IDE zu bearbeiten und Änderungen dann in die Cloud zu deployen.</p><h2>Lokales Git Repository anlegen</h2><p>Zuerst einmal machen wir uns eine lokale Kopie der Lambda. Neben dem node_modules Verzeichnis (das erzeugen wir lokal) besteht diese momentan nur aus zwei Dateien: einer index.js mit dem JavaScript-Quellcode und einer package.json.<br /> Wir legen uns lokal ein neues Verzeichnis für den Skill. In diesem Verzeichnis legen wir nun eine index.js Datei an (in die wir den Inhalt der index.js aus der Lambda kopieren) und eine package.json Datei (die mit dem Inhalt der package.json aus der Lambda befüllt wird.</p><p>Alternativ kann man auch eine Zip-Datei der Lambda (inkl. des node_module Verzeichnisses) herunterladen. Dafür im Header unter Aktionen den Eintrag “Exportfunktion” auswählen:<br /> <a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/export-lambda/"><img src="https://media.graphassets.com/OdfqnGfXQEe7Yq04GGn5" alt="Screenshot: Export der Lambda Funktion als ZIP" width="700" height="154" /></a> </p><p>Im folgenden Dialog wählen wir “Bereitstellungspaket herunterladen”:<br /> <a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-2/export-lambda-dialog/"><img loading="lazy" src="https://media.graphassets.com/OvxfpdviReK83eZrQXOq" alt="Screenshot: Lambda Export als Bereitstellungspaket" width="700" height="232" /></a> </p><p>Nun können wir die in der package.json definierten Pakete lokal installieren. Als Paketmanager nutzen wir yarn. Also können wir mit einem einfachen “yarn” die Abhängigkeiten installieren.<br /> Jetzt ist auch Zeit dafür unser lokales git Repository anzulegen (und ggf. eine lokale .gitignore damit die node-module nicht im Repo landen).</p><h2>Upload der Dateien mit der aws-cli</h2><p>Den Upload von lokalen Änderungen zur AWS Cloud führen wir mit der AWS CLI durch. Die AWS CLI ist eine Commandline-Schnittstelle, die es unter anderem erlaubt den Code einer Lambda-Funktion zu aktualisieren. Hier habe ich viel Zeit verloren: Ich bin einem veralteten Tutorial aufgesessen und habe versucht die CLI über npm zu installieren. Die aktuelle Installation erfolgt aber über den Python-Paketmanager PIP. Schaut also einfach auf die AWS-CLI-Seite und befolgt die dortigen Installationsanweisungen.</p><h2>Einen Benutzer für die CLI anlegen</h2><p>Damit die CLI erfolgreich die Lambda aktualisieren kann, muss man ihr erst die notwendige Berechtigung erteilen. Dazu legt ihr zunächst im <a href="https://console.aws.amazon.com/iam/home?region=eu-west-1#/home" target="_blank">AWS Identity and Access Management (IAM)</a>  einen Benutzer an, der für den Upload verwendet wird.<br /> Meldet euch beim IAM an und wählt in der linken Navigation den Eintrag “Benutzer”. Im folgenden Bildschirm den Eintrag “Benutzer hinzufügen” auswählen.</p><p>Gebt dem Benutzer einen sprechenden Namen und wählt als Zugrifftyp “Programmgesteuerter Zugriff.<br /> <a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/iam_create_user/"><img loading="lazy" src="https://media.graphassets.com/bo8ZwaB2RsSVwtBv4Ty6" alt="Screenshot: Anlegen eines Benutzers für die AWS CLI in der IAM Console" width="700" height="524" /></a> </p><p>Im nächsten Schritt müsst ihr die Berechtigungen auswählen. Ich habe hier die vorhandene Richtlinie “AWSLambdaFullAccess” verwendet:</p><p><a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-2/iam_berechtigungen/"><img loading="lazy" src="https://media.graphassets.com/a79YKNXRKKf3OM0fbf3r" alt="Screenshot: Festlegen der Berechtigung des neuen Benutzers" width="700" height="510" /></a> </p><p>Überspringt die Tags und erstellt im letzten Bildschirm des Wizards den Benutzer. Wenn der Benutzer angelegt wurde, erhaltet ihr im folgenden Bildschirm die Zugangsdaten des Benutzers die wir für die CLI benötigen. Am besten ladet ihr euch diese als CSV-Datei herunter und speichert sie lokal an einem sicheren Ort ab.</p><p><a href="https://blog.codecentric.de/2022/01/bdd-alexa-skill-part1/iam_user_created/"><img loading="lazy" src="https://media.graphassets.com/dZ7ltoWWQx6DCvQj1sap" alt="Screenshot: Herunterladen der Zugangsdaten des neuen Benutzers als CSV Datei" width="700" height="329" /></a> </p><h2>Die CLI konfigurieren</h2><p>Jetzt könnt ihr die CLI konfigurieren. Geht dazu in eure Shell und führt den Befehl:<br /> aws configure<br /> aus. Nun werdet ihr nach der Access Key ID und dem Secret Access Key gefragt. Hier verwendet ihr die Zugangsdaten des soeben angelegten Benutzers. Als Default-Region müsst ihr Lambdas in Irland die Region “eu-west-1” angeben.</p><h2>Der erste Upload</h2><p>Jetzt sind wir schon fast soweit, die Lambda zum ersten Mal von der Commandline zu aktualisieren. Der Upload selbst erfolgt in Form eines ZIP-Archivs. Momentan hat unser Projekt folgende Struktur:</p><ul><li>index.js</li><li>package.json</li><li>node_modules/</li></ul><p>Diese Struktur wird nun gezippt, z.B. aus der Shell mit</p>

```
zip -r fuenferpasch.zip index.js package.json node_modules/
```

<p>Anschließend können wir dieses ZIP mit der CLI in die AWS Cloud hochladen. Dafür benötigen wir aber noch einmal die ID unserer Lambda-Funktion. Diese haben wir bereits im ersten Teil dieser Artikelserie verwendet um den Alexa Skill mit der Lambda zu verknüpfen.</p>

```
aws lambda update-function-code --function-name  --zip-file fileb://./fuenferpasch.zip"
```

<p>Im Erfolgsfall wird euch dies durch eine JSON-Ausgabe auf der Commandline quittiert.</p><p>Es bietet sich an, diese beiden Befehle (die Erstellung des ZIP-Archivs und das Upload desselbigen) in einem Script zusammenzufassen und in der package.json zu hinterlegen. So reicht später ein einfacher Aufruf von</p>

```
yarn upload
```

<p>um die Lambda in der Cloud zu aktualisieren.<br /> Die aktualisierte package.json sieht somit so aus:</p><div>

```javascript
{
    "name": "Fuenferpasch",
    "version": "0.0.1",
    "description": "Blogartikel Demo Skill",
    "main": "index.js",
    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "upload": "zip -r fuenferpasch.zip index.js package.json node_modules/ && aws lambda update-function-code --function-name  --zip-file fileb://./fuenferpasch.zip"
    },
    "keywords": [
        "alexa",
        "skill",
        "demo"
    ],
    "author": "codecentric.de",
    "dependencies": {
        "ask-sdk": "^2.0.0"
    }
}
```

</div><h2>Ausblick</h2><p>Mit diesem Stand können wir nun unsere Lambda lokal entwickeln und in der Cloud aktualisieren. Das ist nett, man merkt aber auch relativ schnell, dass die Turn-Around-Zeiten in der Entwicklung viel zu hoch sind. Gerade am Anfang passieren einem noch häufiger Fehler, wenn man sich mit der neuen API vertraut machen muss. Ein neuer Intent wird im Voice-Model angelegt, ein passender Handler geschrieben, der Code gezippt und hochgeladen, der Alexa Simulator geöffnet, der Skill gestartet, der Satz zum Auslösen des Intents eingegeben und … es kommt die Antwort “Bei der Ausführung des angeforderten Skills ist ein Problem aufgetreten”. Zum Glück gibt es in solchen Fällen die Log-Ausgaben in der <a href="https://eu-west-1.console.aws.amazon.com/cloudwatch/home?region=eu-west-1#logs:" target="_blank">Cloud Watch Management Console</a> . Also sucht man in den Logs, ergänzt Logausgaben um schließlich festzustellen, dass man vergessen hat den neuen Intent im Skill zu registrieren. Oder man hatte einen einfachen Tippfehler. Das ist alles schnell passiert, kann auch einfach behoben werden, aber die Zeitspanne zum Auffinden dieser Fehler ist viel zu hoch.<br /> Spätestens an diesem Punkt hatte ich mich davon verabschiedet, auf Tests verzichten zu wollen. <a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-3/">Im nächsten Beitrag dieser Artikelserie</a>  schauen wir uns dann an, wie wir das bisherige Projekt um Unit-Tests, Linting und Transpiling ergänzen (um auch neue JavaScript Features wie async / await nutzen zu können).</p>

BDD für Alexa Skills – Teil 2: Lokale Lambda-Entwicklung

<p>Dies ist der dritte Teil einer Serie von Blog-Artikeln über die Entwicklung eines Alexa Skills. Diesmal machen wir auf dem Weg zu Behaviour-Driven-Development (BDD) einen Zwischenstopp bei Test-Driven-Development (TDD). Die Grundlagen dafür legen wir mit der Konfiguration von Jest um Unit-Tests für unseren Skill verfassen zu können.</p><h2>Was bisher geschah</h2><ul><li><a href="https://blog.codecentric.de/2019/02/bdd-alexa-skills-teil1/">Teil 1: Initiales Setup</a> </li><li><a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-2/">Teil 2: Lokale Lambda Entwicklung</a> </li></ul><p>Mit dem Ende des zweiten Artikels sind wir in der Lage, die Lambda-Funktion die unseren Skill bedient mit einer lokalen IDE zu entwickeln und dann in der Cloud zu aktualisieren.</p><h2>Nächste Schritte</h2><p>Um unsere Skill-Entwicklung weiter zu beschleunigen, wollen wir Fehler möglichst früh finden, also nicht erst wenn die Lambda-Funktion in der Cloud deployed wurde. Um dies zu erreichen werden wir im Rahmen dieses Blog-Posts die lokale Entwicklung um folgende Dinge erweitern:</p><ul><li>Statische Analyse des Codes mit ESLint</li><li>Typechecking mit Flow</li><li>Unit-Tests mit Jests</li></ul><p>Zusätzlich erfolgt die Übersetzung (Transpilierung) des JavaScript-Codes mit babel (damit wir in unserem Skill moderne JavaScript Features verwenden können) und ein Bundling der resultierenden Dateien mit webpack.</p><p>Die Vorteile einer statischen Analyse oder eines Typecheckers aufzuzeigen würde den Rahmen dieser Artikelserie sprengen. Für unser Ziel, Fehler in der Skill-Entwicklung möglichst früh zu finden, sind sie sehr gut geeignet. Bei der Wahl eines Typsystems für JavaScript wäre Typescript eine naheliegende Alternative gewesen. Ich habe mich in diesem Projekt für Flow entschieden, da ich mit Flow bereits vertraut war und ich mich somit besser auf das Lernen der Skill-Entwicklung konzentrieren konnte (ohne noch eine weitere neue Technologie lernen zu müssen).</p><p>Für die Unit-Tests habe ich mich für Jest entschieden. Eine Einleitung zu diesem JavaScript Testing Framework findet sich<a href="https://blog.codecentric.de/2017/06/javascript-unit-tests-sind-schwer-aufzusetzen-keep-calm-use-jest/" target="_blank"> hier im codecentric Blog</a> .</p><h2>Setup von ESLint, Flow, Jest, Babel und Webpack</h2><p>Das Setup dieser Toolchain war leider kein linearer Prozess. Unterschiedliche Versionen von babel und jest gepaart mit vielen verschiedenen Konfigurationsmöglichkeiten führten zu einigen Schleifen in der Entwicklung. Aus diesem Grund teile ich hier nur die finalen Konfigurationsdateien.</p><p>Hervorheben möchte ich die finale webpack-Konfiguration, hier haben zwei kleine Fehlkonfigurationen mehrtägige Debugging-Sessions verursacht (die leider nicht einfach zu diagnostizieren waren, da der Skill grundsätzlich funktionierte, nur Zugriffe auf einen Persistent Adapter nicht möglich waren).</p><p>Wichtig waren hier die beiden Einstellungen:</p>

```
target: 'node',
externals: [ 'aws-sdk' ]

```

<p>Die vollständigen Konfigurationsdateien findet ihr <a href="https://gitlab.com/spittank/fuenferpasch/tree/BlogPart3_TDD" target="_blank">hier im Repository auf gitlab</a> .</p><h2>Projektstrukturierung</h2><p>Nach dem Setup der diversen Tools sind wir nun in der Lage, erste Unit-Tests mit Jest zu verfassen.</p><p>Schauen wir uns zunächst einmal den Aufbau der Lambda für unseren Skill an, um uns eine sinnvolle Strukturierung zu überlegen. Neben vielen Konfigurationsdateien besteht die Lambda-Funktion aktuell nur aus einer einzigen JavaScript-Datei, der index.js.</p><p>In der Datei finden wir Handler für verschiedene Requests und Code der über einen Skillbuilder die eigentliche Lambda-Funktion zusammenbaut und für den Aufruf durch unseren Skill exportiert.</p><p>Für jeden Intent den wir in unserem Voice Interaction Model definieren, müssen wir einen IntentHandler in unserer Lambda implementieren. Um diese Handler isoliert testen zu können, ist es sinnvoll diese in eigene Dateien zu extrahieren. In der index.js verbleibt dann nur noch der Glue-Code, der die einzelnen Handler zur exportierten Lambda-Funktion zusammenbaut.</p><p>Mit der Einführung von Babel und webpack sind alle Quelldateien in das Unterverzeichnis <em>src</em> gewandert. Die von webpack generierte Datei wird hingegen im Unterverzeichnis <em>build</em> abgelegt.</p><p>Es ergibt sich bislang folgende Verzeichnisstruktur:</p><ul><li><code>/build</code>: Hier landet der build-output. Momentan ist dies die von webpack erzeugte index.js</li><li><code>/flow-typed</code>: In diesem Verzeichnis befinden sich Typdefinitionen von flow (konkret bislang die Typdefinitionen für jest)</li><li><code>/src</code>:<ul><li><code>/handler</code>: Im Unterverzeichnis <em>handler</em> landen alle Handler für Intents unseres Skill, plus weitere Handler die nicht an einen bestimmten Intent gebunden sind. Da die Anzahl an Intents im Weiteren wachsen wird, sind diese Handler in weitere Unterverzeichnisse aufgeteilt.<ul><li><code>/lifecycle</code>: Handler für bestimmte Ereignisse im Lebenszyklus eines Skills (z. B. launch, stop/ cancel, sessionEnded)</li><li><code>/help</code>: Handler für den Help Intent</li></ul></li><li><code>/own-flow-types</code>: Selbst definierte flow-typen für externe Bibliotheken die ich bei Bedarf nach und nach ergänzt habe. Typescript hat hier die breitere Unterstützung, aber die Flow-Typen zu definieren geht leicht von der Hand und hilft beim Verständnis der eingesetzten Bibliotheken.<ul><li><ul><li><code>/aws-sdk</code>: Flow Typen für das aws-sdk</li></ul></li></ul></li></ul></li><li><code>voiceUI</code>: Dieses Verzeichnis nutzen wir um lokal eine Kopie des Voice Interaction Model zu halten (Details dazu im vierten Teil dieser Blogserie).</li></ul><h2>Aktualisierung der Lambda</h2><p>Durch die geänderte Verzeichnisstruktur und die Einführung von babel und webpack muss auch die Aktualisierung der Lambda-Funktion in der Cloud angepasst werden. Die erste notwenige Änderung ist der Befehl <code>yarn upload</code>in der package.json. Dieser muss nun zunächst den Build mit webpack triggern und dann die erzeugte Datei aus dem Build-Verzeichnis zippen um dieses Zip dann mit der aws-cli in der Cloud zu aktualisieren.</p><p>Der angepasste Befehl sieht nun so aus:</p><div>

```javascript
    "scripts": {
        ...
        "webpack": "webpack",
        "upload": "yarn webpack && zip -r fuenferpasch.zip package.json build/main.js && aws lambda update-function-code --function-name arn:aws:lambda:eu-west-1:668867983508:function:serverlessrepo-fuenferpas-alexaskillskitnodejsfact-40MX9KL1B0PB --zip-file fileb://./fuenferpasch.zip"
    }
```

</div><p> </p><p>Durch die geänderte Verzeichnisstruktur liegt aber nun auch die generierter Lambda-Funktion an einer anderen Stelle. Dies müssen wir auch in der Lambda-Konfiguration in der Cloud anpassen, sonst wird bei der Ausführung immer noch am ursprünglichen Ort gesucht. Dazu öffnen wir die <a href="https://eu-west-1.console.aws.amazon.com/lambda/home?region=eu-west-1#/functions" target="_blank">Lambda Management Console</a> , wählen aus der Liste der Lambda-Funktionen die Funktion zu unserem Skill aus und passen im Folgenden den Handler an:<br /> <a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-3/change-handler-after-adding-build-folder/"><img src="https://media.graphassets.com/JCsOV0ZmRmSaCtUoV0QL" alt="Screenshot: Anpassung des Orts an dem AWS den exportieren Handler der Lambda Funktion erwartet." width="700" height="449" /></a> </p><h2>Der erste Unit-Test</h2><p>Schauen wir uns einmal den Aufbau eines Handlers am Beispiel des LaunchHandlers an:</p><div>

```javascript
// @flow
import {SKILL_NAME} from '../../consts';
import type {HandlerInput, Response} from '../../own-flow-types/ask-sdk/inputHandler';
 
export const LaunchRequestHandler = {
    canHandle(handlerInput: HandlerInput): boolean {
        const request = handlerInput.requestEnvelope.request;
        return request.type === 'LaunchRequest';
    },
    handle(handlerInput: HandlerInput): Response {
        const speech = 'Willkommen bei Fünferpasch';
        return handlerInput.responseBuilder
            .speak(speech)
            .withSimpleCard(SKILL_NAME, speech)
            .getResponse();
    }
};
```

</div><p>Ein Handler ist also ein Objekt das zwei Methoden anbieten:</p><ul><li><code>canHandle</code>: wird vom Alexa Voice Service aufgerufen um zu bestimmen, ob sich ein Handler für einen bestimmten Request verantwortlich fühlt. Für den LaunchRequestHandler geschieht dies rein anhand des Request-Typs. Für einen Intent-Handler muss auch noch der Intent-Name hinzugezogen werden um zu entscheiden, ob der Handler genau für diesen Intent zuständig ist.</li><li><code>handle</code>: wird aufgerufen, wenn entschieden wurde, dass genau dieser Handler für den Request verantwortlich ist. Dieser bekommt dann die vorverarbeiteten Benutzereingaben verpackt im handlerInput-Objekt, um diese zu verarbeiten und das Ergebnis als Response zur Verfügung zu stellen.</li></ul><p>Beide Methoden lassen sich sehr gut mit einem Unit-Test testen. Auch der einfache Test der canHandle-Methode empfiehlt sich, denn es ist schnell passiert, dass man einen neuen Handler anlegt, aber den Intent-Namen nicht genau trifft (oder einen existierenden Handler kopiert und vergisst, den Namen anzupassen). Dann merkt man den Fehler erst nachdem der Skill gebaut, gezippt, hochgeladen und im Simulator gestartet wurde. Mit dem Test haben wir direkte Sicherheit.</p><p>Für den Test benötigen wir ein <code>handlerInput</code>-Objekt mit dem wir unseren Handler aufrufen können. Hierfür habe ich eine kleine Hilfsfunktion geschrieben, die uns ein konfigurierbares Mockobjekt zur Verfügung stellt.</p><p>Mit dieser Hilfsfunktion sieht ein Test für den LaunchRequestHandler dann so aus:</p><div>

```javascript
import {LaunchRequestHandler} from './launchRequest';
import {getMockHandlerInputForIntent, getMockHandlerInputForLaunch} from '../../test/mockHandlerInput';
import type {MockResponse} from '../../test/mockHandlerInput';
 
describe('LaunchRequestHandler', () => {
    describe('can handle should', () => {
        it('return true for a LaunchRequest', () => {
            expect(LaunchRequestHandler.canHandle(getMockHandlerInputForLaunch())).toEqual(true);
        });
 
        it('return false for another intent', () => {
            expect(LaunchRequestHandler.canHandle(getMockHandlerInputForIntent('unhandledIntent'))).toEqual(false);
        });
    });
 
    describe('handle should', () => {
        it('not crash', async () => {
            expect(LaunchRequestHandler.handle(getMockHandlerInputForLaunch())).toBeDefined();
        });
 
        it('say hello', async () => {
            const response: MockResponse = LaunchRequestHandler.handle(getMockHandlerInputForLaunch());
            expect(response.speechText).toEqual('Willkommen bei Fünferpasch webpack');
        });
    })
});
```

</div><p>Die <code>canHandle</code>-Methode wird mit zwei unterschiedlichen handlerInput-Objekten getestet. Einmal simulieren wir einen HandlerInput mit einem LaunchRequest und erwarten, dass die <code>canHandle</code>-Methode true zurück gibt, einmal simuliert der HandlerInput einen Request für einen Intent mit dem Namen ‚unhandledIntent‘, der erwartungsgemäß vom LaunchRequestHandler ignoriert wird.</p><p>Die <code>handle</code>-Methode erfährt ebenfalls zwei Prüfungen. Der erste Test prüft nur, dass die Methode ohne Fehler aufgerufen werden kann. Der zweite Test prüft hingegen, ob der Handler auch die erwartete Antwort für den Anwender generiert.</p><p>Das funktioniert, weil wir dem Handler unser eigenes Mock-handlerInput-Objekt mitgegeben haben. Die Response des Handlers wird generiert mit einem ResponseBuilder-Objekt, das dem Handler über den handlerInput zur Verfügung gestellt wird. Unser Mock-Objekt stellt dem Handler aber einen besonderen MockResponseBuilder zur Verfügung, der die Aufrufe des ResponseBuilders aufzeichnet und für spätere Überprüfungen im Test als MockResponse zur Verfügung stellt. So können wir im Test prüfen, ob im Handler die Methode <code>speak</code> mit einem bestimmten Text aufgerufen wurde, der uns im MockResponse-Objekt als speechText zur Verfügung steht. Dies können wir nach und nach für alle Methoden des ResponseBuilders ergänzen die wir in unseren Handler nutzen und testen wollen.</p><p>Momentan sieht der MockResponseBuilder so aus:</p><div>

```javascript
const getMockResponseBuilder = (): $Shape<MockResponse> => {
    const that: MockResponse = {
        speak: (speechText: string) => {
            that.speechText = speechText;
            return that;
        },
        reprompt: (repromptText: string) => {
            that.repromptText = repromptText;
            return that;
        },
        withSimpleCard: (title: string, cardText: string) => {
            that.simpleCardTitle = title;
            that.simpleCardText = cardText;
            return that;
        },
        withShouldEndSession: (shouldEndSession: boolean) => {
            that.shouldEndSession = shouldEndSession;
            return that;
        },
        withAskForPermissionsConsentCard: (permissions: string[]) => {
            that.requestedPermissions = permissions;
            return that;
        },
        addDelegateDirective: (updatedIntent): MockResponse => {
            const mockResponse: mockResponse = {
                ...that,
                updatedIntent
            };
            return mockResponse;
        },
        getResponse: () => that,
        speechText: '',
        repromptText: '',
        simpleCardText: '',
        simpleCardTitle: '',
        shouldEndSession: undefined,
        updatedIntent: undefined,
        hasDelegateDirective: false
    };
    return that;
};
```

</div><p>Wir können nicht nur testen, ob unser Handler mit einem Text geantwortet hat, über eine ConsentCard vom Benutzer weitere Berechtigungen erfragt oder die Session beendet hat.</p><h2>Ausblick</h2><p>Mit diesem Setup haben wir einen Stand erreicht, mit dem wir die Handler für unseren Skill test-driven entwickeln können. Fehler beim Matching unseres Voice Interaction Models auf unsere Handler finden wir so aber noch nicht.<br /> Darum geht es unter anderem <a href="https://blog.codecentric.de/2019/03/alexa-skills-bdd-cucumber-4/">im nächsten Teil dieser Artikelserie</a> , indem wir lernen wie wir Akzeptanztests mit Hilfe von cucumber.js formulieren können um so unser gesamtes Setup vom Voice Interaction Model bis hinunter zum Handler testen zu können.</p>

BDD für Alexa Skills – Teil 3: Unit-Testing mit Jest

<p>Dies ist der fünfte Teil einer Serie von Blogposts über Behaviour Driven Development (BDD) eines Alexa Skills. In diesem Beitrag erweitern wir unser Testframework um die Behandlung von Status-Informationen.</p><h2>Was bisher geschah</h2><ul><li><a href="https://blog.codecentric.de/2019/02/bdd-alexa-skills-teil1/">Teil 1: Initiales Setup</a> </li><li><a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-2/">Teil 2: Lokale Lambda Entwicklung</a> </li><li><a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-3/">Teil 3: Unit Testing mit Jest</a> </li></ul><p>In den ersten vier Beiträgen dieser Artikelserie haben wir einen Alexa Skill aufgesetzt. Schritt für Schritt wurde die Lambda-Entwicklung für diesen Skill um Linting, ein Typsystem, Unit-Tests mit Jest erweitert und Akzeptanztests mit cucumber.js ergänzt.</p><h2>State-Handling in unseren Tests</h2><p>Auf unserem Weg zu Behaviour Driven Development für unseren Skill bildet der entwickelte Mock Voice Service die Grundlage um die Lambda-Funktion gezielt aus dem Test heraus aufzurufen und Erwartungen an die Ergebnisse zu formulieren.</p><p>In diesem Teil der Serie werden wir das Handling der Lambda im Test so verbessern, dass unser Skill auch State-Handling nutzen kann. Amazon erlaubt es uns, den Zustand eines Skills auf drei verschiedenen Ebenen zu speichern:</p><ul><li>auf Ebene des Requests,</li><li>auf Ebene der Session oder</li><li>persistent mit Hilfe eines PersistenceAdapters (Amazon bietet einen solchen Adapter z.B. für eine MongoDB an, der mit sehr wenig Aufwand konfiguriert werden kann)</li></ul><p>Eine Speicherung rein auf Ebene eines einzelnen Requests ist sehr flüchtig und hat somit nur ein sehr begrenztes Einsatzgebiet. Spannender ist da schon die Speicherung von Daten für die Lebensdauer einer Session.</p><h3>Was ist eine Alexa-Session</h3><p>Bevor wir uns anschauen, wie wir Informationen für eine Session speichern können, sollten wir zunächst einmal klären, was genau eine Session denn im Kontext eines Alexa Skills ist:</p><ul><li>Eine Session beginnt in dem Moment, in dem der Nutzer den Skill startet.</li><li>Eine Session endet, wenn:<ul><li>der Benutzer die Session explizit beendet (z.B. mit „Alexa, stopp“). Dann erhält unser Skill einen Stopp-Intent.</li><li>der Benutzer nach der letzten Antwort von Alexa nicht innerhalb von acht Sekunden wieder mit dem Skill interagiert.</li><li>Diese Zeit können wir einmal verlängern, wenn wir zusätzlich zur Sprachausgabe noch einen Reprompt in unsere Response einbauen. Mit diesem fragt Alexa dann noch einmal nach, kommt innerhalb von (erneuten) acht Sekunden dann wieder keine Antwort, wird der Skill beendet.</li><li>Ein Skill wird auch beendet, wenn bei der Verarbeitung der Skill-Anfrage ein Fehler auftritt.</li></ul></li></ul><p>Die Lebensdauer einer Alexa-Session ist also eng daran gebunden, dass der Nutzer kontinuierlich mit dem Skill interagiert (und somit potenziell recht kurz). Das gilt im Übrigen für Custom-Skills, Musik- oder Video-Skills verhalten sich da anders.</p><h3>Session-Attribute</h3><p>Für die Dauer einer Session können wir uns den aktuellen Zustand in Session-Attributen merken. Diese Session-Attribute bekommen wir als Key-Value-Store über den <code>AttributeManager</code> des <code>handlerInput</code> bereitgestellt.</p><p>Für Session-Attribute bietet uns der Attribute-Manager zwei Methoden an:</p><ul><li><code>getSessionAttributes</code> zum Auslesen der Session-Attribute</li><li><code>setSessionAttributes</code> zum Setzen der Session-Attribute</li></ul><p>Im <code>starteSpiel</code> Intent unseres Würfelspiel-Skills wollen wir uns die Anzahl an Mitspielern für die aktuelle Session merken. Dies sieht dann z.B. so aus:</p><div>

```javascript
// @flow
import {HandlerInput} from 'ask-sdk-core';
import {Response} from 'ask-sdk-model';
import {PLAYER_COUNT_KEY, SKILL_NAME} from '../../consts';
import {deepGetOrDefault} from '../../deepGetOrDefault';
 
export const StarteSpielIntentHandler = {
    canHandle(handlerInput: HandlerInput) {
        return handlerInput.requestEnvelope.request.type === 'IntentRequest' &&
            handlerInput.requestEnvelope.request.intent.name === 'starteSpiel';
    },
    handle(handlerInput: HandlerInput): Response {
        const numberOfPlayers = deepGetOrDefault(handlerInput, '1', 'requestEnvelope', 'request', 'intent', 'slots', 'spieleranzahl', 'value');
 
        const playersText = numberOfPlayers === '1' ? 'einen' : numberOfPlayers;
        const speechText = `Prima, ich habe ein neues Spiel für ${playersText} Mitspieler gestartet`;
        const sessionAttributes = handlerInput.attributesManager.getSessionAttributes();
        const newSessionAttributes = {
            ...sessionAttributes,
            [PLAYER_COUNT_KEY]: numberOfPlayers
        };
        handlerInput.attributesManager.setSessionAttributes(newSessionAttributes);
 
        return handlerInput.responseBuilder
            .speak(speechText)
            .withSimpleCard(SKILL_NAME, speechText)
            .withShouldEndSession(false)
            .getResponse();
    }
};
```

</div><p>Wir lesen den Wert des Slots <code>spieleranzahl</code> aus dem Request aus (<code>deepGetOrDefault</code> ist eine kleine Hilfsmethode, die aus einem Objektbaum beliebiger Tiefe einen Wert ausliest oder einen übergebenen Default-Wert zurückliefert, wenn irgendein Attribut auf dem Pfad zum Wert undefined ist).</p><p>Nachdem die Antwort zusammengebaut wurde, merken wir uns diesen Wert in den Session-Attributen und speichern diese mit <code>setSessionAttributes</code> wieder ab.</p><p>In unserem Skill können wir nun einfach einen Intent anbieten, mit dem der Nutzer die aktuelle Anzahl an Mitspielern erfragen kann.</p><p>Dies können wir nun bereits sehr gut als Akzeptanztest in cucumber.js formulieren:</p>

```
# language: de
Funktionalität: Ein Spiel starten
  Grundlage:
    Angenommen der Anwender hat den Skill geöffnet

  Szenario: Ein neues Spiel kann gestartet werden, die Anzahl an Mitspielern wird gespeichert
    Wenn der Anwender sagt: Starte ein Spiel mit 4 Spielern
    Dann antwortet Alexa mit: Prima, ich habe ein neues Spiel für 4 Mitspieler gestartet
    Wenn der Anwender sagt: Wieviele Spieler gibt es
    Dann antwortet Alexa mit: Du spielst mit 4 Spielern

```

<p>Um diesen Test grün zu bekommen, müssen wir nun folgende Dinge tun:</p><ol><li>Wir müssen unser Voice Interaction Model um einen Intent „wieVieleSpieler“ erweitern und mindestens die eine Utterance „Wieviele Spieler gibt es“ ergänzen</li><li>Wir müssen in der Lambda einen <code>wieVieleSpieler</code> Handler für diesen Intent programmieren</li><li>Und einmalig müssen wir unser Test-Setup so erweitern, dass unser Mock Voice Service die Session-Attribute zwischen zwei Requests korrekt speichert und weitergibt</li></ol><h3>SetSessionAttributes im Test abfangen</h3><p>Fangen wir mit dem letzteren Punkt an, diesen müssen wir nur genau einmal machen um unser Testframework für die Behandlung von Session-Attributen zu erweitern.</p><p>Im Test müssen wir mitbekommen, wenn ein Intent-Handler die Session-Attribute verändert, damit wir diese dann dem nächsten Step in dem gleichen Test (und somit der gleichen Session) wieder zur Verfügung stellen können. Die Lösung bietet uns ein <a href="https://developer.amazon.com/de/blogs/alexa/post/0e2015e1-8be3-4513-94cb-da000c2c9db0/what-s-new-with-request-and-response-interceptors-in-the-alexa-skills-kit-sdk-for-node-js" target="_blank">RequestInterecptor</a> . Mit diesem können wir das handlerInput-Objekt eines Requests bearbeiten, bevor dieses an den Skill weitergegeben wird. Dazu wandeln wir die Skill-Erzeugung in der index.js auf eine Factory-Methode um, der wir optional – für unseren Test – einen RequestInterceptor mitgeben können.</p><div>

```javascript
export const createSkill = (requestInterceptor?: RequestInterceptor) => {
    const skillBuilder = Alexa.SkillBuilders.standard();
 
    const skill = skillBuilder
        .addRequestHandlers(
            ExitHandler,
            HelpHandler,
            LaunchRequestHandler,
            SessionEndedRequestHandler,
            StarteSpielIntentHandler,
            WieVieleSpielerIntentHandler
        )
        .addErrorHandlers(ErrorHandler);
    if (requestInterceptor) {
        skill.addRequestInterceptors(requestInterceptor);
    }
 
    return skill.lambda();
};
```

</div><p>In der index.js die unseren Skill für die produktive Nutzung erzeugt, ist der Aufruf nun ein Einzeiler:</p><div>

```javascript
export const handler = createSkill();
```

</div><p>Für den Test ist eine <code>createSkillForTest</code> Methode vorgeschaltet, die den Skill mit einem RequestInterceptor aufruft:</p><div>

```javascript
function createSkillForTest(world) {
    const requestInterceptor: RequestInterceptor = {
        process(handlerInput: HandlerInput) {
            // Wrap setSessionAttributes, so that we can save these Attributes in the test
            const orginalSetSessionAttributes = handlerInput.attributesManager.setSessionAttributes;
            handlerInput.attributesManager.setSessionAttributes = (attributes: Attributes) => {
                world.sessionAttributes = attributes;
                orginalSetSessionAttributes.call(handlerInput.attributesManager, attributes);
            }
        }
    };
    return createSkill(requestInterceptor)
}
```

</div><p>Im RequestInterceptor ersetzen wir die <code>setSessionAttributes</code>-Methode des attributeManagers durch eine eigene Funktion, die die zu speichernden Attribute im World-Objekt speichert und anschließend die Originalmethode aufruft.</p><p>Die <code>executeRequest</code>-Methode aus dem letzten Blogartikel wird nun um eine Zeile erweitert, die dafür sorgt, dass die SessionAttribute aus dem letzten Request an den nächsten Request weitergegeben werden:</p><div>

```javascript
async function executeRequest(world, skill, request) {
    return new Promise((resolve) =>; {
        // Handle session attributes
        request.session.attributes = simulateDeserialization(world.sessionAttributes);
        skill(request, {}, (error, result) =>; {
            world.lastError = error;
            world.lastResult = result;
            resolve();
        });
    });
}
```

</div><p>Die <code>simulateDeserialization</code> simuliert dabei eine Serialisierung indem sie den Attributes Key-Value-Store einmal in einen JSON-String und zurück umwandelt. Dies hilft dabei Fehler zu finden, die sonst im Test verdeckt wären: Instanzen einer ES6-Klasse verlieren z.B. (wenn man nichts dagegen tut)<a href="https://stackoverflow.com/questions/38922990/re-associating-an-object-with-its-class-after-deserialization-in-node-js" target="_blank"> bei der Serialisierung ihre Class-Properties</a> .</p><h3>Implementierung des Handlers für den wieVieleSpieler-Intent</h3><p>Mit diesem Test-Stetup ist es nun sehr einfach, den neuen Intent test-driven umzusetzen. Die fertige Implementierung findet sich <a href="https://gitlab.com/spittank/fuenferpasch" target="_blank">im Repository in Gitlab</a> .</p><h2>PersistentState Handling</h2><p>Den State in einer Session halten (und testen) zu können ist gut und wichtig. Wie oben beschrieben, sind Alexa-Sessions aber potenziell recht kurz. Je nach Art des Skill stößt man hier also schnell an seine Grenzen. Zum Glück bietet das Alexa-Skill-Kit-SDK auch eine Möglichkeit, Daten über die Grenzen einer Session hinaus zu persistieren.</p><p>Die API für PersistentAttributes ist ähnlich wie die für SessionAttributes:</p><ul><li><code>getPersistentAttributes</code> liefert die Session-Attribute asynchron als Promise</li><li><code>setPersistentAttributes</code> setzt die Session-Attribute</li><li>und zusätzlich <code>savePersistentAttributes</code> erlaubt es, die Session-Attribute asynchron zu persistieren</li></ul><p>Damit wir diese API verwenden können, müssen wir dem Skill aber mitteilen, wie wir unsere Daten persistieren wollen. Dafür müssen wir dem Skill bei der Erzeugung einen <code>PersistenceAdapter</code> mitgeben. Diesen Apdapter können wir entweder anhand <a href="http://ask-sdk-node-typedoc.s3-website-us-east-1.amazonaws.com/interfaces/persistenceadapter.html" target="_blank">des vorgegebenen Interfaces</a>  selbst implementieren, oder <a href="https://ask-sdk-for-nodejs.readthedocs.io/en/latest/Managing-Attributes.html#persistenceadapter" target="_blank">einen der fertigen Adapter</a>  nutzen.</p><p>Für den produktiven Betrieb werden wir den fertigen <code>DynamoDbPersistenceAdapter</code> nutzen, für die Tests implementieren wir unseren eigenen Adapter.</p><h3>Hinzufügen des DynamoDbPersistenceAdapters</h3><p>Um den DynamoDB-Adapter verwenden zu können, müssen wir das Paket <code>ask-sdk-dynamodb-persistence-adapter</code> zu unserem Projekt hinzufügen.</p><h3>Rechtevergabe für unsere Lambda-Funktion</h3><p>Außerdem müssen wir unserer Lambda-Funktion Zugriff auf die DynamoDB gewähren. Dazu navigieren wir auf der <a href="https://eu-west-1.console.aws.amazon.com/lambda/home?region=eu-west-1#/functions" target="_blank">Lambda Management Console</a>  zu unserer Lambda-Funktion und prüfen die Rolle, die unserer Lambda zugewiesen ist:<br /> <a href="https://blog.codecentric.de/2019/03/alexa-skills-bdd-cucumber-5/lambda-execution-role-2/"><img src="https://media.graphassets.com/vzgKyxgZRLimqD5kmg4s" alt="Screenshot: Ermittlung der ausführenden Rolle in der Lambda Management Console" width="700" height="332" /></a> </p><p>Diese Rolle suchen wir wiederum in der <a href="https://console.aws.amazon.com/iam/home?region=eu-west-1#/roles" target="_blank">IAM Management Console</a>  um dort der Rolle die Berechtigung für den Zugriff auf die DynamoDB einzuräumen.</p><p><a href="https://blog.codecentric.de/2019/03/alexa-skills-bdd-cucumber-5/richtlinie-zu-aws-rolle-hinzufu%cc%88gen/"><img loading="lazy" width="700" height="274" src="https://media.graphassets.com/nE227ssQhqJzv1X6ccA9" alt="Richtlinie zur AWS Rolle hinzufügen" /></a> </p><p>Im folgenden Bildschirm suchen wir nach der Richtlinie <em>AmazonDynamoDBFullAccess</em> und fügen diese unserer Rolle hinzu.</p><h3>Konfiguration des Skills für die Nutzung des DynamoDB Adapters</h3><p>Um den DynamoD-Adapter nun produktiv nutzen zu können, müssen wir unsere <code>createSkill</code>-Methode erweitern:</p><div>

```javascript
export const createSkill = (PersistenceAdapterClass: Class, requestInterceptor?: RequestInterceptor) => {
    const skillBuilder = Alexa.SkillBuilders.custom();
    const persistenceAdapter = new PersistenceAdapterClass({
        tableName: `${SKILL_INTERNAL_NAME}_state`,
        createTable: true
    });
    const skill = skillBuilder
        .addRequestHandlers(
            ExitHandler,
            HelpHandler,
            LaunchRequestHandler,
            SessionEndedRequestHandler,
            StarteSpielIntentHandler,
            WieVieleSpielerIntentHandler
        )
        .withPersistenceAdapter(persistenceAdapter)
        .addErrorHandlers(ErrorHandler);
    if (requestInterceptor) {
        skill.addRequestInterceptors(requestInterceptor);
    }
 
    return skill.lambda();
};
```

</div><p>Die Methode bekommt nun einen weiteren Parameter: <code>PersistenceAdapterClass</code>. Wir übergeben also eine Klasse, die einen PersistenceAdapter implementiert. Diese Klasse wird dann in createSkill instanziert (wobei der Name der Tabelle in der DynamoDB festgelegt wird) und mit <code>withPersistenceAdapter</code> an den SkillBuilder gegeben.<br /> Um die withPersistenceAdapter-Methode des SkillBuilders nutzen zu können, mussten wir den Skill Builder (am Anfang der Methode) auf einen custom SkillBuilder umstellen.<br /> In der index.js übergeben wir als Parameter für die PersistenceAdapaterClass nun den DynamoDB-Adapter:</p><div>

```javascript
import {createSkill} from './createSkill';
import {DynamoDbPersistenceAdapter} from 'ask-sdk-dynamodb-persistence-adapter';
 
export const handler = createSkill(DynamoDbPersistenceAdapter);
```

</div><h3>Konfiguration des Skills für die Nutzung unseres eigenen PersistenceAdapaters im Test</h3><p>Im Test übergeben wir als Parameter für die PersistenceAdapaterClass unsere eingene Implementierung:</p><div>

```javascript
function createSkillForTest(world) {
    class MockPersistenceAdapterClass {
        getAttributes: () => Promise;
        saveAttributes: () => Promise;
        attributes: any;
 
        constructor() {
            this.getAttributes = () => Promise.resolve(world.persistentAttributes);
            this.saveAttributes = (_, attributes) => {
                world.persistentAttributes = attributes;
                return Promise.resolve();
            };
        }
    }
    const requestInterceptor: RequestInterceptor = {
        process(handlerInput: HandlerInput) {
            // Wrap setSessionAttributes, so that we can save these Attributes in the test
            const orginalSetSessionAttributes = handlerInput.attributesManager.setSessionAttributes;
            handlerInput.attributesManager.setSessionAttributes = (attributes: Attributes) => {
                world.sessionAttributes = attributes;
                orginalSetSessionAttributes.call(handlerInput.attributesManager, attributes);
            }
        }
    };
    return createSkill(MockPersistenceAdapterClass, requestInterceptor)
}
```

</div><p>Ähnlich wie für die SessionAttributes speichern wir auch die PersistentAttributes im globalen World-Objekt. Dort werden sie auch aktualisiert, wenn der Skill diese mit saveAttributes speichert.</p><h2>Fazit</h2><p>Mit diesem Setup haben wir nun eine schöne Grundlage für Akzeptanztest-getriebene Entwicklung von Alexa-Skills gelegt. Den vollständigen Source-Code findet ihr auf Gitlab. Der Stand für diesen Blogpost ist getagged unter: https://gitlab.com/spittank/fuenferpasch/tree/BlogPart5_AttributeHandling.</p><p>Im Repo sind auch noch weitere cucumber-Steps implementiert, z.B. zur Überprüfung von Bildschirmausgaben für Echos mit Display, oder zur Dialogsteuerung, wenn ein Nutzer einen Intent ohne einen erforderlichen Wert für einen Slot aufruft.</p><p>Lasst mir gerne Feedback hier, wenn ihr eigene / weitere Anwendungsfälle für die Skillentwicklung habt.</p>

BDD für Alexa Skills – Teil 5: cucumber.js Tests und State-Handling

<p>Dies ist der vierte Teil einer Serie von Blogeinträgen über die Entwicklung eines Alexa Skills. Diesmal beschäftigen wir uns mit der Entwicklung von automatisierten Akzeptanztests für unseren Skill unter Einsatz von cucumber.js, also Behaviour Driven Development (BDD) für einen Alexa Skill.</p><h2>Was bisher geschah</h2><ul><li><a href="https://blog.codecentric.de/2019/02/bdd-alexa-skills-teil1/">Teil 1: Initiales Setup</a> </li><li><a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-2/">Teil 2: Lokale Lambda Entwicklung</a> </li><li><a href="https://blog.codecentric.de/2019/02/alexa-skills-bdd-cucumber-3/">Teil 3: Unit Testing mit Jest</a> </li></ul><p>In den ersten drei Beiträgen dieser Artikelserie haben wir einen Alexa Skill aufgesetzt. Schritt für Schritt wurde die Lambda-Entwicklung für diesen Skill um Linting, ein Typsystem und schließlich Unit-Tests mit Jest erweitert.</p><h2>Aufbau eines Tests in cucumber.js</h2><p>cucumber.js ist die JavaScript-Portierung von cucumber, einem Framework zur Ausführung von automatisierten (Akzeptanz-) Tests (wer sich für die Historie von cucumber interessiert kann hier mehr <a href="https://blog.codecentric.de/2013/08/cucumber-setup-grundlagen/" target="_blank">in einem Artikel von 2013 auf dem codecentric Blog</a>  lernen).</p><p>Cucumber erlaubt es uns, Testszenarien als Text zu definieren, die einer gewissen Struktur gehorchen müssen.<br /> Ein Testszenario wird eingeleitet mit dem Schlüsselwort <code>Szenario:</code> gefolgt von einem Namen für den Test.</p><p>Der Testablauf wird dann mit Schlüsselwörten versehen:</p><ul><li><code>Angenommen</code>: Definiert einen Ausgangszustand für den Test, z.B. dass der Skill bereits gestartet ist. Wenn unser Skill von der Tageszeit abhängig ist, könnten wir hier z. B. schreiben „Angenommen es ist sieben Uhr morgens“.</li><li><code>Wenn</code>: Gibt einen Schritt an, der in dem Test ausgeführt werden soll.</li><li><code>Dann</code>: Beschreibt unsere Erwartung, was durch den Test passieren soll.</li></ul><p>Ziel ist es, den Test für unseren Alexa Skill so zu schreiben, als würden wir einen Dialog mit Alexa führen. Dies könnte in unserem Würfelspiel vielleicht so aussehen:</p>

```
 
Szenario: Würfel mit n Würfeln. Alexa erfragt die Anzahl, wenn der Anwender diese initial nicht nennt
Angenommen der Zufallsgenerator generiert eine Sequenz 2,5,3,2,3
Und der Anwender hat den Skill gestartet
Wenn der Anwender sagt: Bitte würfeln
Dann fragt Alexa: Mit wie vielen Würfeln möchtest du würfeln?
Wenn der Anwender die Frage mit 5 beantwortet
Dann sagt Alexa: Okay. Du hast zweimal eine 2, zweimal eine 3 und eine 5 gewürfelt

```

<p> </p><p>Jeden der Angenommen-, Wenn- und Dann-Schritte müssen wir erst implementieren, damit cucumber weiß was dafür zu tun ist. Wir könnten nun einen speziellen Schritt <code>Wenn der Anwender sagt: Bitte würfeln</code> implementieren und dann einen neuen „Würfel Intent“ aufrufen. Aber schöner wäre es, wenn wir nur wenige generischen Schritte implementieren würden, wie z.B.:</p><p><code>Wenn der Anwender sagt: utterance</code><br /> <code>Dann sagt Alexa: Antwort</code></p><h2>Der (Mock) Voice Service</h2><p>Um generische Steps für den Aufruf unseres Skill aus einem cucumber-Test zu entwerfen, schauen wir noch einmal auf das Diagramm aus dem ersten Blogpost dieser Serie. Dieses Diagramm hilft uns, zu verstehen wie unser Skill von Alexa ausgeführt wird:<br /> <a href="https://blog.codecentric.de/2022/01/bdd-alexa-skills-teil1/voice-interaction-model-to-lambda/"><img loading="lazy" src="https://media.graphassets.com/sr7NepUWSHe2ejg1YaTQ" alt="Schematischer Ablauf des Aufrufs eines Alexa Skills im produktiven Fall" width="700" height="321" /></a> </p><p>Der Anwender sagt einen Befehl zu seinem Echo-Gerät. Dieser Sprachbefehl wird in die Cloud übertragen und vom Alexa Voice Service verarbeitet.</p><p>Der Voice Service nutzt unser Voice Interaction Model um zu prüfen, ob die Spracheingabe des Nutzers zu einem unserer da definierten Intents passt. Wenn ja, baut der Voice-Service einen intentRequest mit dem aufzurufenden Intent und ggf. vorhandenen Slot-Werten zusammen und ruft damit unseren Skill auf. Der Skill prüft welcher Handler für den Intent in der <code>canHandle</code> Methode <code>true</code> zurückgibt und ruft dann den passenden Handler auf.</p><p>Für unseren Akzeptanztest müssen wir also die Rolle des Voice Service selbst übernehmen und diesen durch einen speziellen Mock Voice Service ersetzen:</p><p><a href="https://blog.codecentric.de/2019/03/alexa-skills-bdd-cucumber-4/mock-voice-service/"><img loading="lazy" src="https://media.graphassets.com/3WmjBKn7TM2SvIXVxbl0" alt="Schematischer Ablauf des Aufrufs eines Alexa Skill bei der Ausführung eines Akzeptanztests mit cucumber.js" width="700" height="390" /></a> </p><p>Um dies tun zu können brauchen wir lokal Zugriff auf unser definiertes Voice Interaction Model. Dieses finden wir in der <a href="https://developer.amazon.com/alexa/console/ask" target="_blank">Alexa Developer Console</a> . Von dort navigieren wir zu unserem Skill und können dann über die Navigation links den JSON Editor aufrufen:</p><p><a href="https://blog.codecentric.de/2019/03/alexa-skills-bdd-cucumber-4/skill-interaction-model-json-editor/"><img loading="lazy" src="https://media.graphassets.com/3Rf5pXzRQ52ykafaGI2N" alt="Screenshot: Der JSON Editor unseres Voice Interaction Model" width="700" height="386" /></a> </p><p>Wir kopieren uns den Inhalt und legen mit diesem eine neue Datei namens „interactionModel.json“ im Verzeichnis /VoiceUI an (Anmerkung: neben der aws-cli die wir zur Aktualisierung der Lambda nutzen, existiert ein eigenes <a href="https://developer.amazon.com/de/docs/smapi/quick-start-alexa-skills-kit-command-line-interface.html" target="_blank">Commandline Interface für Alexa Skills</a> , das hier vielleicht hilfreich wäre. Dieses habe ich aber noch nicht ausprobiert).</p><p>Momentan haben wir in unserem Voice Interaction Model nur einen einzigen neuen Intent angelegt. Dieser Intent (starteSpiel) kann nur durch einen einzigen Satz aufgerufen werden, mit einer Variablen (einem Slot) für die Anzahl an Spielern.</p><p>Für die bessere Veranschaulichung erweitern wir unseren Intent nun um einen weiteren Slot. Wir ersetzen das Wort Mitspielern durch einen Slot {Spielern} mit möglichen Werten einem eigenen Slot-Typ {SpielernSlot} mit den möglichen Werten: Mitspielern und Spielern (um dem Anwender etwas mehr Freiheiten in der Formulierung zu gestatten).</p><p>Unser verändertes Voice Interaction Model sieht somit so aus:</p><div>

```javascript
{
    "interactionModel": {
        "languageModel": {
            "invocationName": "fünferpasch",
            "intents": [
                {
                    "name": "AMAZON.FallbackIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.CancelIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.HelpIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StopIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.NavigateHomeIntent",
                    "samples": []
                },
                {
                    "name": "starteSpiel",
                    "slots": [
                        {
                            "name": "spieleranzahl",
                            "type": "AMAZON.NUMBER"
                        },
                        {
                            "name": "spielern",
                            "type": "SpielernSlot"
                        }
                    ],
                    "samples": [
                        "Starte ein Spiel mit {spieleranzahl} {spielern}"
                    ]
                }
            ],
            "types": [
                {
                    "name": "SpielernSlot",
                    "values": [
                        {
                            "name": {
                                "value": "Mitspielern"
                            }
                        },
                        {
                            "name": {
                                "value": "Spielern"
                            }
                        }
                    ]
                }
            ]
        }
    }
}
```

</div><p>Es gibt also einige Standard-Intents, plus den <code>starteSpiel</code> Intent, mit den zwei Slots:</p><ul><li><code>spieleranzahl</code> vom Typ <code>AMAZON.number</code></li><li><code>spielern</code> vom Typ <code>SpielernSlot</code></li></ul><p>Der SlotTyp <code>SpielernSlot</code> ist ein benutzerdefinierter Slot-Typ, der durch die möglichen Werte Spielern und Mitspielern ersetzt werden kann. Wir nutzen den Slot-Typ hier also nur, um die Anzahl an verschiedenen Utterances zu reduzieren und gleichzeitig dem Anwender verschiedene Formulierungen zu erlauben. Der Hauptunterschied ist hier, dass der Slot <code>spieleranzahl</code> später von uns weiter verwendet wird, während es uns egal ist, ob der Anwender unseren Skill mit „Spielern“ oder „Mitspielern“ adressiert hat.</p><h3>Ein generischer <code>Wenn der Anwender sagt</code> Step für cucumber.js</h3><p>Mit unserem Mock Voice Service wollen wir einen generischen Step für die Verarbeitung einer Spracheingabe eines Nutzers anbieten. Wir müssen also zu der Spracheingabe den passenden Intent ermitteln und unsere Lambda-Funktion mit einem entsprechenden Intent-Request aufrufen.</p><p>Um diesen Intent zu ermitteln, liest unser Mock Voice Service das lokal gespeicherte Voice Interaction Model und speichert sich zu jedem möglichen Intent jede mögliche Utterance. Um diese Utterances im Test auf die Spracheingabe des Nutzers zu matchen, übersetzen wir jede Utterance in eine Regular Expression. In der erzeugten Regular Expression ersetzen wir die Slot-Werte durch die für den passenden Slot-Type gültigen Eingaben. Das klingt komplizierter als es wirklich ist. Machen wir es konkreter an unserem obigen Beispiel:</p><p>Die Utterance:<br /> <code>"Starte ein Spiel mit {spieleranzahl} {spielern}"</code></p><p>wird eingelesen. Anhand der geschweiften Klammer erkennen wir zwei Slots. Über die Slot-Typen ersetzen wir diese Slots nun durch eine Regular Expression zu:</p><p><code>"^Starte ein Spiel mit (.*) (Spielern|Mitspielern)$"</code></p><p>Mit dem „<code>^</code>“ und „<code>$</code>“ Zeichen legen wir fest, dass unsere Regular Expression nur matchen soll, wenn die Spracheingabe genau mit dem ersten Wort anfängt und dem letzten Wort aufhört, dadurch schließen wir für unseren Test Teilmatches aus.</p><p>Die Slot-Werte aus der Utterance haben wir in der Regular Expression durch Gruppen (gekennzeichnet durch die runden Klammern) ersetzt:</p><ul><li>Vordefinierte Slot-Types (erkennbar daran, dass der Typ mit „AMAZON.“ anfängt, ersetzen wir momentan durch (.*) was auf beliebige Eingaben matched (Für AMAZON.number könnten wir später noch spezifischer werden).</li><li>Benutzerdefinierte Slot-Types ersetzen wir durch eine Oder-verkettete Liste aller für den Slot-Typ gültigen Eingaben. Im Beispiel sind das „Spielern“ und „Mitspielern“.</li></ul><p>Im Test müssen wir dann nur noch die Spracheingabe aus dem Test gegen alle erzeugten Regular Expressions testen. Haben wir einen Match, kennen wir auch den aufzurufenden Intent und über die Gruppen in der Regular Expression ermitteln wir die Werte zu den ermittelten Slots.</p><p>Mit diesen Informationen können wir uns dann einen IntentRequest zusammenbauen. Hierfür nutzen wir einige Template-Requests, die wir im Projekt als JSON-Dateien ablegen und mit dem aufzurufenden Intent und den Slot-Informationen aktualisieren.</p><p>Die Implementierung unseres „Wenn der Anwender sagt“ cucumber Steps ist:</p><div>

```javascript
When(/^der Anwender sagt[:]? (.*)$/, async function (utterance) {
    const allUtterances = getAllUtterances();
 
    const matchingIntent: ?IntentInvocation = findMatchingIntent(allUtterances, utterance);
 
    expect(allUtterances).toHaveMatchingIntentFor(utterance);
    if (!matchingIntent) return;
 
    const slots = matchingIntent && matchingIntent.slots.reduce((acc, cur: Slot) => ({
        ...acc,
        [cur.name]: {
            name: [cur.name],
            value: cur.value,
            confirmationStatus: 'NONE',
            source: 'USER'
        }
    }), {});
 
    const json = fs.readFileSync('features/support/mockVoiceService/requestJsonTemplates/intentRequest.json', 'utf-8');
    const intentRequest = JSON.parse(json);
 
    intentRequest.request.intent.name = matchingIntent.intentName;
    intentRequest.request.intent.slots = slots;
 
    this.lastRequest = intentRequest;
 
    await executeRequest(this, this.skill, intentRequest);
});
```

</div><p>Zuerst holen wir uns mit <code>getAllUtterances</code> wie oben beschrieben Regular Expressions (und die dazugehörigen Intents) für alle Utterances in unserem Voice Interaction Model.</p><p><code>findMatchingIntent</code> ermittelt dann den aufzurufenden Intent und die zu setzenden Werte für alle eventuell vorhandenen Slots.</p><p><code>expect(allUtterances).toHaveMatchingIntentFor(utterance);</code> prüft, dass wir auch wirklich einen Intent gefunden haben (sonst wäre der Test schon hier fehlgeschlagen). Der matcher <code>toHaveMatchingIntentFor</code> ist ein Custom-Matcher, implementiert in der Datei expectations.js. Dadurch werden besser lesbare Fehlermeldungen in den Tests ermöglicht.</p><p>Die folgende Reduce-Anweisung dient dazu, alle ermittelten Slot-Werte aus einem Array in Form eines Dictionary-Objekts für den Skill zusammenzubauen.</p><p>Abschließend wird der Request zusammengebaut und mit <code>executeRequest</code> ausgeführt.</p><h3>Überprüfung der Antwort des Skills</h3><p>Mit dem nun definierten Step können wir aus einem cucumber-Test heraus einen Intent in unserem Skill aufrufen. Um zu überprüfen, ob der Aufruf erfolgreich war, müssen wir aber auch die Antwort überprüfen. Schauen wir hierzu zunächst auf die Methode <code>executeRequest</code> (die in Gitlab abgelegte Version ist geringfügig komplexer, da sie sich auch um die Weitergabe des Session-States zwischen verschiedenen Aufrufen kümmert):</p><div>

```javascript
async function executeRequest(world, skill, request) {
    return new Promise((resolve) => {
        // Add session Attributes to requests
        skill(request, {}, (error, result) => {
            world.lastError = error;
            world.lastResult = result;
            // Store session attributes from response for future requests
            resolve();
        });
    });
}
```

</div><p>Die <code>executeRequest</code> Methode ist als Promise definiert. Der Promise wird resolved, sobald wir eine Antwort von unserem Skill bekommen haben. Unser Skill wird mit dem zusammengebauten Request aufgerufen und bekommt als dritten Parameter eine Callback-Funktion. Diese Callback-Funktion wird aufgerufen, wenn unser Skill den Request verarbeitet hat. Je nach Erfolg ist dann entweder der Parameter <code>error</code> oder der Parameter <code>result</code> gesetzt. Beide Parameter speichern wir uns im globalen World-Objekt von Cucumber (dort ist der aktuelle Zustand des Tests gespeichert) und können den Promise resolven.</p><p>Mit dieser Information wird dann die Implementierung eines Steps zur Überprüfung der Antwort eines Skills ganz einfach:</p><div>

```javascript
Then(/^antwortet Alexa mit[:]? (.*)$/, function (expectedResponse) {
    expect(this.lastResult.response.outputSpeech.ssml).toEqual(`${expectedResponse}`);
});
```

</div><p>Jeder implementierte Step in cucumber.js erhält über <code>this</code> Zugriff auf das globale world-Objekt (Achtung: deswegen dürfen cucumber-Steps nie mit arrow-functions implementiert werden, da mit arrow-functions das Verhalten des this-Keywords geändert wird). Also haben wir über <code>this.lastResult</code> direkt Zugriff auf das letzte Ergebnis unseres Lambda-Aufrufs. Wenn wir von unserem Skill (wie in diesem Fall) eine Sprachausgabe erwarten, muss diese im outputSpeech-Attribut der Response stehen.</p><p>Den aktuellen Stand des Skills<a href="https://gitlab.com/spittank/fuenferpasch/tree/BlogPart4_BDD" target="_blank"> findet ihr hier auf Gitlab</a> .</p><h2>Ausblick</h2><p>Wir haben nun ein erstes Setup um Akzeptanztests für unseren Alexa Skill in cucumber.js zu formulieren. Mit dieser Technik lassen sich auch weitere Annahmen an die Skill-Antwort formulieren, z.B. dass der Skill Berechtigungen vom Anwender erfragt oder einen Text auf einem eventuell vorhandenen Bildschirm ausgibt.</p><p>Auch die Behandlung von Attributen für die Zwischenspeicherung von Werten haben wir noch nicht berücksichtigt. Alexa Skills können bestimmte Werte für die Lebensdauer eines Requests, einer Session oder persistent (zwischen-)speichern. Damit sollte auch unser Testing-Framework umgehen können. Dies wird Bestandteil <a href="https://blog.codecentric.de/2019/03/alexa-skills-bdd-cucumber-5/">des nächsten Artikels dieser Blogserie sein</a> .</p><p> </p>

BDD für Alexa Skills – Teil 4 Akzeptanztests mit cucumber.js

<p>Voice User Interfaces stellen neue Herausforderungen an alle, die sich für Benutzerinteraktionen verantwortlich fühlen. Während grafische Benutzerschnittstellen uns schon eine ganze Zeit begleiten und wir auf etablierte Entwurfsmuster, Prozesse und Werkzeuge zurückgreifen können, müssen diese für Benutzerinteraktionen mit Sprachinterfaces erst noch entstehen. Exemplarisch habe ich mir angesehen, was heute bei der Umsetzung eines Voice UIs in einem Alexa Skill möglich ist und wo konzeptionelle Herausforderungen liegen.</p><p>In einer <a href="https://blog.codecentric.de/2019/02/bdd-alexa-skills-teil1/">Serie von Blogposts</a>  habe ich mich bereits aus technischer Sicht mit einigen Aspekten der Entwicklung eines Alexa Skills auseinandergesetzt. Dieser Beitrag ist keine Fortsetzung dieser Serie. Stattdessen werde ich mich hier rein auf den Aspekt des Sprachinterfaces und der User Experience mit einem Skill beschränken. Die technischen Artikel sind keine Voraussetzung für diesen Artikel, aus diesem Grund lassen sich einige Überschneidungen nicht ganz verhindern.</p><h2>Hauptzutaten eines Skills</h2><p>Ein Skill besteht aus zwei wesentlichen Hauptbestandteilen:</p><ol><li>Dem <code>Voice Interaction Model</code>, welches die User-Interface-Schicht unseres Skill bildet</li><li>und einem <code>Service</code>, der die Logik beinhaltet, Benutzereingaben entgegennimmt und eine Antwort erzeugt (üblicherweise eine Sprachantwort).</li></ol><p><img width="700" height="320" src="https://media.graphassets.com/EO9UOuHeQq6JCTSYYGI1" alt="Schematischer Ablauf der Skillverarbeitung" /></p><p>Spricht der Anwender mit dem Skill, wird (durch den Alexa Voice Service) anhand des Voice Interaction Models ermittelt, ob die Spracheingabe verarbeitet werden kann. Wenn dies der Fall ist, wird der Service mit den notwendigen Informationen aufgerufen und anschließend die erzeugte Antwort zurück an das Echo-Gerät geschickt, welches es dem Anwender ausgibt.</p><p>Schauen wir uns das Voice Interaction Model einmal etwas genauer an:</p><h2>Das Voice Interaction Model</h2><p>Die Grundlage der Interaktion eines Nutzers mit einem Alexa Skill ist das Voice Interaction Model. Darin ist festgelegt, auf welche Spracheingaben unser Skill reagiert. Das Modell besteht aus folgenden Hauptelementen:</p><ul><li>Dem <strong>Invocation Name</strong>: Ein Dialog zwischen dem Nutzer und unserem Skill muss immer durch den Nutzer initiiert werden, indem er den Skill über einen Sprachbefehl startet. Wie sich der Skill starten lässt, ist durch den Invocation Name festgelegt.</li><li>Den <strong>Intents</strong>: Intents sind mögliche Sprachbefehle, die unser Skill verarbeiten kann.<ul><li>Für jeden Intent muss mindestens eine <strong>Utterance</strong> festgelegt werden. Eine Utterance ist eine konkrete Phrase, die der Benutzer sagen kann um den Intent auszulösen.</li><li>Intents sind nicht rein statisch, sondern können variable Anteile beinhalten, die sogenannten Slots. Welche Werte die Slots annehmen können, wird in Slot-Types definiert.</li></ul></li></ul><li>Neben den benutzerdefinierten Intents existieren auch vordefinierte Intents. Unter anderem sind dies solche, die durch den Lebenszyklus des Skills ausgelöst werden. Der <code>LaunchIntent</code> wird zum Beispiel aufgerufen, wenn der Skill gestartet wird.</li><li>Den <strong>Slot-Typen</strong>: diese definieren, welche Werte ein Slot in einem Intent annehmen kann. Es existieren vordefinierte Slot-Typen wie z.B. <code>AMAZON.number</code> (welcher nur Zahlen als Eingaben ermöglicht), oder wir können unsere eigenen Slot-Typen definieren. Dabei geben wir eine Liste an möglichen Werten an, die wir für den Slot-Typ akzeptieren wollen.</li><h2>Ein Beispiel-Dialog</h2><p>Das Zusammenspiel dieser Elemente wird verständlicher, wenn wir uns ein Beispiel ansehen. Nehmen wir an, wir hätten einen Skill für ein Würfelspiel. In diesem Skill haben wir einen Intent um ein neues Spiel zu starten, den <code>starteSpiel</code> Intent. Dieser Intent hat einen möglichen Slot mit dem Namen <code>anzahlSpieler</code>, der definiert, mit wie vielen Spielern der Anwender ein neues Spiel starten möchte. Der Slot <code>anzahlSpieler</code> hat den Typ <code>AMAZON.number</code>, d.h. nur Zahlen werden als gültige Werte erkannt. Der Intent kann über die Utterance <code>Starte eine Spiel mit {anzahlSpieler} Spielern</code> ausgelöst werden, wobei der Slot über die geschweiften Klammern gekennzeichnet wird.</p><p><img loading="lazy" width="700" height="596" src="https://media.graphassets.com/pzJCsYFTg2Uerm4dZBs4" alt="Dialogablauf in einem Alexa Skill bei erkannter Utterance" /></p><p>Wird keine Utterance erkannt, bekommt unser Skill die Chance, eine generische Antwort in einem Fallback Intent zu erzeugen:</p><p><img loading="lazy" width="700" height="323" src="https://media.graphassets.com/9rHFEAg7SNaYqAXJqvfk" alt="Antwort des Fallback Intent, wenn keine Utterance erkannt wird" /></p><h2>Lessons Learned</h2><p>Nachdem wir den grundsätzlichen Aufbau eines Skills verstanden haben, werfen wir nun einen Blick darauf, was wir aus Sicht der User Experience lernen können.</p><p>Die Nutzungserfahrung mit einem smarten Assistenten ist durch vielerlei Dinge geprägt. Manche davon können wir beeinflussen, manche hingegen nicht. Zwei Hauptaspekte aber sind:</p><ul><li>Wie gut funktioniert die Spracherkennung? Also wird meine Stimme, mein Akzent erkannt <a href="https://www.youtube.com/watch?v=J3lYLphzAnw" target="_blank">und in den richtigen Befehl übersetzt</a> ?</li><li>Erkennt der Assistent meine Intention? Auch wenn die Spracherkennung funktioniert, ist längst nicht sichergestellt, dass auch meine Absicht sicher erkannt wird</li></ul><p>Die Spracherkennung können wir nicht beeinflussen. Hier sind wir allein auf die Arbeit von Amazon angewiesen. Wir können aber viel dazu beitragen, dass die Intention des Benutzers richtig erkannt wird. Umgekehrt kann man hier aber auch viel falsch machen.</p><h3>Welche Spracheingaben erlauben wir?</h3><p>Wie Anwender mit Sprachassistenten interagieren ist sehr unterschiedlich. Je nach Alter, kulturellem Hintergrund, technischer Sozialisierung oder Bildung erfolgt die Ansprache mal sehr formal, mal weniger formal, höflicher oder befehlsorientierter, knapp oder ausführlich.</p><p>Es reicht also nicht, wenn wir als Experten uns einige Utterances überlegen, wir müssen früh unsere Anwender miteinbeziehen. Wenn wir wirklich wissen wollen, was Nutzer zu einem Sprachassistenten sagen, gibt es kaum eine bessere Methode als dies zu testen. Mit <a href="https://uxfactor.wordpress.com/2018/11/27/voice-usability-testing-with-wizard-of-oz-lessons-learned/" target="_blank">„Wizard-of-Oz“ Testing</a>  können wir dies schon, bevor wir auch nur eine Zeile Code geschrieben haben.</p><p>Erstaunlich war für mich, wie wenig smart unser Skill dabei behandelt wird. Sicherlich ist die Leistung von Amazon mit Alexa sehr beachtlich und im Hintergrund findet bestimmt auch viel Künstliche-Intelligenz-Magie statt. Aber bezogen auf unseren Skill ist es eher so: Entweder trifft ein Anwender eine unserer hinterlegten Phrasen (Utterances) oder die Eingabe wird nicht erkannt. Eine smarte Interpretation von alternativen Formulierungen konnte ich zumindest nicht feststellen (eventuell kommt das aber auch noch).</p><h4>Anfragen in einer Session vs. Direktanfragen</h4><p>Benutzer können einen Skill erst öffnen und dann eine Frage stellen oder als “one shot” einen Skill direkt mit einer Frage öffnen. Dies resultiert in unterschiedlichen Aufrufen, die sich im Wesentlichen über die veränderte Grammatik unterscheiden:</p><p><img loading="lazy" width="700" height="561" src="https://media.graphassets.com/CL26KcO2QsiU94QAblic" alt="Abfrage in einer Session vs. direkter Aufruf mit Anfrage" /></p><p>In ersten Fall müssen wir eine Utterance “Wie viele Mitspieler gibt es?” unterstützen, im zweiten Fall “wie viele Mitspieler es gibt”. Beide Utterances müssen aber explizit vom Skill-Entwickler angegeben werden, obwohl man annehmen könnte, dass ein Algorithmus erkennt, dass hinter beiden Fragen die gleiche Intention steckt.</p><p>Wir müssen also für jede mögliche Utterance die wir für einen Intent unterstützen wollen prüfen, ob sie auch als Direktanfrage denkbar ist und dann ggf. beide Varianten unterstützen.</p><h4>Alternative Formulierungen</h4><p>Um Utterances für unseren Skill zu formulieren, machen wir also Tests mit Anwendern und berücksichtigen die verschiedenen Arten, wie Alexa angesprochen werden kann. Daraus ergibt sich schnell eine sehr große Anzahl an unterschiedlichen Utterances. Hier können zusätzliche Slots helfen. Im Beispiel mit der Anzahl an Mitspielern haben wir einen Slot verwendet, um eine Variable in unserem Intent-Aufruf zu haben (die Anzahl an Mitspielern). Wir können Slots aber auch verwenden, um unterschiedliche synonyme Formulierungen zu unterstützen.</p><p>Auch hier wieder ein Beispiel:</p><p>Der <code>starteSpiel</code> Intent kann momentan über „Starte ein Spiel mit {<code>anzahlSpieler</code>} Spielern“ aufgerufen werden. Manche Anwender sagen aber nicht „Spieler“ sondern „Mitspieler“. Andere wollen das Spiel nicht „starten“ sondern „beginnen“. Also sind wir bereits bei vier Utterances:</p><ul><li>„Starte ein Spiel mit {<code>anzahlSpieler</code>} Spielern“</li><li>„Beginne ein Spiel mit {<code>anzahlSpieler</code>} Spielern“</li><li>„Starte ein Spiel mit {<code>anzahlSpieler</code>} Mitspielern“</li><li>„Beginne ein Spiel mit {<code>anzahlSpieler</code>} Mitspielern“</li></ul><p>Dies können wir durch zusätzliche Slots wieder reduzieren. Wir führen zwei neue Slots ein: <code>starte</code> mit den möglichen Werten „Starte“ und „Beginne“ und <code>spielern</code> mit den möglichen Werten „Spielern“ und „Mitspielern“. Mit dieser Änderung haben wir wieder nur eine Utterance, die wie folgt aussieht:</p><p>„{<code>starte</code>} ein Spiel mit {<code>anzahlSpieler</code>} {<code>spielern</code>}“</p><p>Auf diese Utterance passen nun alle oben definierten Phrasen, unser Interaction Model bleibt aber übersichtlicher.</p><h4>Konflikte in Utterances</h4><p>Mit einer steigenden Anzahl von unterschiedlichen Utterances steigt aber auch die Gefahr von Konflikten. Ein Beispiel: Nehmen wir an, wir würden einen Skill schreiben, mit dem ein Anwender Dinge einkaufen kann. Mögliche Befehle wären:</p><ol><li>„Ich will {Produkt} kaufen“ und Alexa würde dann fragen wie viel von dem Produkt gekauft werden soll</li><li>„Ich will {Anzahl} {Einheit} {Produkt} kaufen“, um z. B. „zwei Packungen Milch“ zu kaufen“</li><li>„Ich will weniger kaufen“, wenn Alexa eine Mengenangabe falsch verstanden hat und man dies korrigieren möchte</li></ol><p>In diesem Fall kann Alexa den Befehl „Ich will weniger kaufen“ nicht eindeutig zuordnen. Ist der dritte Intent gemeint oder will der Anwender ein Produkt mit dem Namen „weniger“ kaufen?</p><p><img loading="lazy" width="700" height="323" src="https://media.graphassets.com/I5FqoHozSCGj9EtcEA4x" alt="Falsche Zuordnung der Benutzeranfrage weil diese nicht eindeutig einer Utterance zugeordnet werden kann" /></p><p>In diesem Beispiel sieht man das Problem noch recht schnell, bei vielen Intents und Utterances geht so etwas aber schnell unter. Hier helfen <a href="https://blog.codecentric.de/2019/03/alexa-skills-bdd-cucumber-4/" target="_blank">automatisierte Akzeptanztests</a> .</p><h3>Session-Verwaltung</h3><p>Neben der Arbeit an der Formulierung, wie Anwender einen Skill ansprechen, war die Behandlung von Zustandsinformationen in einer Alexa Session ein weiteres großes Learning für mich.</p><p>Bleiben wir beim initial vorgestellten Skill für ein Würfelspiel. Wenn ich ein neues Spiel für fünf Mitspieler starte, erwarte ich als Anwender, dass sich Alexa diese Information merkt und nun fünf Spieler würfeln lässt. Zu diesem Zweck bietet Amazon dem Skill-Entwickler Möglichkeiten, Statusinformationen für die Dauer einer Session abzuspeichern.</p><h4>Was ist eine Alexa-Session</h4><p>Aber was genau ist denn eine Session aus Sicht eines Alexa Skills? (Leser der technischen Artikelserie kennen diesen Abschnitt bereits)</p><ul><li>Eine Session beginnt in dem Moment, in dem der Nutzer den Skill startet.</li><li>Eine Session endet, wenn:<ul><li>der Benutzer die Session explizit beendet (z.B. mit „Alexa, stopp“).</li><li>der Benutzer nach der letzten Antwort von Alexa nicht innerhalb von acht Sekunden wieder mit dem Skill interagiert.</li><li>Diese Zeit können wir einmal verlängern, indem wir eine erneute Nachfrage einbauen, die ausgegeben wird wenn der Anwender innerhalb der ersten acht Sekunden nicht antwortet. Kommt innerhalb von (erneuten) acht Sekunden dann wieder keine Antwort, wird der Skill beendet.</li></ul></li></ul><p>Eine Session ist also potentiell recht kurz. Gerade bei komplexeren Interaktionen ist bei einem Skill heute die Gefahr noch recht hoch, dass eine Session beendet wird, weil nicht rechtzeitig geantwortet wird, die eigentliche Intention des Anwenders aber nicht vollendet wurde. Dies ist aus meiner Sicht auch mit einer der Gründe, warum ein großer Teil der verfügbaren Skills heute auf sehr einfache Interaktionen beschränkt ist. Oft sind es einfache kurze Befehle, die von Alexa kurz bearbeitet und beantwortet werden (One-Shot-Interaktionen). Von einem echten Dialog zwischen Alexa und Anwender kann oft keine Rede sein.</p><h4>Ein eigenes Session-Konzept</h4><p>Wer trotzdem komplexere Interaktionen realisieren will, sollte sich dieser Herausforderung bewußt sein und eigene Lösungsstrategien erarbeiten. Das kann z.B. bedeuten, dass man sich für seinen Skill ein eigenes Session-Konzept überlegt, das eng an die Aufgabe geknüpft ist, die der Anwender bearbeitet.</p><p>Was wir nicht verhindern können, ist, dass der Skill sich beendet wenn der Anwender nicht kontinuierlich mit ihm interagiert. Aber wir können dem Anwender den Wiedereinstieg so einfach wie möglich machen, indem wir den Skill darauf auslegen, direkt am letzten bekannten Punkt wieder aufzusetzen. Dies ist sicherlich noch keine ideale Lösung, aber wir sind dadurch eingeschränkt, was technisch heute möglich ist. Aber der Trend <a href="https://www.slideshare.net/adobe/adi-state-of-voice-assistants-113779956" target="_blank">scheint zu komplexeren Interaktionen</a>  zu gehen, also wird Amazon hier sicher nachbessern.</p><p>Technisch bedeutet dies, dass man sich von der Alexa-Session entkoppelt. Man kann den Status also nicht mehr im dafür vorgesehenen Session-State halten, sondern muss diesen über die Grenzen einer Alexa-Session hinweg speichern. Dadurch stellt sich aber die Frage: wann endet diese selbst definierte Session? Und wie erkenne ich das um den Session-State zu bereinigen?</p><h3>Gesprächskontext</h3><p>Im obigen Beispiel merken wir uns für eine Session, wie viele Mitspieler das aktuelle Würfelspiel hat. Dies ist naheliegend, sonst würde unser Skill nicht sinnvoll funktionieren. Wir wollen aber auch, dass sich ein Dialog mit unserem Skill natürlich anfühlt. Dafür brauchen wir aber noch mehr Gesprächskontext.</p><p>In unserem Würfelspiel-Skill könnte ich den Skill fragen: „Wie viele Fünfen habe ich gewürfelt?“. Wenn ich nun drei Fünfen gewürfelt habe, aber nur zwei dieser Würfel behalten möchte, wäre ein natürlicher Dialog:</p><p><img loading="lazy" width="700" height="414" src="https://media.graphassets.com/AwR7TJTSYWs9GplD5avP" alt="Fehlender Kontext im Dialog mit Alexa. Worauf bezieht sich meine Anfrage?" /></p><p>Ich möchte also, dass Alexa automatisch erkennt, dass sich mein Befehl „Lege zwei davon zurück!“ auf meine letzte Anfrage bezieht, also die Fünfen. Diesen Kontext zu implementieren obliegt momentan rein dem Skill-Entwickler. Von Haus aus merkt sich Alexa keinerlei Kontext.</p><h3>Geschwätzige Antworten</h3><p>Ein anderer Aspekt, den es beim Entwurf eines Skills zu berücksichtigen gilt, ist, wie wortreich die Antworten des Skills ausfallen. Als Anwender wünsche ich mir kurze und knappe, aber ausreichend informative Antworten auf meine Anfragen. Hier gehen Skills heute häufig noch dem vermeintlich sicheren Weg und geben dem Anwender im Zweifel lieber zu viele Informationen. Wenn ich aber per Sprache durch eine Menge von Schritten navigiere und nach jedem Schritt darauf hingewiesen werde, dass ich mit „Weiter“ zum nächsten Schritt komme, mit „Zurück“ einen Schritt zurück und „Wiederholen“ den letzten Schritt wiederholt, dann wird das schnell lästig. Wenn ich Hilfe zur Navigation brauche, möchte ich lieber explizit danach fragen können.</p><p>Die Antwort so knapp zu bemessen wie in einem menschlichen Dialog ist aber oft auch nicht das richtige Maß. Wir sind eben nicht in einer menschlichen Interaktion. Denn auch wenn die Spracherkennung heute sehr beeindruckend funktioniert, ist sie im Allgemeinen nicht auf dem Niveau eines Menschen. Das wissen auch die Anwender und es bleibt eine gewisse Ungewissheit: Hat mich der Skill auch wirklich verstanden?<br /> Im Beispiel oben fragt der Anwender: „Wie viele Fünfen habe ich gewürfelt?“ und die Antwort ist: „Du hast drei Fünfen gewürfelt“. Ein Mensch würde wohl eher nur mit „Drei“ antworten. Mit der etwas längeren Antwort beantworten wir so nicht nur die ursprüngliche Frage, sondern bestätigen auch, was der Skill verstanden hat und geben dem Anwender so mehr Sicherheit und Vertrauen in unseren Skill.</p><h3>Fehlertoleranz</h3><p>Ein wichtiger Aspekt bei allen Mensch-Maschine-Interaktionen ist die Fehlertoleranz und die Steuerbarkeit. Fühlt sich der Anwender in Kontrolle des Systems oder eher durch das System kontrolliert?<br /> Um sicherzustellen, dass ein Slot in einem Intent richtig interpretiert wurde, bietet Amazon Skill-Entwicklern die Möglichkeit, Slot Confirmations zu implementieren. Dabei muss der Anwender die Werte die der Skill verstanden hat noch einmal bestätigen.</p><p><img loading="lazy" width="700" height="410" src="https://media.graphassets.com/XZCGOi1QQam8K94rbF5J" alt="Slot Confirmation am Beispiel des starteSpiel Intents" /></p><p>Die Möglichkeit, Aktionen vom Anwender noch einmal bestätigen zu lassen, ist insbesondere bei Aktionen sinnvoll, bei denen potenziell Daten verloren gehen könnten oder die eine finanzielle Transaktion einleiten. Aber die Häufigkeit, mit der sie in Skills eingesetzt werden, erinnert etwas an vergangene Tage in grafischen Benutzerschnittstellen, wo man noch häufig mit Dialogen behelligt wurde: „Sind Sie wirklich sicher, dass Sie das Spiel neu starten wollen?“ oder „Soll der Spieler wirklich gelöscht werden?“.<br /> Vielleicht schaffen wir es auch bei Sprachinterfaces, dem Anwender mehr Kontrolle zu verschaffen, indem wir ihm bessere Möglichkeiten geben, Befehle wieder zurückzunehmen.</p><h2>Fazit</h2><p>Was Sprachinterfaces heute leisten können, ist bereits sehr beeindruckend. Mit Blick auf Alexa Skills ist für natürlich geführte Dialoge aber noch einiges zu tun. Heute sind die Interaktionen mit einem Sprachassistenten noch recht einfach und kurz. Wer trotzdem komplexere Interaktionen realisieren will, konnte hoffentlich in diesem Beitrag einige hilfreiche Anregungen finden. Wenn ihr ähnliche oder abweichende Erfahrungen gemacht habt, würde ich mich über euer Feedback in den Kommentaren freuen.</p>

User Experience in Voice User Interfaces am Beispiel eines Alexa Skills

<p>In den letzten zwei Jahren haben sich viele der Aktivitäten in der Business-Welt zu Remote-Aktivitäten verändert. Für viele von uns sind dadurch neue Tools in den Fokus gerückt.</p><p>Aber auch wenn diese Werkzeuge sich enorm weiterentwickelt haben, irgendwann stoßen sie an ihre Grenzen. Und was läge einem Entwickler in so einem Fall näher als zu schauen, wie man diese Grenzen verschieben kann?</p><p>Eines der Werkzeuge, die in meinem Alltag eine deutlich größere Rolle einnehmen als früher, ist Miro, eine Online-Whiteboard-Lösung.</p><p>In diesem Blog-Artikel beleuchte ich, wie man Miro durch ein eigenes Plugin funktional erweitern kann.</p><h2>Projektinitialisierung</h2><p>Miro bietet unter <a href="https://developers.miro.com/docs">https://developers.miro.com/docs</a>  eine Übersicht der zur Verfügung stehenden APIs und SDKs. Für diesen Artikel konzentriere ich mich auf Plugins zur Erweiterung des Miro User Interfaces.</p><p>Um mit einem eigenen Plugin loszulegen, sind einige Schritte erforderlich. Als Startpunkt empfehle ich die Seite: <a href="https://developers.miro.com/docs/build-your-first-hello-world-app">https://developers.miro.com/docs/build-your-first-hello-world-app</a> . Ich werde mich in diesem Artikel auf das Anlegen des Entwicklungsprojektes konzentrieren.</p><h2>Anlegen des Entwicklungsprojektes</h2><p>Ein initiales Projekt lässt sich über das Command Line Interface create-miro-app erzeugen. Mit dem Befehl:</p><p><code>yarn create miro-app</code></p><ul><li>erzeugt man sich ein initiales Projekt. Dabei wird man interaktiv durch ein paar Fragen geführt:</li><li>Wie soll der Name des Plugins sein?</li><li>Möchte man mit VanillaJS oder React arbeiten?</li><li>Soll das Projekt als JavaScript oder TypeScript angelegt werden?</li></ul><h2>Das API</h2><p>Als ich angefangen habe, zu recherchieren, wie man Miro erweitern kann, hatte ich zunächst keine Vorstellung davon, wie die API für ein Plugin aussehen würde. Ich war also von den Fragen durchaus überrascht, da ich mit serverseitigem Code und nicht mit einem eigenen Frontend-Projekt gerechnet hätte.<br /> Das Plugin läuft also als eigene Anwendung in einem iFrame innerhalb von Miro. Kommuniziert wird mit der Hauptanwendung über Events. Dies wird allerdings vom Entwickler weggekapselt. Stattdessen programmiert man gegen ein Miro-Objekt, das automatisch global zur Verfügung steht.</p><blockquote><p>Hinweis:<br /> Wer nur schnell mal etwas ausprobieren möchte, erreicht mit create-miro-app schnell sein Ziel. Wer aber wirklich ein Plugin produktreif entwickeln möchte, dem lege ich ans Herz, einen Blick auf mein im Rahmen dieses Blogposts entstandenes Repo bei GitHub zu werfen:<br /> <a href="https://github.com/stefan-spittank/miro-affinity-diagram-tools">https://github.com/stefan-spittank/miro-affinity-diagram-tools</a> <br /> Dort findet ihr ein Projekt inkl. Test-Setup mit Jest und react-testing-library, JSlint und Prettier.</p></blockquote><p>Das Miro-Objekt erlaubt dem Entwickler die Kommunikation in zwei Richtungen. Zum einen kann er über Methoden Einfluss auf die Inhalte des geöffneten Miro Boards nehmen, zum anderen kann sich über Events über Änderungen im Miro Board benachrichtigen lassen:<br /> <img loading="lazy" src="https://media.graphassets.com/H6LN2E9nTQq2skTyjKbN" alt="Kommunikation mit dem miro Objekt. Änderungen über den Aufruf von Methoden, Events registrieren mit addListener" width="800" height="270" /></p><h3>Aktivierung des Plugins</h3><p>Damit ein Miro-Plugin aktiv werden kann, muss es sich in die Benutzeroberfläche von Miro einklinken. Dies geschieht in der<br /> <i>index.ts</i>-Datei, die über ein unsichtbares iFrame aus der <i>index.html</i> geladen wird.<br /> In der <i>index.ts</i> kann man sich beim Miro-Objekt für das <code>onReady</code> Callback von miro anmelden. Dieses Callback wird ausgeführt, wenn Miro geladen wurde. Ab diesem Zeitpunkt ist es zulässig, die SDK-Methoden zu verwenden.<br /> In diesem Callback kann nun das eigene Plugin mit der Methode <code>initialize</code> initialisiert werden. Dieser Methode übergibt man ein Konfigurationsobjekt, um sich für verschiedene Extension Points zu registrieren. Extension Points sind dabei Elemente in der Miro-Benutzeroberfläche, die man als Plugin erweitern kann. Beispiele für Extension Points sind die Toolbar, die Bottom Bar oder das Export Menu.<br /> Ein Beispiel für eine Plugin-Initialisierung:</p><div>

```javascript
miro.onReady(async () => {
  await miro.initialize({
    extensionPoints: {
      toolbar: {
        title: "Test",
        toolbarSvgIcon: affinityDiagramIcon,
        librarySvgIcon: affinityDiagramIcon,
        async onClick() {
          const isAuthorized = await miro.isAuthorized();
 
          if (!isAuthorized) {
            // Ask the user to authorize the app.
            await miro.requestAuthorization();
          }
          await miro.board.ui.openLeftSidebar(
            "src/SidebarApp/SidebarApp.html"
          );
        },
      },
    },
  });
});
```

</div><p>Im Beispiel registrieren wir einen Button in der Toolbar mit dem Titel „Test“ und zwei Icons (Miro unterscheidet hier zwischen zwei Zuständen, die für das Beispiel hier keine Relevanz haben). Wird der Button in der Toolbar angeklickt, erfolgt zunächst eine Überprüfung, ob das Plugin bereits für den Benutzer aktiviert ist. Ist dies nicht der Fall, wird der Benutzer nun zunächst durch den Aufruf von <code>requestAuthorization</code> dazu aufgefordert, das Plugin zu installieren.<br /> <img loading="lazy" src="https://media.graphassets.com/euOFe5MxR9KzVMSJpJvS" alt="Screenshot des Dialogs in Miro der den Benutzer fragt, ob er das Plugin autorisieren möchte." width="499" height="563" /></p><blockquote><p>Hinweis: in diesem Dialog werden dem Benutzer auch die Berechtigungen angezeigt, die das Plugin einfordert. Diese werden allerdings nicht beim Aufruf von requestAuthorization festgelegt, sondern bereits beim Anlegen der App in Miro. Über das Berechtigungskonzept wird gesteuert, auf welche Aspekte eines Miro Boards das Plugin Lese- oder Schreibzugriff hat. Mehr zum Berechtigungskonzept findet ihr hier: <a href="https://developers.miro.com/docs/add-permission-scopes-to-your-app">https://developers.miro.com/docs/add-permission-scopes-to-your-app</a> </p></blockquote><p>Ist das Plugin autorisiert, öffnet es über den Befehl <code>miro.board.ui.openLeftSidebar</code> eine HTML-Seite des Plugins in die linke Seitenleiste von Miro geladen. Diese Seitenleiste rendert wiederum eine React-Anwendung als User Interface des Plugins.</p><h2>Zugriff auf Elemente des Miro Boards</h2><p>Nachdem das Plugin sich in Miro registriert und der Benutzer es autorisiert hat, ist nun ein programmatischer Zugriff auf das Board möglich.<br /> Was wäre naheliegender als zunächst ein einfaches Widget mit dem Text “Hello World” anzulegen? Hier der dazu notwendige Code:</p><div>

```javascript
await miro.board.widgets.create({
  type: "STICKER",
  text: "Hello World",
  x: 0,
  y: 0
});
```

</div><p>Die Erzeugung eines Widgets ist also denkbar einfach. Angegeben werden muss mindestens: der Typ des Widgets, der Inhalt und die Position.<br /> Der Typ des Widgets ist im Beispiel “STICKER”, wodurch ein typisches Post-it-Widget erzeugt wird. Es existieren aber auch eine Reihe weiterer Widget-Typen, wie Text- oder Shape-Widgets.<br /> Der obige Code erzeugt das Widget bei den Koordinaten (0, 0). Dies ist aber vermutlich keine gute Idee, da diese Position nicht unbedingt im für den Benutzer sichtbaren Bereich liegen muss. Der für den aktuellen Benutzer sichtbaren Bereich kann über die Miro-API ausgelesen werden. Im Beispiel würde das so aussehen:</p><div>

```javascript
const { x, y, width, height } = await miro.board.viewport.get();
```

</div><p>Der Viewport liefert ein Rectangle-Objekt zurück mit x- und y-Koordinaten und Höhe sowie Breite. Die Informationen können nun genutzt werden, um das neue Widget im sichtbaren Bereich zu positionieren.</p><h2>Reaktion auf Ereignisse</h2><p>Der obige Code demonstriert sowohl den lesenden als auch den schreibenden Zugriff auf Elemente im Miro Board. Ein weiterer wichtiger Baustein für die Entwicklung eines Miro-Plugins ist die Möglichkeit, auf Ereignisse zu reagieren. Mögliche Ereignisse, auf die ein Plugin reagieren kann, sind:</p><ul><li>SELECTION_UPDATED</li><li>WIDGETS_CREATED</li><li>WIDGETS_DELETED</li><li>WIDGETS_TRANSFORMATION_UPDATED</li><li>ALL_WIDGETS_LOADED</li></ul><p>Um auf eines dieser Events zu reagieren, muss ein Event Handler registriert werden. Auch dies erfolgt über das globale Miro-Objekt:</p><div>

```javascript
miro.addListener('SELECTION_UPDATED', widgets => {
  console.log('Selected widgets:', widgets)
});
```

</div><h2>Abschluss</h2><p>Miro hat mit seiner API eine Möglichkeit geschaffen, den Funktionsumfang um Fähigkeiten zu erweitern, die dem Benutzer vielleicht bislang gefehlt haben. Aber wie gut funktioniert das in der Praxis? Mein Fazit:</p><h3>Was mir gut gefallen hat</h3><p>Es gab einige Punkte, die mir wirklich gut gefallen haben:</p><ul><li>Die API war für mich überraschend einfach. Durch das Command-Line Tool <code>create-miro-app</code> habe ich sehr schnell ein erstes Erfolgserlebnis verbuchen können. Ein erster Prototyp war in ein weniger als einem Tag realisierbar.</li><li><code>create-miro-app</code> wird aktiv weiterentwickelt. In dem Zeitraum, in dem dieser Blogeintrag entstand, gab es mehrere Releases.</li><li>Die Möglichkeit, eine React-Anwendung als Miro-Plugin einzusetzen, hat den Vorteil, dass es direkt eine breite Entwicklerbasis gibt, die potenziell Miro-Plugins umsetzen könnte.</li></ul><h3>Was mir (noch) nicht so gut gefallen hat</h3><p>Bei der Entwicklung bin ich aber auch auf einige Punkte gestoßen, die aus meiner Sicht noch nicht rund sind:</p><ul><li>Die Möglichkeit, das Plugin in TypeScript zu entwickeln, ist zwar gegeben, diese wird von Miro aber recht stiefmütterlich behandelt. Zum einen hat sich das Entwicklungsteam gegen den – recht verbreiteten – Weg entschieden, eine eigenes <code>@typings</code>-Modul zu veröffentlichen. Stattdessen wird dem generierten Code eine <code>miro.d.ts-Datei</code> spendiert. In meinem Fall konnte IntelliJ mit der Datei aber nichts anfangen, sodass der initial von <code>create-miro-app</code> erzeugte Zustand für mich nicht nutzbar war (falls euch das auch so geht: in meinem Repo findet liegt die miro.d.ts nun im Ordner @types – das funktioniert).<br /> Zum anderen ist die Miro-API nicht wirklich gut getypt. An diversen Stellen bekommt man dann doch ein Array von any zurück und muss selbst testen, wie die Objekte wohl aussehen mögen, die man von der API erhält. Beispiel: Das <code>SELECTION_UDPATED-Event</code> liefert ein Event-Objekt mit einer data-Property vom Typ any. Zur Laufzeit ist any mal ein Objekt, mal ein Array. Die Objekte sind Widgets, aber nicht mit allen Eigenschaften, die ein Widget hat, das man über miro.ui.board.widgets.get erhält. Der Typ scheint also zu sein: <code>Partial<SDK.IWidget> | Partial<SDK.IWidget>[].</code></li><li>Wenn man nicht nur etwas ausprobieren möchte, sondern ernsthaft ein Plugin entwickelt, sollte man sich früh Gedanken über Testbarkeit machen. Das globale Miro-Objekt ist der Testbarkeit des Codes nicht zuträglich. Ich habe mich für mein Plugin entschieden, das Miro-Objekt zu kapseln und einen eigenen Miro-Provider zu implementieren.</li><li>Wer ein eigenes Plugin entwickelt, wird früher oder später zu dem Punkt kommen, an dem er das Plugin mit anderen Benutzern verproben möchte. Dann benötigt man neben dem lokal gestarteten Plugin noch eine deployte Variante. Mehrere Stages für Plugins sind aber nicht vorgesehen. Ich habe mich hier so beholfen, dass ich in Miro mehrere Plugins für DEV und PROD registriert habe, die dann zur Laufzeit aber optisch nicht unterscheidbar sind. Also benötigt man auch hier ein eigenes Konzept.</li></ul><h3>Fazit</h3><p>Bei aller Kritik an der API bin ich doch sehr dankbar für die Möglichkeit, die Miro hier geschaffen hat. Im Rahmen dieses Artikels konnte ich ein Plugin für die Auswertung von Benutzer-Interviews realisieren, das mir bei meiner täglichen Arbeit eine große Hilfe sein wird. Die Schwächen in der API wird Miro ja vielleicht noch ausmerzen.<br /> Gibt es für euch Dinge, die ihr gerne in Miro erweitern würdet? Oder habt ihr gar schon eigene Erfahrungen in der Entwicklung von Miro-Plugins? Dann lasst doch einen Kommentar da. Ich bin sehr auf eure Anmerkungen gespannt.</p>

Miro ohne Grenzen – Wie man eigene Plugins für Miro entwickelt

<p>In the <a href="https://blog.codecentric.de/en/2019/03/bdd-alexa-skill-cucumber-js-part-1/" target="_blank">first post of this blog series</a>  we established a framework to easily write acceptance tests for an Alexa Skill in Cucumber.js. This second part will be about enhancing this framework, so that our skill is able to use state handling.</p><h2>Ways to store skill state information</h2><p>Amazon offers us three ways to store information about the state of our skill:</p><ul><li>For the duration of the current request</li><li>For the duration of the current session</li><li>Persistent across sessions</li></ul><p>For the latter one our skill will need a special persistence adapter. Amazon offers a prebuilt DynamoDB-based adapter which is easily configured.</p><p>For our skill, the storage of information just for the current request is not sufficient. So we’ll skip this one. But the storage of information for the duration of one session looks more promising. So let’s start with this.</p><h2>Session-state handling</h2><h3>What is an Alexa session?</h3><p>Before we go into the details of storing information for one session, let’s take a step back and look at what the term “session” means in the context of an Alexa Skill.</p><ul><li>The moment a user opens our skill, a new session is initiated</li><li>A session will end if<ul><li>the user explicitly ends the session (e.g. by calling “Alexa, stop”).</li><li>the user doesn’t continue the conversation after our last response within eight seconds</li><li>We can enhance this time frame by another eight seconds if we provide a reprompt in our response</li><li>The session will be automatically terminated if an error occurs during the handling of the intent</li></ul></li></ul><p>As we can see, an Alexa session is tightly coupled to the user.</p><p>As we can also see, the duration of an Alexa session is strongly dependent on the user continously interacting with our skill (ans so potentially quite short). At least that’s the case for custom skills, music or video skills have different interaction models.</p><h3>Session attributes</h3><p>For the duration of an Alexa session, we can store the current state in session attributes. We get the session attributes as a key value store from the <code>AttributeManager</code> provided by the <code>handlerInput</code> object.</p><p>The AttributeManager offers us two methods to get and set the session attributes:</p><ul><li><code>getSessionAttributes</code> to read the attributes</li><li><code>setSessionAttributes</code> to write the attributes</li></ul><p>We can use the session attributes in our skill, to store the given number of players for the current session. In our <code>starteSpiel</code> (startGame) intent, this looks like this:</p><div>

```javascript
// @flow
import {HandlerInput} from 'ask-sdk-core';
import {Response} from 'ask-sdk-model';
import {PLAYER_COUNT_KEY, SKILL_NAME} from '../../consts';
import {deepGetOrDefault} from '../../deepGetOrDefault';
 
export const StarteSpielIntentHandler = {
    canHandle(handlerInput: HandlerInput) {
        return handlerInput.requestEnvelope.request.type === 'IntentRequest' &&
            handlerInput.requestEnvelope.request.intent.name === 'starteSpiel';
    },
    handle(handlerInput: HandlerInput): Response {
        const numberOfPlayers = deepGetOrDefault(handlerInput, '1', 'requestEnvelope', 'request', 'intent', 'slots', 'spieleranzahl', 'value');
 
        const {t} = handlerInput.attributesManager.getRequestAttributes();
 
        const playersText = numberOfPlayers === '1' ? 'einen' : numberOfPlayers;
        const speechText = t('GAME_STARTED', playersText);
        const sessionAttributes = handlerInput.attributesManager.getSessionAttributes();
        sessionAttributes[PLAYER_COUNT_KEY] = numberOfPlayers;
        handlerInput.attributesManager.setSessionAttributes(sessionAttributes);
 
        return handlerInput.responseBuilder
            .speak(speechText)
            .withSimpleCard(t('SKILL_NAME'), speechText)
            .withShouldEndSession(false)
            .getResponse();
    }
};
```

</div><p>We start by reading the number of players (given by the user) from the request (<code>deepGetOrDefault</code> is a small utility function which will either return the value of an object attribute on a given path in a nested object structure, or return the default value if any of the given attributes is null or undefined).</p><p>Then we build our response. Instead of hard-coded strings, we use the function <code>t</code> which is a translation function provided by <code>i18-next</code>, the framework we’re using for internationalization. The function <code>t</code> will be injected by the <code>localizationInterceptor</code>. You can find more details about localizing Alexa Skills <a href="https://developer.amazon.com/de/blogs/alexa/post/285a6778-0ed0-4467-a602-d9893eae34d7/how-to-localize-your-alexa-skills" target="_blank">in this blog post</a> .</p><p>After creating the response text, we get the <em>sessionAttributes</em>, store our number of players in it and save the attributes.</p><p>Finally the response object is built and returned.</p><p>We can now use this session attribute to provide another intent to retrieve the number of players later.</p><p>To do this, we’ll start with a new acceptance test (since we want to work in true BDD fashion):</p>

```

# language: en
Feature: Start a new game
  Background:
    Given the user has opened the skill

  Scenario: A new game can be started, the number of players is stored
    When the user says: Start a new game with 4 players
    Then Alexa replies with: Okay, I started a new game for 4 players
    When the user says: How many players do I have?
    Then Alexa replies with: You are playing with 4 players

```

<p>To get this test green (= passing), we have to do the following things:</p><ol><li>The new intent (and at least one utterance for it) needs to be added to our voice interaction model.</li><li>We need to add a new handler for this intent to our Lambda function</li><li>We have to enhance our testing framework, so that session attributes will correctly be handled and new intents within the same session receive the previously stored attributes.</li></ol><h3>Handling <em>SetSessionAttributes </em>in Cucumber tests</h3><p>We start with the last point, since this is a one-time-only investment.</p><p>Our test framework needs to be aware of changes to the session attributes, so that they are available for further requests. To be able to do this, we use a <a href="https://developer.amazon.com/de/blogs/alexa/post/0e2015e1-8be3-4513-94cb-da000c2c9db0/what-s-new-with-request-and-response-interceptors-in-the-alexa-skills-kit-sdk-for-node-js" target="_blank"><code>requestInterceptor</code></a> . The interceptor allows us to modifiy the <code>handlerInput</code> object before it is given to the handler’s <code>handle</code> function.</p><p>To inject the <code>requestInterceptor</code>, we change the skill creation to a factory method. This factory method receives a list of interceptors which will be added to our Lambda:</p><div>

```javascript
export const createSkill = (requestInterceptors: RequestInterceptor[]) => {
    const skillBuilder = Alexa.SkillBuilders.custom();
    const skill = skillBuilder
        .addRequestHandlers(
            ExitHandler,
            HelpHandler,
            LaunchRequestHandler,
            SessionEndedRequestHandler,
            StarteSpielIntentHandler
        )
        .withPersistenceAdapter(persistenceAdapter)
        .addErrorHandlers(ErrorHandler);
    if (requestInterceptors.length > 0) {
        skill.addRequestInterceptors(...requestInterceptors);
    }
 
    return skill.lambda();
};
```

</div><p>The production skill is still created in the <code>index.js</code> file. The call is quite simple:</p><div>

```javascript
export const handler = createSkill([localizationInterceptor]);
```

</div><p>We only provide one interceptor object (the internationalization interceptor mentioned above).</p><p>The skill for our tests will be created by a new <code>createSkillForTest</code> method:</p><div>

```javascript
function createSkillForTest(world) {
    const requestInterceptor: RequestInterceptor = {
        process(handlerInput: HandlerInput) {
            // Wrap setSessionAttributes, so that we can save these Attributes in the test
            const orginalSetSessionAttributes = handlerInput.attributesManager.setSessionAttributes;
            handlerInput.attributesManager.setSessionAttributes = (attributes: Attributes) => {
                world.sessionAttributes = attributes;
                orginalSetSessionAttributes.call(handlerInput.attributesManager, attributes);
            }
        }
    };
    return createSkill([localizationInterceptor, requestInterceptor])
}
```

</div><p>For the tests we provide an additional interceptor object we create locally. We use the interceptor to replace the <code>setSessionAttributes</code> of the <em>AttributeManager</em> given to our handler. The new setSessionAttributes stores the sessionAttributes in the global world object of Cucumber.js and afterwards calls the original setSessionAttributes method (we previously replaced).</p><p>So we already took care of the first part (receiving the changed session attributes), now we need to make sure that the next request handler will receive the updated attributes. This is done in the <code>executeRequest</code> method introduced in the last part of this blog series. We add an additional lines to take care of the sessionAttributes:</p><div>

```javascript
async function executeRequest(world, skill, request) {
    return new Promise((resolve) => {
        // Handle session attributes
        request.session.attributes = simulateDeserialization(world.sessionAttributes);
        skill(request, {}, (error, result) => {
            world.lastError = error;
            world.lastResult = result;
            resolve();
        });
    });
}
```

</div><p>The <code>simulateDeserialization</code> simulates a (de-)serialization by converting the key-value store to JSON and parsing it back to a JavaScript object. This helps find bugs with ES6 Class properties, which will be lost in this process (<a href="https://stackoverflow.com/questions/38922990/re-associating-an-object-with-its-class-after-deserialization-in-node-js" target="_blank">if you don’t manually restore them</a> ).</p><h3>Implementing the new intent</h3><p>With our updated test framework, it is quite easy to implement the final intent handler. You can see the implementation in <a href="https://gitlab.com/spittank/fuenferpasch/tree/BlogBDD_EN_Part2" target="_blank">the repository on gitlab</a> .</p><h2><em>PersistentState</em> handling</h2><p>To be able to store a state in a session is important and nice. But as we’ve seen above, an Alexa session is potentially quite short-lived. Depending on the type of skill we are implementing, this may soon become an issue. Luckily the Alexa Skill Kit SDK allows us to persist data beyond the duration of a session.</p><p>The API to use PersistenAttributes is very similar to SessionAttributes:</p><ul><li><code>getPersistentAttributes</code> will asynchronously return the persistent attributes in a promise</li><li><code>setPersistenAttributes</code> will set the persistent attributes</li><li>and <code>savePersistentAttributes</code> will asynchronously persist the attributes previously set</li></ul><p>To be able to use this API, we need to tell our skill how the data is being persisted. We do this by configuring our skill with a <code>PersistenceAdapter</code>. We could <a href="http://ask-sdk-node-typedoc.s3-website-us-east-1.amazonaws.com/interfaces/persistenceadapter.html" target="_blank">implement our own PersistenceAdapter</a>  or use <a href="https://ask-sdk-for-nodejs.readthedocs.io/en/latest/Managing-Attributes.html#persistenceadapter" target="_blank">one of the predefined ones</a> .</p><p>For our skill we’ll be using the <code>DynamoDbPersistenceAdapter</code>, only in the tests we’ll implement our own.</p><h3>Adding the DynamoDbPersistenceAdapter</h3><p>To use the DynamoDbPersistenceAdapter, we have to add the package <code>ask-sdk-dynamodb-persistence-adapter</code> to our project.</p><h3>Giving the Lambda function access to the DynamoDB</h3><p>Additionally our Lambda function needs access rights to read from the database. To do this, we need to look up the role assigned to our Lambda function first. We do this from the <a href="https://eu-west-1.console.aws.amazon.com/lambda/home?region=eu-west-1#/functions" target="_blank">Lambda Management Console</a>  from where we navigate to our Lambda function to look up the role:</p><p><img width="700" height="480" src="https://media.graphassets.com/vzgKyxgZRLimqD5kmg4s" alt="Looking up the role of a lambda function" /></p><p>We use this role in the <a href="https://console.aws.amazon.com/iam/home?region=eu-west-1#/roles" target="_blank">IAM Management Console</a>  to assign access rights to the DynamoDB to this role:<br /> <img loading="lazy" width="700" height="453" src="https://media.graphassets.com/nE227ssQhqJzv1X6ccA9" alt="Add DynamoDB access rights to the role" /></p><h3>Configuration of our skill to use the PersistenceAdapter</h3><p>To use the DynamoDB Persistence Adapter, we need to enhance our <code>createSkill</code> function:</p><div>

```javascript
export const createSkill = (PersistenceAdapterClass: Class<PersistenceAdapter>, requestInterceptors: RequestInterceptor[]) => {
    const skillBuilder = Alexa.SkillBuilders.custom();
    const persistenceAdapter = new PersistenceAdapterClass({
        tableName: `${SKILL_INTERNAL_NAME}_state`,
        createTable: true
    });
    const skill = skillBuilder
        .addRequestHandlers(
            ExitHandler,
            HelpHandler,
            LaunchRequestHandler,
            SessionEndedRequestHandler,
            StarteSpielIntentHandler,
            WieVieleSpielerIntentHandler
        )
        .withPersistenceAdapter(persistenceAdapter)
        .addErrorHandlers(ErrorHandler);
    if (requestInterceptors.length > 0) {
        skill.addRequestInterceptors(...requestInterceptors);
    }
 
    return skill.lambda();
};
```

</div><p>The method receives an additional parameter: <code>PersistenceAdapterClass</code>. This is the class implementing the PersistenceAdapter interface. Our method creates a new instance of this class (configuring the table name of the table we store our state into) and passes this instance to the skill builder using the <code>withPersistenceAdapter</code> method.</p><p>From our index.js we pass in an DynamoDB adapter to this new parameter:</p><div>

```javascript
import {createSkill} from './createSkill';
import {DynamoDbPersistenceAdapter} from 'ask-sdk-dynamodb-persistence-adapter';
import {localizationInterceptor} from './localizationInterceptor';
 
export const handler = createSkill(DynamoDbPersistenceAdapter, [localizationInterceptor]);
```

</div><h3>Configuration of the PersistenceAdapter in our tests</h3><p>For the Cucumber tests we pass in our own implementation of a PersistenceAdapter:</p><div>

```javascript
function createSkillForTest(world) {
    class MockPersistenceAdapterClass {
        getAttributes: () => Promise<any>;
        saveAttributes: () => Promise<void>;
        attributes: any;
 
        constructor() {
            this.getAttributes = () => Promise.resolve(world.persistentAttributes);
            this.saveAttributes = (_, attributes) => {
                world.persistentAttributes = attributes;
                return Promise.resolve();
            };
        }
    }
    const requestInterceptor: RequestInterceptor = {
        process(handlerInput: HandlerInput) {
            // Wrap setSessionAttributes, so that we can save these Attributes in the test
            const orginalSetSessionAttributes = handlerInput.attributesManager.setSessionAttributes;
            handlerInput.attributesManager.setSessionAttributes = (attributes: Attributes) => {
                world.sessionAttributes = attributes;
                orginalSetSessionAttributes.call(handlerInput.attributesManager, attributes);
            }
        }
    };
    return createSkill(MockPersistenceAdapterClass, [localizationInterceptor, requestInterceptor])
}
```

</div><p>Similar to the way we’re handling session attributes, we store the persistent attributes in the global world object and update them there if somewhere in the lambda function <code>saveAttributes</code> is called.</p><h2>Conclusion</h2><p>The test framework developed in the blog series is the base to be able to do behaviour-driven development of Alexa Skills. You will find the complete source code on GitLab. I created tags for different blog posts, so after this blog post you’ll probably want to look at:</p><p><a href="https://gitlab.com/spittank/fuenferpasch/tree/BlogBDD_EN_Part2" target="_blank">https://gitlab.com/spittank/fuenferpasch/tree/BlogBDD_EN_Part2</a> </p><p>first.</p><p>Do you have additional use cases not covered yet? Is this framework helpful for you? I would love to hear your feedback in the comments below.</p>

Behaviour-driven development (BDD) of an Alexa Skill with Cucumber.js – Part 2

<p>In this blog article we will learn how to do behaviour-driven development (BDD) of an Alexa Skill utilizing the Cucumber.js framework.</p><h2>Why do you even want to do this?</h2><p>I didn’t even intend to do a blog article on BDD of Alexa Skills. I just wanted to get into voice UIs and learn more about the current state of the art. I must admit: I even tried to skip writing tests altogether. But I quickly learned that there are just too many things that could possibly go wrong, and the turnaround times from writing code to seeing whether it actually works are just too long:</p><ul><li>define the voice UI</li><li>write the code locally</li><li>build the code</li><li>upload your code</li><li>start the Alexa Skill in the Alexa Simulator or on your Echo device</li><li>Alexa reports an error</li><li>search for the log file</li><li>realize you forgot to register your new intent handler</li><li>fix your code and restart the loop</li></ul><p>Imagine we are building an Alexa Skill to write down points in a game of dice. What if we could define our voice interaction upfront like this…</p>

```

 Scenario: A new game can be started, the number of players is stored
    Given the user has opened the skill
    When the user says: Start a new game with 4 players
    Then Alexa replies with: Okay, I started a new game for 4 players
    When the user says: How many players do I have?
    Then Alexa replies with: You are playing with 4 players

```

<p>…and then be able to actually run this as an automated acceptance test?</p><p>This is exactly what we are going to do in this blog entry.</p><h2>About Cucumber.js</h2><p>Cucumber.js is the JavaScript version Cucumber, a framwork for running automated acceptance tests. There are already a lot of good introductions for Cucumber, so I will keep this part short. If you are new to Cucumber, I recommend reading <a href="https://docs.cucumber.io/guides/overview/" target="_blank">their very good introduction</a>  first.</p><p>Cucumber allows us to define test scenarios in a text file.</p><p>Each test scenario starts with the keyword <code>Scenario</code>, followed by the name of the test.</p><p>The test itself consists of different steps. Each step has to be started with one of these keywords:</p><ul><li><code>Given</code>: Defines the initial context of the system prior to our test. In the example above, we assume that the user has already opened our Alexa Skill.</li><li><code>When</code>: Describes an action taken in the test. In our case, this could be the user saying something to their echo device.</li><li><code>Then</code>: Specifies the expected outcome of the prior steps. For us, this would typically be the reply Alexa gave to the user.</li></ul><p>There is more to it, but this is a very short description of how a Cucumber test might be structured.</p><p>But out of the box Cucumber has no clue how to execute these steps. That’s something we need to do, and that’s what this article is about.</p><h2>Ingredients of an Alexa Skill</h2><p>To be able to implement the Cucumber steps, we first need to look at the different parts of an Alexa Skill. To create a new skill, we have to create at least two artifacts:</p><ul><li>The first part is the Voice Interaction Model. This model defines all commands (intents) a user can trigger in our skill and which speech input (utterances) will trigger which intent.</li><li>The second part is the code handling these intents. Typically, this code will receive an intent request and will answer with a voice reply (though there are other possible results). It could be any webservice, but Amazon makes our life easier if we use an AWS Lambda for this purpose (which is what we will do here).</li></ul><p>So a user interaction is processed as follows:<br /> <img width="700" height="314" src="https://media.graphassets.com/X38fu0DTee3DKhdJaXV3" alt="Processing of a user interaction with an Alexa Skill" /></p><ul><li>The user talks to their Echo device.</li><li>From the device the speech input is sent to the Alexa Voice Service.</li><li>The Alexa Voice Service uses our Voice Interaction Model to find a fitting intent and (if one is found) creates a proper intent request.</li><li>Our Lambda function receives the intent request. Executes the appropriate intent handler which generates a response sent back to the device</li></ul><h2>Our voice interaction model</h2><p>Before we take care of the Alexa Voice Service in our tests, let’s take a look at our interaction model. We will need this locally for the tests, so we first make a local copy:</p><p>Open the Alexa Developer Console, navigate to the Alexa Skill and open the JSON editor. From there you can copy the content and create a local version of the voice interaction model.</p><p><img loading="lazy" width="700" height="382" src="https://media.graphassets.com/sr7NepUWSHe2ejg1YaTQ" alt="The JSON editor of the voice interaction model" /></p><p>The code of this blog article is available in this <a href="https://gitlab.com/spittank/fuenferpasch/tree/BlogBDD_EN">GitLab repository</a> . The example is localized to English and German, so there are actually two voice interaction models: the English one (interactionModel.en.json) and the German one (interactionModel.de.json).</p><p>Our skill for the blog entry has two intents: one to start a new game (remember: it’s about a fictional game of dice) and one to ask how many players there are.</p><p>The English voice interaction model looks like this:</p><div>

```javascript
{
    "interactionModel": {
    "languageModel": {
        "invocationName": "five of a kind",
            "intents": [
            {
                "name": "AMAZON.FallbackIntent",
                "samples": []
            },
            {
                "name": "AMAZON.CancelIntent",
                "samples": []
            },
            {
                "name": "AMAZON.HelpIntent",
                "samples": []
            },
            {
                "name": "AMAZON.StopIntent",
                "samples": []
            },
            {
                "name": "AMAZON.NavigateHomeIntent",
                "samples": []
            },
            {
                "name": "starteSpiel",
                "slots": [
                    {
                        "name": "spieleranzahl",
                        "type": "AMAZON.NUMBER"
                    },
                    {
                        "name": "players",
                        "type": "playersSlot"
                    }
                ],
                "samples": [
                    "Start a new game with {spieleranzahl} {players}"
                ]
            },
            {
                "name": "wieVieleSpieler",
                "slots": [],
                "samples": [
                    "How many players do we have",
                    "How many players do I have"
                ]
            }
        ],
            "types": [
            {
                "name": "playersSlot",
                "values": [
                    {
                        "name": {
                            "value": "persons"
                        }
                    },
                    {
                        "name": {
                            "value": "people"
                        }
                    },
                    {
                        "name": {
                            "value": "players"
                        }
                    }
                ]
            }
        ]
    }
}
}
```

</div><p>We see some default AMAZON intents (like Cancel or Stop) and our game intents <code>starteSpiel</code> (startGame) and <code>wieVieleSpieler</code>. Intent names and slot names are in German, because that is the voice interaction model I started with and localizing the internal values is probably not a good idea (note to myself: start with the English blog next time).</p><p>The <code>starteSpiel</code> intent can be triggered with:</p><p><code>Start a new game with {spieleranzahl} {players}</code></p><p>There are two slots (the values in curly braces):</p><ul><li><code>spieleranzahl</code> (number of players) of type <code>AMAZON.number</code> and</li><li><code>players</code> (in English, because it is specific to the English voice interaction model) of type <code>playersSlot</code>.</li></ul><p>The type <code>playersSlot</code> is a user-defined slot type which could be replaced by the values “players”, “persons” or “people”. We don’t actually care which of these words the user uses to address players, we just want to support a large variety of different voice inputs.</p><h2>The mock voice service</h2><p>To be able to run our acceptance tests locally, we have to replace Amazon’s Alexa Voice Service with a local mock voice service.</p><p><img loading="lazy" width="700" height="397" src="https://media.graphassets.com/3WmjBKn7TM2SvIXVxbl0" alt="Interaction flow in Cucumber tests with our mock voice service" /></p><h3>A generic <code>When the user says</code> step</h3><p>Of course we could create Cucumber steps specifically for each individual intent, however, we strive for a more generic approach. We will create a generic <code>When the user says</code> step and the mock voice service will decide which intent should be triggered.</p><p>To do this, our mock voice service reads the voice interaction model and stores all possible utterances our Alexa Skill understands, and for each utterance the associated intent.</p><p>For our Cucumber step, we have to decide whether the given phrase from the test step matches any of our utterances. Therefore, we convert each utterance to a regular expression. For me, regular expressions are always a bit scary, because I seldom use them and therefore find them hard to read. But this is pretty simple, I promise. It’s best described with an example:</p><p>The utterance:</p><p><code>Start a new game with {spieleranzahl} {players}</code></p><p>is converted to the following regular expression:</p><p><code>^Start a new game with (.*) (players|persons|people)$</code></p><p>While converting the utterance from the voice interaction model to a regular expression, we did the following:</p><ul><li>We added a <code>^</code> at the beginning and a <code>$</code> at the end, so our regular expression will only match on input with exact this beginnig and end, we don’t match on substrings.</li><li>Additionally, we replaced all predefined slots (of a type beginning with <code>AMAZON.</code>) with the expression: <code>(.*)</code>, matching any input.</li><li>And finally we replace all user-defined slots with an expression matching all possible values (in the given example: “players”, “persons” or “people”).</li></ul><p>To execute a test, we only have to match the speech input from the test step against all regular expressions generated from our voice interaction model. If we have a match, we know the intent we have to call and the values used for the different slots. With this information, we can build our own IntentRequest which is then given to the Lambda function that is being tested.</p><p>To build the IntentRequest (or any other request, like the LaunchRequest), there is a folder with request templates in the GitLab project. These templates are read during test execution and intent names and slot values are replaced with the values we determined before.</p><p>The implementation of the <code>When the user says</code> step looks like this:</p><div>

```javascript
async function theUserSays(utterance, locale: string) {
    const voiceUiModel = getVoiceUiModel(locale);
 
    const allUtterances = getAllUtterances(voiceUiModel.interactionModel);
 
    const matchingIntent: ?IntentInvocation = findMatchingIntent(allUtterances, utterance);
 
    expect(allUtterances).toHaveMatchingIntentFor(utterance);
    if (!matchingIntent) return;
 
    const slots = matchingIntent && matchingIntent.slots.reduce((acc, cur: Slot) => ({
        ...acc,
        [cur.name]: {
            name: [cur.name],
            value: cur.value,
            confirmationStatus: 'NONE',
            source: 'USER'
        }
    }), {});
 
    const json = fs.readFileSync('src/test/mockVoiceService/requestJsonTemplates/intentRequest.json', 'utf-8');
    const intentRequest = JSON.parse(json);
 
    intentRequest.request.intent.name = matchingIntent.intentName;
    intentRequest.request.intent.slots = slots;
    intentRequest.request.locale = locale;
 
    this.lastRequest = intentRequest;
 
    await executeRequest(this, this.skill, intentRequest);
}
 
When(/^der Anwender sagt[:]? (.*)$/, async function(utterance) {
    await theUserSays.call(this, utterance, 'de');
});
 
When(/^the user says[:]? (.*)$/, async function(utterance) {
    await theUserSays.call(this, utterance, 'en');
});
```

</div><p>The function <code>theUserSays</code> does all the heavy lifting. But it is not directly the Cucumber.js step implementation. Actually, two steps are implemented, one for the German and one for the English language. Since the skill is localized, it makes sense that we also localize our acceptance tests. Both step definitions just call the <code>theUserSays</code> function and set locale parameter.</p><p>In the <code>theUserSays</code> function, we start with <code>getAllUtterances</code>, which will get us all utterances of our Alexa Skill as regular expressions according to the description above.</p><p>The function <code>findMatchingIntent</code> will return the matching intent and all slot values.</p><p><code>expect(allUtterances).toHaveMatchingIntentFor(utterance)</code> is a custom matcher (we use the<a href="https://www.npmjs.com/package/expect" target="_blank"> expect package from jest </a> here) to make sure we actually have a match, otherwise the test will fail.</p><p>In the following reduce, we build a dictionary object with all given slot values (as expected by the skill request).</p><p>Finally we execute the built request with <code>executeRequest</code>.</p><h3>Checking the response of our Alexa Skill</h3><p>So far, we can successfully call the Lambda function of our skill from within our test. But we also need to look at the response to be able to check whether it meets our expectations.</p><p>Let’s take a look at the <code>executeRequest</code> method first:</p><div>

```javascript
async function executeRequest(world, skill, request) {
    return new Promise((resolve) => {
        skill(request, {}, (error, result) => {
            world.lastError = error;
            world.lastResult = result;
            resolve();
        });
    });
}
```

</div><p>The <code>executeRequest</code> function is a Promise which will be resolved as soon as we got a reply from our skill. This reply is given by calling the callback function we provide as the third parameter. The callback function receives two parameters. Depending on the success of the call, either the parameter <code>error</code> or the parameter <code>result</code> is set. Either way, we store both values in the global <code>world</code> object. This world object is where we store the current state of our test and Cucumber.js will take care of providing each Cucumber step implementation with this world object.</p><p>So to implement an <code>Alexa replies with</code> step is now actually quite easy:</p><div>

```javascript
function alexaReplies(expectedResponse) {
    expect(this.lastResult.response.outputSpeech.ssml).toEqual(`<speak>${expectedResponse}</speak>`);
}
Then(/^antwortet Alexa mit[:]? (.*)$/, alexaReplies);
Then(/^Alexa replies with[:]? (.*)$/, alexaReplies);
```

</div><p>Again, the main implementation is an extra function called by Cucumber steps for each language. The expectation is using the <code>this</code> reference to get access to the world object, which is Cucumber.js’s way of providing us with the test context (that’s the reason why we don’t use arrow functions for Cucumber steps since arrow functions have a different way of handling the this keyword).</p><p>Since we expect speech output in this step, we know this is given in the <code>outputSpeech</code> attribute of the response object.</p><h2>Conclusion and outlook</h2><p>With the described technique we already have a good base framework to work with Cucumber.js acceptance tests against our Alexa Skill. Adding more Cucumber steps for slot confirmation or screen output is very straightforward and you can see more implemented steps in the<a href="https://gitlab.com/spittank/fuenferpasch/tree/BlogBDD_EN" target="_blank"> linked GitLab project</a> .</p><p>Handling attributes for storing values (per request, session, or permanent) is something we’ll look into in part 2 of this blog series. Until then I’m happy to hear your thoughts and feedback in the comments below.</p>

Behaviour-driven development (BDD) of an Alexa Skill with Cucumber.js – Part 1

Weitere Infos

Details

Sprich mich gern an

Komm zu unserer Konferenz, ich freue mich auf den Austausch mit dir! Hast du vorher schon Fragen?

Vielen Dank für deine Anfrage. Ich melde mich bei dir.

Vielen Dank für deine Anmeldung. Eine E-Mail zur Bestätigung ist zu dir unterwegs.

Diese Seite ist eine Vorschau. \nKlicken Sie hier\n, um den Vorschaumodus zu verlassen.

Zu deiner Suche haben wir leider keine passenden Blogartikel gefunden. 

Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.

Die \nDatenschutzerklärung\n der codecentric AG habe ich zur Kenntnis genommen und bestätige das mit der Absendung des Formulars.*

Entdecke spannende weiterführende Themen und lass dich von der codecentric Welt inspirieren.

Ich möchte eure Inhalte abonnieren. Diese Einwilligung kann ich jederzeit widerrufen bzw. den Blog Newsletter abbestellen. Die Datenschutzerklärung habe ich gelesen. Ich bin damit einverstanden, dass die codecentric AG, Hochstr. 11, 42697 Solingen, mich über eigene Dienstleistungen, branchenrelevante Events, Webinare und Publikationen der codecentric AG über die von mir angegebene E-Mail-Adresse informiert. Meine Einwilligung ist freiwillig. Ich kann meine Einwilligung jederzeit mit Wirkung für die Zukunft widerrufen (z.B. über den hierfür vorgesehenen Abmeldelink in unserem Newsletter, per E-Mail an datenschutz@codecentric.de oder per Post an die oben genannte Adresse der codecentric AG) erklären. Weitere Hinweise zur Verarbeitung meiner personenbezogenen Daten und zu meinen Rechten als betroffene Person finde ich hier: \nhttps://www.codecentric.de/datenschutzerklaerung\n

Bitte wähle deine/n gewünschte/n Standort/e aus.

Wir möchten dich als Mensch kennenlernen. Erzähle uns, wer du bist, worauf du Wert legst, wie du gerne arbeitest und was du von uns als Arbeitgeber erwartest.

Bitte füge deine Bewerbungsunterlagen ​(mind. Lebenslauf, gerne auch mehr)​​ ​als eine ​PDF-​Datei ​hinzu.

Ich habe die \nDatenschutzbestimmungen\n und die Einwilligung in die Datenverarbeitung gelesen und stimme diesen zu.*

Job application form field placeholder 10

Keine passende Rolle gefunden? Bewirb dich bitte trotzdem initiativ! Jenseits von starren Schubladen zählen für uns vielmehr Motivation, Kompetenz und der Cultural Fit.

Job application form field placeholder 11

Dies ist ein Pflichtfeld, bitte fülle es aus.

Kontakt

Absenden

Nein! Doch! Oh!! – Diese 5 Dinge machen Webentwicklung 2023 besser!

EnterJS

Weitere Infos

Details

Sprich mich gern an

Gemeinsam bessere Projekte umsetzen.

Wir helfen deinem Unternehmen.

Unsere Leistungen

Hilf uns, noch besser zu werden.

Zu den Jobangeboten