@telnyx/voice-agent-tester 0.2.0

package/.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Code owners for voice-agent-tester
+# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+* @lucasassisrosa

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+        env:
+          CI: true

package/.github/workflows/draft-release.yml

@@ -0,0 +1,72 @@
+name: Draft release
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git ref (branch or tag) to draft from"
+        required: false
+        default: "main"
+      prerelease:
+        description: "Pre-release identifier"
+        required: false
+        default: "none"
+        type: choice
+        options:
+          - none
+          - alpha
+          - beta
+          - rc
+      increment:
+        description: "Version bump (only if prerelease is 'none')"
+        required: false
+        default: "patch"
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+jobs:
+  draft:
+    name: "@telnyx/voice-agent-tester Draft release"
+    runs-on: ubuntu-latest
+
+    env:
+      TARGET_REF: ${{ github.event.inputs.ref || 'main' }}
+      PRERELEASE_ARGS: ${{ github.event.inputs.prerelease && github.event.inputs.prerelease != 'none' && format(' --preRelease={0} --github.preRelease', github.event.inputs.prerelease) || '' }}
+      INCREMENT_ARG: ${{ github.event.inputs.prerelease && github.event.inputs.prerelease != 'none' && ' --increment=prerelease' || github.event.inputs.increment && format(' --increment={0}', github.event.inputs.increment) || '' }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.TARGET_REF }}
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Git user
+        run: |
+          git config user.name TelnyxIntegrations
+          git config user.email integrations@telnyx.com
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+        env:
+          CI: true
+
+      - name: Create draft release
+        run: |
+          npx release-it --ci --github.draft --no-npm.publish${{ env.INCREMENT_ARG }}${{ env.PRERELEASE_ARGS }}
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_CI_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/publish-release.yml

@@ -0,0 +1,39 @@
+name: Publish release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    if: github.event.release.prerelease == false
+    name: "@telnyx/voice-agent-tester Publish release"
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: "main"
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Git user
+        run: |
+          git config user.name TelnyxIntegrations
+          git config user.email integrations@telnyx.com
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish package
+        run: npm publish --access public
+        env:
+          CI: true
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_CI_TOKEN }}

package/.release-it.json

