Testing Framework

This page documents the testing framework used in the SpeechRecognition library. It describes the testing infrastructure, test organization, continuous integration setup, and provides guidance on how to run and extend the test suite. For information about building and deploying the library, see Building and Deployment.

Overview

The SpeechRecognition library employs a comprehensive testing approach that combines unit tests for individual components and integration tests for verifying functionality across various speech recognition services. The testing infrastructure is built on both the Python standard library's unittest framework and pytest.

Sources: tests/test_recognition.py1-7 tests/test_special_features.py1-7 .github/workflows/unittests.yml59-61

Test Architecture

The testing framework is organized around two primary concepts:

1. Unit tests: Verify individual components of the library
2. Recognition service tests: Verify integration with various speech recognition services

Sources: tests/test_recognition.py10-84 tests/test_special_features.py10-31

Test Organization

The test files are organized in a dedicated tests directory with individual test files focusing on specific aspects of the library's functionality.

Sources: tests/__init__.py1-2 tests/test_recognition.py12-15 tests/test_special_features.py12-13

Continuous Integration Setup

The SpeechRecognition library uses GitHub Actions for continuous integration, automatically running tests on both pull requests and merges to the master branch.

Sources: .github/workflows/unittests.yml3-61 .github/workflows/lint.yml1-19 .github/workflows/rstcheck.yml1-19

Test Types

Unit Tests for Recognizer Attributes

The basic unit tests verify that the Recognizer class has the expected attributes with proper default values.

Sources: tests/test_recognition.py17-30

Speech Recognition Service Tests

These tests verify integration with different speech recognition services/engines. Many tests are conditionally skipped if API keys or specific environments are not available.

Service	Test Method	Conditional Execution
Sphinx	test_sphinx_english()	Skips on Windows
Wit.ai	test_wit_english()	Requires WIT_AI_KEY
Bing	test_bing_english(), test_bing_french(), test_bing_chinese()	Requires BING_KEY
Houndify	test_houndify_english()	Requires HOUNDIFY_CLIENT_ID and HOUNDIFY_CLIENT_KEY
IBM	test_ibm_english(), test_ibm_french(), test_ibm_chinese()	Requires IBM_USERNAME and IBM_PASSWORD

Sources: tests/test_recognition.py32-84

Special Feature Tests

Tests for specialized features such as keyword recognition.

Sources: tests/test_special_features.py10-31

Test Dependencies

The testing framework requires several dependencies defined in the setup.cfg file under the dev extras:

pytest
pytest-randomly
respx
numpy

Additionally, various optional dependencies are required for testing specific recognition engines:

Extra	Purpose	Dependencies
audio	PyAudio for microphone access	PyAudio >= 0.2.11
pocketsphinx	Offline recognition	pocketsphinx
google-cloud	Google Cloud Speech API	google-cloud-speech
whisper-local	Local Whisper model	openai-whisper, soundfile
faster-whisper	Faster Whisper implementation	faster-whisper
openai	OpenAI API integration	openai, httpx < 0.28
groq	Groq API integration	groq, httpx < 0.28

Sources: setup.cfg1-26

Running Tests

Local Test Execution

To run the full test suite locally, first install the required dependencies:

Then run the tests using pytest:

For tests that require API credentials, set the appropriate environment variables before running the tests.

Sources: .github/workflows/unittests.yml48-58 .github/workflows/unittests.yml59-61

Test Execution Flow

Sources: tests/test_recognition.py10-84 tests/test_special_features.py10-31

Extending the Test Suite

When adding new features or modifying existing functionality, consider these guidelines for extending the test suite:

1. Add new test files in the tests/ directory for substantial new features
2. Add test methods to existing test classes for modifications to existing features
3. Provide test audio files for new recognition services or language support

For testing with services requiring API keys, use environment variables and conditional test execution to avoid test failures when credentials are not available.

Sources: tests/test_recognition.py38-82

Test Data

The test suite uses several audio files for testing recognition in different languages:

Filename	Format	Language	Content
english.wav	WAV	English	"one two three"
french.aiff	AIFF	French	"Essaye la dictée numéro un"
chinese.flac	FLAC	Chinese	"砸自己的脚"

Sources: tests/test_recognition.py12-15 tests/test_special_features.py12-13

Custom Assertions

The test suite includes custom assertion methods to handle specific validation needs:

• assertSameWords: Compares two strings by checking if they contain the same set of words, regardless of order.

Sources: tests/test_special_features.py26-30