Skip to content

test

This directory contains the unit test suite and the supporting mock environment for the Talon Voice community scripts.

Because the native Talon Voice runtime environment is closed-source and unavailable outside of the running application, executing static analysis tools or unit tests on community scripts directly in a local terminal or continuous integration (CI) pipeline would normally fail with a ModuleNotFoundError. To solve this, this directory implements a set of custom mock stubs and isolated test files that bypass this limitation, allowing safe, headless validation of script logic.

The Testing Infrastructure

Testing Talon scripts requires intercepting and simulating the environment that Talon's core engine usually provides. This is managed through localized stub packages:

  • stubs: Acts as the primary integration layer that intercepts Python's import system. By using pytest's configuration to append this directory to the Python import path (sys.path), test runs import these mock interfaces instead of seeking the native application.
  • stubs/talon: Provides the concrete core mock implementations. It stubs out foundational Talon classes—such as Module, Context, Settings, and the speech parsing Phrase structure in grammar.py—and injects a central, in-memory actions registry (Actions). This mock setup exposes a test_mode = True flag, allowing user scripts to verify whether they are operating inside a test runner.
  • stubs/talon/experimental: Safely stubs out newer and experimental UI components like TextArea and Span. By defining these complex graphical layout interfaces as safe defaults (e.g., None), scripts using them can be imported and parsed in non-GUI, headless testing systems.

Unit Test Modules

The test files in this directory focus on validating core utilities, formatters, text processing, and helper functions. They conditionally run their tests by checking for the talon.test_mode attribute to ensure they only execute within the testing environment.

Action Delegation and Modification

  • test_code_modified_function.py validates that modifier keywords (such as ["private", "static"] or ["protected"]) are routed to their appropriate target actions correctly. It utilizes standard Python mock libraries (MagicMock) integrated with the stubbed action dispatch system to assert that the dispatcher invokes the expected sub-actions.

Text Formatting & Dictation Engine

  • test_formatters.py asserts the correctness of Talon's text formatting rules. It tests standard code conventions like SNAKE_CASE or NO_SPACES, as well as complex prose transformations like CAPITALIZE_ALL_WORDS (which must respect grammatical boundaries, hyphens, and contractions).
  • test_dictation.py checks the spacing, punctuation, and capitalization logic of the dictation engine. It ensures that subsequent words receive appropriate spacing or auto-capitalization based on prior grammatical states (e.g., following periods, newlines, or parenthesis).

Dynamic Spoken Form Generation

  • test_create_spoken_forms.py tests the algorithm that generates pronounceable words and phrases from code symbols, file extensions, and abbreviations (e.g., translating .cs to "dot see sharp", or expanding "README" to "read me"). It isolates testing from the active filesystem by dynamically overriding Talon's CSV tracker implementation (track_csv_list) with custom memory structures.

Snippet Management

  • test_snippet_body_formatting.py tests the parser utility responsible for standardizing snippet bodies. Specifically, it verifies that final cursor tabstops ($0) are automatically and correctly placed at the end of snippets if missing, and that complex tabstop nested braces are parsed safely.

How the Components Work Together

When a developer or a CI workflow executes pytest inside this repository:

  1. Path Resolution: The stubs inside the stubs directory are loaded first. Any test file or community script that runs import talon resolves to the mock implementations.
  2. Mock Initialization: Custom actions defined inside user scripts register themselves via @mod.action_class with the mock Module registry inside stubs/talon.
  3. Isolation and Setup: Individual tests setup their specific dependencies. For example, test_create_spoken_forms.py overrides user-settings decorators to bypass file reading, and test_code_modified_function.py registers custom test actions to intercept call structures.
  4. Assertion: The test suite evaluates the core formatting, dictation, modifier logic, and spoken form algorithms, utilizing mock assertions and standard test cases to guarantee that system utilities operate deterministically.