feat: add --expect-text, --fail-text and --timeout

Author: urish

src/ExpectEngine.ts

@@ -0,0 +1,42 @@
+import { EventEmitter } from 'events';
+
+export class ExpectEngine extends EventEmitter {
+  readonly expectTexts: string[] = [];
+  readonly failTexts: string[] = [];
+
+  private currentLine = '';
+
+  onMatch(type: 'match' | 'fail', text: string) {
+    this.emit(type, text);
+  }
+
+  feed(bytes: number[]) {
+    if (this.expectTexts.length === 0 && this.failTexts.length === 0) {
+      return;
+    }
+    for (const byte of bytes) {
+      const char = String.fromCharCode(byte);
+      if (char === '\n') {
+        this.testMatches();
+        this.currentLine = '';
+      } else {
+        if (this.currentLine.length < 10_000) {
+          this.currentLine += char;
+        }
+      }
+    }
+  }
+
+  private testMatches() {
+    for (const candidate of this.expectTexts) {
+      if (this.currentLine.includes(candidate)) {
+        this.onMatch('match', candidate);
+      }
+    }
+    for (const candidate of this.failTexts) {
+      if (this.currentLine.includes(candidate)) {
+        this.onMatch('fail', candidate);
+      }
+    }
+  }
+}

src/help.ts

@@ -9,5 +9,15 @@ export function cliHelp() {
   {bold OPTIONS}
       {green --help}, {green -h}                  Shows this help message and exit
       {green --quiet}, {green -q}                 Quiet: do not print version or status messages
+      {green --expect-text} <string>      Expect the given text in the output
+      {green --fail-text} <string>        Fail if the given text is found in the output
+      {green --timeout} <number>          Timeout in simulation milliseconds (default: 0 = none)
+
+  {bold EXAMPLES}
+
+      Running a simulation for 5 seconds, and expecting "Hello World" in the output (assuming wokwi.toml in the current directory):
+
+      {dim $} {bold wokwi-cli} {green --timeout} 5000 {green --expect-text} "Hello World"
+  
 `);
 }

src/main.ts

@@ -1,25 +1,35 @@
 import arg from 'arg';
+import chalk from 'chalk';
 import { existsSync, readFileSync } from 'fs';
 import path, { join } from 'path';
 import { APIClient } from './APIClient';
 import type { APIEvent, SerialMonitorDataPayload } from './APITypes';
 import { parseConfig } from './config';
-import { readVersion } from './readVersion';
 import { cliHelp } from './help';
+import { readVersion } from './readVersion';
+import { ExpectEngine } from './ExpectEngine';
 
 async function main() {
   const args = arg(
     {
       '--help': Boolean,
       '--quiet': Boolean,
       '--version': Boolean,
+      '--expect-text': String,
+      '--fail-text': String,
+      '--timeout': Number,
       '-h': '--help',
       '-q': '--quiet',
     },
     { argv: process.argv.slice(2) }
   );
 
   const quiet = args['--quiet'];
+  const expectText = args['--expect-text'];
+  const failText = args['--fail-text'];
+  const timeout = args['--timeout'] ?? 0;
+  const timeoutNanos = timeout * 1_000_000;
+
   if (!quiet) {
     const { sha, version } = readVersion();
     console.log(`Wokwi CLI v${version} (${sha})`);
@@ -69,6 +79,28 @@ async function main() {
     process.exit(1);
   }
 
+  const expectEngine = new ExpectEngine();
+
+  if (expectText) {
+    expectEngine.expectTexts.push(expectText);
+    expectEngine.on('match', (text) => {
+      if (!quiet) {
+        console.log(chalk`\n\nExpected text found: {green "${expectText}"}`);
+        console.log('TEST PASSED.');
+      }
+      process.exit(0);
+    });
+  }
+
+  if (failText) {
+    expectEngine.failTexts.push(failText);
+    expectEngine.on('fail', (text) => {
+      console.error(chalk`\n\n{red Error:} Unexpected text found: {yellow "${text}"}`);
+      console.error('TEST FAILED.');
+      process.exit(1);
+    });
+  }
+
   const client = new APIClient(token);
   client.onConnected = (hello) => {
     if (!quiet) {
@@ -85,13 +117,24 @@ async function main() {
   }
 
   await client.serialMonitorListen();
-  await client.simStart({ elf: 'test.elf', firmware: 'firmware' });
+  await client.simStart({ elf: 'test.elf', firmware: 'firmware', pause: timeoutNanos > 0 });
+  if (timeout > 0) {
+    await client.simResume(timeoutNanos);
+  }
 
   client.onEvent = (event) => {
+    if (event.event === 'sim:pause') {
+      if (timeoutNanos && event.nanos >= timeoutNanos) {
+        console.error(`Timeout: simulation did not finish in ${timeout}ms`);
+        process.exit(42);
+      }
+    }
     if (event.event === 'serial-monitor:data') {
-      for (const byte of (event as APIEvent<SerialMonitorDataPayload>).payload.bytes) {
+      const { bytes } = (event as APIEvent<SerialMonitorDataPayload>).payload;
+      for (const byte of bytes) {
         process.stdout.write(String.fromCharCode(byte));
       }
+      expectEngine.feed(bytes);
     }
   };
 }