update websocket example

Author: ptrthomas

README.md

@@ -59,5 +59,5 @@ This repository also contains examples of how to use Karate and demonstrates int
 * [Slack](slack/README.md) - Refer to blog posts and sample code from the community
 * [Spring Boot](spring-boot/README.md) - Resources on testing Spring Boot applications with Karate
 * [SSH](ssh/README.md) - how to open an SSH connection and invoke server commands using Karate
-* [WebSockets](websockets/README.md) - Built-in support for WebSockets or you can use Java interop for very advanced scenarios
+* [WebSocket](websocket/README.md) - Built-in support for WebSocket or you can use Java interop for very advanced scenarios
 * [Xray](https://docs.getxray.app/display/XRAYCLOUD/Testing+APIs+using+Karate+DSL) - Official documentation from the Xray team on how to integrate Karate

kafka/README.md

@@ -1,6 +1,6 @@
 # Karate Kafka
 
-Karate has native support for Kafka as an optional dependency (non-open source and commercial). Enterprise users can find more information here: [Karate-Kafka](https://github.com/karatelabs/karate-addons/tree/main/karate-kafka). 
+Karate has native support for [Apache Kafka](https://kafka.apache.org) as an optional dependency (non-open source and commercial). Enterprise users can find more information here: [Karate-Kafka](https://github.com/karatelabs/karate-addons/tree/main/karate-kafka). 
 
 A license is required for running (for e.g. in CI/CD) and a Karate Labs IDE subscription is required per developer seat.
 

websocket/README.md

@@ -0,0 +1,41 @@
+# Karate Websocket
+
+Karate has native support for [the Websocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) as an optional dependency (non-open source and commercial). Enterprise users can find more information here: [Karate-Websocket](https://github.com/karatelabs/karate-addons/tree/main/karate-websocket). 
+
+A license is required for running (for e.g. in CI/CD) and a Karate Labs IDE subscription is required per developer seat.
+
+This sample project shows how to handle the async nature of Websocket communication and handle a custom protocol such as [STOMP](https://stomp.github.io/). Make sure you have a `.karate/karate.lic` file in place before running the example.
+
+## Running
+
+This is a normal Java / Maven project. To run the simple [`echo.feature`](src/test/java/karate/echo.feature) you can do: `mvn clean test`.
+
+There is also [`json.feature`](src/test/java/karate/json.feature) that can be run as follows: `mvn test -Dtest=JsonRunner`. This shows how the built-in `io.karatelabs.websocket.JsonAdapter` can be used if all messages are known to be JSON.
+
+There is an advanced example: [`stomp.feature`](src/test/java/karate/stomp.feature) that shows how to fully control the flow of messages and the conversion of text (or bytes) to and from JSON in the test. Concepts such as how to implement a message adapter i.e. [`StompAdapter.java`](src/test/java/karate/StompAdapter.java) are explained in the [documentation](https://github.com/karatelabs/karate-addons/tree/main/karate-websocket).
+
+To run the STOMP example, you need to download and start this Spring-Boot based project: [gs-messaging-stomp-websocket
+](https://github.com/spring-guides/gs-messaging-stomp-websocket). The [`/complete`](https://github.com/spring-guides/gs-messaging-stomp-websocket/tree/main/complete) directory has a ready to run Maven project which you can start from the command-line like this:
+
+```
+mvn exec:java -Dexec.mainClass="com.example.messagingstompwebsocket.MessagingStompWebsocketApplication"
+```
+
+You can also open the `complete` project within a Java IDE and run the main class referred in the command above as an alternative.
+
+This will start a local web-app on port 8080 and you can also view a demo web-page at `http://localhost:8080`. Now you can run the Karate test that communicates to the just-started server via STOMP over Websocket like this:
+
+```
+mvn test -Dtest=StompRunner
+```
+
+## Further Reading
+
+Karate has had very basic support for websockets in the open-source version which may suffice for some teams. The following information is available:
+
+* [Documentation](https://github.com/karatelabs/karate#websocket)
+* Examples:
+  * [echo.feature](https://github.com/karatelabs/karate/blob/master/karate-demo/src/test/java/demo/websocket/echo.feature)
+  * [websocket.feature](https://github.com/karatelabs/karate/blob/master/karate-demo/src/test/java/demo/websocket/websocket.feature)
+* [Karate and WebSockets on Stack Overflow](https://stackoverflow.com/search?q=%5Bkarate%5D+websocket)
+* [Using a custom Java implementation if required](https://stackoverflow.com/a/69299321/143475)

websocket/pom.xml

@@ -0,0 +1,64 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+ 
+    <groupId>io.karatelabs.examples</groupId>
+    <artifactId>karate-websocket-example</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <packaging>jar</packaging>
+ 
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <java.version>17</java.version>
+        <maven.compiler.version>3.11.0</maven.compiler.version>
+        <maven.surefire.version>3.0.0</maven.surefire.version>
+        <junit5.version>5.6.2</junit5.version>
+    </properties>    
+
+    <dependencies>         
+        <dependency>
+            <groupId>io.karatelabs</groupId>
+            <artifactId>karate-websocket</artifactId>
+            <version>0.1.0</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>${junit5.version}</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <testResources>
+            <testResource>
+                <directory>src/test/java</directory>
+                <excludes>
+                    <exclude>**/*.java</exclude>
+                </excludes>
+            </testResource>
+        </testResources>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>${maven.compiler.version}</version>
+                <configuration>
+                    <encoding>UTF-8</encoding>
+                    <source>${java.version}</source>
+                    <target>${java.version}</target>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>${maven.surefire.version}</version>
+                <configuration>
+                    <argLine>-Dfile.encoding=UTF-8</argLine>
+                </configuration>
+            </plugin>          
+        </plugins>        
+    </build>                
+    
+</project>

websocket/src/test/java/karate-config.js

@@ -0,0 +1,3 @@
+function fn() {
+
+}

websocket/src/test/java/karate/EchoTest.java

@@ -0,0 +1,17 @@
+package karate;
+
+import com.intuit.karate.Results;
+import com.intuit.karate.Runner;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class EchoTest {    
+    
+    @Test
+    void testFeature() {
+        Results results = Runner.path("classpath:karate/echo.feature").parallel(1);
+        assertEquals(0, results.getFailCount(), results.getErrorMessages());
+    }      
+    
+}

websocket/src/test/java/karate/JsonRunner.java

@@ -0,0 +1,17 @@
+package karate;
+
+import com.intuit.karate.Results;
+import com.intuit.karate.Runner;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class JsonRunner {
+    
+    @Test
+    void testFeature() {
+        Results results = Runner.path("classpath:karate/json.feature").parallel(1);
+        assertEquals(0, results.getFailCount(), results.getErrorMessages());
+    }      
+    
+}

websocket/src/test/java/karate/StompAdapter.java

@@ -0,0 +1,77 @@
+package karate;
+
+import com.intuit.karate.Json;
+import io.karatelabs.websocket.WebsocketAdapter;
+import io.karatelabs.websocket.WebsocketConsumer;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+public class StompAdapter implements WebsocketAdapter<Map<String, Object>, String> {
+
+    @Override
+    public void onMessage(WebsocketConsumer client, Map<String, Object> msg) {
+        client.receive(msg);
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public String toWire(Map<String, Object> map) {
+        String command = (String) map.get("command");
+        Map<String, Object> headers = (Map<String, Object>) map.get("headers");
+        Object body = map.get("body");
+        if (body instanceof Map) {
+            body = Json.of(body).toString();
+        }
+        StringBuilder sb = new StringBuilder();
+        sb.append(command).append('\n');
+        if (headers != null) {
+            headers.forEach((k, v) -> {
+                sb.append(k).append(':').append(v).append('\n');
+            });
+        }
+        sb.append('\n');
+        if (body != null) {
+            sb.append(body);
+        }
+        sb.append('\0');
+        return sb.toString();
+    }
+
+    @Override
+    public Map<String, Object> fromWire(String text) {
+        Map<String, Object> map = new LinkedHashMap<>();
+        String[] lines = text.split("\\R");
+        Map<String, String> headers = new LinkedHashMap<>();
+        boolean headersDone = false;
+        for (String line : lines) {
+            if (map.isEmpty()) {
+                map.put("command", line);
+            } else if (line.isEmpty()) {
+                map.put("headers", headers);
+                headersDone = true;
+            } else if ("\0".equals(line)) {
+                continue;
+            } else {
+                if (headersDone) {
+                    line = line.trim();
+                    if (line.charAt(0) == '{') {
+                        map.put("body", Json.of(line).asMap());
+                    } else {
+                        map.put("body", line);
+                    }
+                } else {
+                    int pos = line.indexOf(':');
+                    if (pos == -1) {
+                        throw new RuntimeException("unexpected header: " + line);
+                    }
+                    String key = line.substring(0, pos);
+                    String value = line.substring(pos + 1);
+                    headers.put(key, value);
+                }
+            }
+        }
+        return map;
+    }
+
+}

websocket/src/test/java/karate/StompRunner.java

@@ -0,0 +1,17 @@
+package karate;
+
+import com.intuit.karate.Results;
+import com.intuit.karate.Runner;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class StompRunner {
+    
+    @Test
+    void testFeature() {
+        Results results = Runner.path("classpath:karate/stomp.feature").parallel(1);
+        assertEquals(0, results.getFailCount(), results.getErrorMessages());
+    }      
+    
+}

websocket/src/test/java/karate/echo.feature

@@ -0,0 +1,11 @@
+Feature: demo plain-text
+
+  Scenario:
+    * def session = karate.channel('websocket')
+    * session.url = 'wss://ws.postman-echo.com/raw'
+    * session.start()
+
+    * session.send('hello')
+
+    * def response = session.collect()
+    * match response == ['hello']

websocket/src/test/java/karate/json.feature

@@ -0,0 +1,13 @@
+Feature: demo auto-conversion to json
+
+  Scenario:
+    * def session = karate.channel('websocket')
+    * session.url = 'wss://ws.postman-echo.com/raw'
+    * def Adapter = Java.type('io.karatelabs.websocket.JsonAdapter')
+    * session.adapter = new Adapter()
+    * session.start()
+
+    * session.send({ message: 'hello' })
+
+    * def response = session.collect()
+    * match response == [{ message: 'hello' }]

websocket/src/test/java/karate/stomp.feature

@@ -0,0 +1,31 @@
+Feature: tests the following spring-websocket example
+  https://github.com/spring-guides/gs-messaging-stomp-websocket
+
+  Background:
+    * def result =
+      """
+      function(name) {
+        var session = karate.get('session');
+        var message = { command: 'SEND', headers: { destination: '/app/hello' }, body: { name: name } };
+        session.send(message);
+        var response = session.pop();
+        return response.body.content;
+      }
+      """
+
+  Scenario:
+    * def session = karate.channel('websocket')
+    * session.url = 'ws://localhost:8080/gs-guide-websocket'
+    * def Adapter = Java.type('karate.StompAdapter')
+    * session.adapter = new Adapter()
+    * session.start()
+    * session.send({ command: 'CONNECT', headers: { 'accept-version': '1.2', 'heart-beat': '0,0' } })
+    * match session.pop() contains { command: 'CONNECTED' }
+    * session.send({ command: 'SUBSCRIBE', headers: { id: 'sub-0', destination: '/topic/greetings' } })
+
+    * match result('foo') == 'Hello, foo!'
+    * match result('bar') == 'Hello, bar!'
+
+    * session.send({ command: 'DISCONNECT', headers: { receipt: 'disc-0' } })
+    * match session.pop() contains { command: 'RECEIPT', headers: { 'receipt-id': 'disc-0' } }
+    * session.stop()

websocket/src/test/java/logback-test.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+ 
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+        </encoder>
+    </appender>
+  
+    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
+        <file>target/karate.log</file>
+        <encoder>
+            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+        </encoder>
+    </appender>    
+   
+    <logger name="com.intuit" level="DEBUG"/>
+    <logger name="io.karatelabs" level="DEBUG"/>
+   
+    <root level="warn">
+        <appender-ref ref="STDOUT" />
+        <appender-ref ref="FILE" />
+    </root>
+  
+</configuration>