@@ -0,0 +1,31 @@
+{
+  "git": {
+    "commitMessage": "chore: release v${version}",
+    "tagAnnotation": "Release v${version}",
+    "tagName": "v${version}"
+  },
+  "github": {
+    "release": true,
+    "releaseName": "v${version}"
+  },
+  "npm": {
+    "publish": false
+  },
+  "plugins": {
+    "@release-it/conventional-changelog": {
+      "preset": {
+        "name": "conventionalcommits",
+        "types": [
+          { "type": "feat", "section": "Features" },
+          { "type": "fix", "section": "Bug Fixes" },
+          { "type": "perf", "section": "Performance Improvements" },
+          { "type": "docs", "section": "Documentation" },
+          { "type": "refactor", "section": "Code Refactoring" },
+          { "type": "test", "section": "Tests" },
+          { "type": "chore", "section": "Chores" }
+        ]
+      },
+      "infile": "CHANGELOG.md"
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.2.0 (2026-01-16)
+
+### Features
+
+* add debug flag for diagnostic and increase timeout limit ([fb3874b](https://github.com/team-telnyx/voice-agent-tester/commit/fb3874b5531a5237757fe2e9f218a095d8cf6dee))
+* add default telnyx widget options ([d62e74f](https://github.com/team-telnyx/voice-agent-tester/commit/d62e74f1e0bdacff49dab67595a866110be861a4))
+* add dynamic params support ([57397f2](https://github.com/team-telnyx/voice-agent-tester/commit/57397f20c6aecafcf0aef89c1699ff6ebee2e839))
+* add elevenlabs provider ([d605f22](https://github.com/team-telnyx/voice-agent-tester/commit/d605f2260d78755bbe1c4f64d8f283f2167cc194))
+* add release process ([acbffc2](https://github.com/team-telnyx/voice-agent-tester/commit/acbffc23efdcd2aa325049b940a94c3dc09694bb))
+* add vapi application along ([a712397](https://github.com/team-telnyx/voice-agent-tester/commit/a7123972de82df52d0b45126159b5afa32afabfd))
+* add workflow files ([f950bcf](https://github.com/team-telnyx/voice-agent-tester/commit/f950bcf7cd80994e74158347c674a49baa338ca2))
+* automatically create integration secret ([e043e5a](https://github.com/team-telnyx/voice-agent-tester/commit/e043e5a9dd2df9453bc6b1a872a29b93d62779cc))
+* handle dynamic provider param fields requirements ([4bdc7b0](https://github.com/team-telnyx/voice-agent-tester/commit/4bdc7b0ff2a8049836552fc5f59b6ab2dbb28e17))
+* initial benchmark setup for telnyx voice ai ([8233c96](https://github.com/team-telnyx/voice-agent-tester/commit/8233c963ba3f7fe933c0f97d14e7c07146f1faf4))
+* make provider required ([48ad25d](https://github.com/team-telnyx/voice-agent-tester/commit/48ad25d8c92acbd375ae23feade69cb8deb7dd2c))
+* refactor naming ([b6857d9](https://github.com/team-telnyx/voice-agent-tester/commit/b6857d95e48c247287b6ae1ef713c62b889a4b34))
+* release prepare ([8b78136](https://github.com/team-telnyx/voice-agent-tester/commit/8b7813697f4dc25beef4e9f0153d74888783f3e2))
+* remove unused code ([42e2908](https://github.com/team-telnyx/voice-agent-tester/commit/42e2908720335541733c0e5eef68bba88139293a))
+* update benchmark providers ([55623ba](https://github.com/team-telnyx/voice-agent-tester/commit/55623ba713b9dbb4ddf0abcd51d3be58dc5d5b8a))
+* update benchmarking setup ([8b7eb5d](https://github.com/team-telnyx/voice-agent-tester/commit/8b7eb5d7e97d24ddd010c440851e97cb29a166e9))
+* update model on telnyx import for better latency ([bbe941f](https://github.com/team-telnyx/voice-agent-tester/commit/bbe941fc0c8acdb158c3275685027084431ab2ed))
+* update parameters usage on provider choice ([8e2def5](https://github.com/team-telnyx/voice-agent-tester/commit/8e2def5f701e679ce6e9b8fcad2c71c57b96d372))
+* update params ([62c79b0](https://github.com/team-telnyx/voice-agent-tester/commit/62c79b0f22b9729c6e4ae8b8defb4502fb85fa57))
+* update params and logic on import ([03142fb](https://github.com/team-telnyx/voice-agent-tester/commit/03142fb143d9981c09298beff19408ab42825676))
+
+### Bug Fixes
+
+* update logs in benchmark app ([26a238d](https://github.com/team-telnyx/voice-agent-tester/commit/26a238ddf0077868da1d877b7d9e89b17b5f7b50))

package/CLAUDE.md

@@ -0,0 +1,72 @@
+# Voice Agent Tester - Development Guidelines
+
+## Design Overview
+
+### Purpose
+A CLI tool for automated testing of voice agents using Puppeteer. It executes test scenarios against voice-enabled web applications, records audio/video, transcribes responses, and evaluates them using AI.
+
+### Architecture
+
+```
+src/
+├── index.js              # CLI entry point (yargs argument parsing)
+├── voice-agent-tester.js # Core test execution engine
+├── report.js             # CSV report generation
+├── server.js             # Express assets server
+└── transcription.js      # OpenAI Whisper transcription
+
+javascript/               # Browser-injected scripts for audio hooks
+applications/             # Application YAML configs
+scenarios/                # Scenario YAML configs
+output/                   # Recordings and reports
+```
+
+### Key Components
+
+- **VoiceAgentTester**: Main class that launches browser, executes steps, handles events
+- **ReportGenerator**: Tracks metrics and generates CSV reports
+- **Assets Server**: Serves audio files and temporary HTML pages
+
+### Test Execution Flow
+
+1. Parse CLI arguments and load YAML configs
+2. Create combinations of applications × scenarios
+3. For each test run:
+   - Launch browser (with puppeteer-stream for recording)
+   - Navigate to application URL
+   - Inject audio hook scripts
+   - Execute application steps then scenario steps
+   - Record metrics and save recordings
+   - Close browser
+
+### Event System
+
+Browser-to-Node communication via `__publishEvent()`:
+- `audiostart` / `audiostop` - Voice activity detection
+- `speechend` - TTS completion
+- `recordingstart` / `recordingcomplete` - Audio recording lifecycle
+
+## Coding Standards
+
+- Use simple JavaScript (ES modules)
+- Keep functions short and focused
+- Prefer async/await over callbacks
+- Use descriptive variable and function names
+
+## Testing
+
+- Avoid using mocks as much as possible
+- Write unit tests for methods without dependencies
+- Write integration tests for all features and CLI flags
+- Tests should be self-contained and not require external services
+
+## Dependencies
+
+- Only add new dependencies when truly necessary
+- Prefer built-in Node.js modules when available
+
+## Git Commits
+
+- Use single-line commit messages
+- Keep messages concise and descriptive
+- Focus on what changed, not implementation details

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Telnyx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# Voice Agent Tester (Telnyx Fork)
+
+[![CI](https://github.com/team-telnyx/voice-agent-tester/actions/workflows/ci.yml/badge.svg)](https://github.com/team-telnyx/voice-agent-tester/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@telnyx/voice-agent-tester.svg)](https://www.npmjs.com/package/@telnyx/voice-agent-tester)
+
+This is a [Telnyx](https://telnyx.com) fork of [livetok-ai/voice-agent-tester](https://github.com/livetok-ai/voice-agent-tester). For base documentation (installation, configuration, actions, etc.), see the [original README](https://github.com/livetok-ai/voice-agent-tester#readme).
+
+## Installation
+
+```bash
+npm install @telnyx/voice-agent-tester
+```
+
+## Fork Enhancements
+
+### CLI Options
+| Option | Description |
+|--------|-------------|
+| `--assistant-id` | Assistant/agent ID for direct benchmarking (Telnyx, ElevenLabs, Vapi) |
+| `--api-key` | Telnyx API key for authentication and import operations |
+| `--provider` | Import from external provider (`vapi`, `elevenlabs`, `retell`) into Telnyx |
+| `--provider-api-key` | External provider API key (required with `--provider`) |
+| `--provider-import-id` | Provider assistant/agent ID to import (required with `--provider`) |
+| `--params` | Additional URL template params (e.g., `--params branchId=xxx,shareKey=yyy`) |
+| `--debug` | Enable detailed timeout diagnostics with WebRTC stats |
+
+### Multi-Provider Support
+- **Direct benchmarking**: Use `--assistant-id` with any provider's YAML config
+- **Provider import**: Import assistants from Vapi/ElevenLabs/Retell into Telnyx via `--provider`
+- **Auto-configuration**: Automatic integration secret management and web call enablement
+
+### Debug & Diagnostics
+When `--debug` is enabled, timeout events include WebRTC RTP statistics (packets received, bytes transferred, jitter, packet loss).
+
+## Usage Examples
+
+### Telnyx Assistant (Direct)
+
+Benchmark a Telnyx AI assistant directly using the Telnyx widget:
+
+```bash
+npm run start -- \
+  -a benchmarks/applications/telnyx.yaml \
+  -s benchmarks/scenarios/appointment.yaml \
+  --assistant-id <TELNYX_ASSISTANT_ID>
+```
+
+### ElevenLabs Agent (Direct)
+
+Benchmark an ElevenLabs conversational agent. Use `--params` for optional `branchId`:
+
+```bash
+npm run start -- \
+  -a benchmarks/applications/elevenlabs.yaml \
+  -s benchmarks/scenarios/appointment.yaml \
+  --assistant-id <ELEVENLABS_AGENT_ID> \
+  --params branchId=<BRANCH_ID>
+```
+
+### Vapi Assistant (Direct)
+
+Benchmark a Vapi assistant using their embedded widget. Requires `shareKey` via `--params`:
+
+```bash
+npm run start -- \
+  -a benchmarks/applications/vapi.yaml \
+  -s benchmarks/scenarios/appointment.yaml \
+  --assistant-id <VAPI_ASSISTANT_ID> \
+  --params shareKey=<SHARE_KEY>
+```
+
+### Import from Provider to Telnyx
+
+Import an assistant from an external provider (Vapi, ElevenLabs, Retell) into Telnyx and benchmark:
+
+```bash
+npm run start -- \
+  -a benchmarks/applications/telnyx.yaml \
+  -s benchmarks/scenarios/appointment.yaml \
+  --provider vapi \
+  --api-key <TELNYX_API_KEY> \
+  --provider-api-key <VAPI_API_KEY> \
+  --provider-import-id <VAPI_ASSISTANT_ID>
+```
+
+- `--api-key`: Your Telnyx API key (for creating the import)
+- `--provider-api-key`: The external provider's API key (for fetching the assistant)
+- `--provider-import-id`: The assistant ID from the provider to import
+
+## License
+
+MIT

package/assets/recording-processor.js

@@ -0,0 +1,86 @@
+// Check if we're in the AudioWorklet context
+if (typeof AudioWorkletProcessor !== 'undefined') {
+
+class RecordingProcessor extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.isRecording = false;
+    this.recordedBuffers = [];
+    
+    // Listen for messages from the main thread
+    this.port.onmessage = (event) => {
+      const { command } = event.data;
+      
+      switch (command) {
+        case 'start':
+          this.startRecording();
+          break;
+        case 'stop':
+          this.stopRecording();
+          break;
+      }
+    };
+  }
+  
+  startRecording() {
+    this.isRecording = true;
+    this.recordedBuffers = [];
+    console.log('AudioWorklet: Recording started');
+  }
+  
+  stopRecording() {
+    this.isRecording = false;
+    
+    // Combine all recorded buffers
+    const totalLength = this.recordedBuffers.reduce((acc, buffer) => acc + buffer.length, 0);
+    const combinedBuffer = new Float32Array(totalLength);
+    
+    let offset = 0;
+    for (const buffer of this.recordedBuffers) {
+      combinedBuffer.set(buffer, offset);
+      offset += buffer.length;
+    }
+    
+    // Send the recorded data back to the main thread
+    this.port.postMessage({
+      command: 'recordingComplete',
+      audioData: combinedBuffer,
+      sampleRate: sampleRate
+    });
+    
+    this.recordedBuffers = [];
+    console.log('AudioWorklet: Recording stopped, data sent to main thread');
+  }
+  
+  process(inputs, outputs, parameters) {
+    const input = inputs[0];
+    const output = outputs[0];
+    
+    // Pass audio through (input to output)
+    if (input.length > 0 && output.length > 0) {
+      const inputChannel = input[0];
+      const outputChannel = output[0];
+      
+      // Copy input to output to maintain audio flow
+      for (let i = 0; i < inputChannel.length; i++) {
+        outputChannel[i] = inputChannel[i];
+      }
+      
+      // Record audio if recording is active
+      if (this.isRecording && inputChannel.length > 0) {
+        const buffer = new Float32Array(inputChannel.length);
+        buffer.set(inputChannel);
+        this.recordedBuffers.push(buffer);
+      }
+    }
+    
+    // Keep the processor alive
+    return true;
+  }
+}
+
+registerProcessor('recording-processor', RecordingProcessor);
+
+} else {
+  console.warn('AudioWorkletProcessor not available - this module should only be loaded in an AudioWorklet context');
+}

package/benchmarks/applications/elevenlabs.yaml

@@ -0,0 +1,10 @@
+url: "https://elevenlabs.io/app/talk-to?agent_id={{assistantId}}&branch_id={{branchId}}"
+steps:
+  - action: wait_for_element
+    selector: "button[data-agent-id]"
+  - action: sleep
+    time: 3000
+  - action: click
+    selector: "button[data-agent-id]"
+  - action: sleep
+    time: 2000

package/benchmarks/applications/telnyx.yaml

@@ -0,0 +1,10 @@
+url: "https://portal.telnyx.com/#/ai-widget-demo?assistantId={{assistantId}}"
+steps:
+  - action: wait_for_element
+    selector: "telnyx-ai-agent"
+  - action: sleep
+    time: 3000
+  - action: click
+    selector: "telnyx-ai-agent"
+  - action: sleep
+    time: 4000

package/benchmarks/applications/vapi.yaml

@@ -0,0 +1,10 @@
+url: "https://vapi.ai/?demo=true&shareKey={{shareKey}}&assistantId={{assistantId}}"
+steps:
+  - action: wait_for_element
+    selector: "button[aria-label='Talk to Vapi']"
+  - action: sleep
+    time: 3000
+  - action: click
+    selector: "button[aria-label='Talk to Vapi']"
+  - action: sleep
+    time: 2000

package/benchmarks/scenarios/appointment.yaml

@@ -0,0 +1,16 @@
+tags:
+  - default
+steps:
+  - action: wait_for_voice
+  - action: wait_for_silence
+  - action: sleep
+    time: 1000
+  - action: speak
+    file: hello_make_an_appointment.mp3
+  - action: wait_for_voice
+    metrics: elapsed_time
+  - action: wait_for_silence
+  - action: speak
+    file: appointment_data.mp3
+  - action: wait_for_voice
+    metrics: elapsed_time