Skip to content

stubs

This directory contains mock implementations of the Talon Voice API. Since the native Talon Voice application runner is closed-source and only available within its active runtime environment, executing unit tests or static analysis tools (such as in a continuous integration pipeline or local terminal) would normally fail with a ModuleNotFoundError.

These stubs isolate the test environment by providing a safe, mock interface that mimics Talon's core and experimental APIs, allowing community scripts to be imported, analyzed, and tested without running the actual Talon application.

Integration and Core Configuration

The stubs are designed to seamlessly intercept Python's import system during testing:

  • README: Explains that the directory is injected into the Python import path (sys.path) via pytest's pythonpath configuration (defined in pyproject.toml). This ensures that when a test executes import talon, Python loads these mock definitions rather than searching for the native runtime. While many of the stubs act as simple no-ops to prevent crashes, others (like the action system) provide functional behavior to enable unit testing and introspection.

Subdirectories and Components

talon

This is the primary mock entry point for the talon package. It stubs out the foundational components of the Talon API:

  • Actions Management: Implements mock Actions and RegisteredActionsAccessor classes to mimic Talon's action dispatching system. It provides basic built-in actions (e.g., key, insert, sleep) and allows tests to register custom actions and reset them between runs.
  • Modules and Contexts: Provides dummy Module and Context classes. The Module.action_class decorator automatically registers user-defined action classes into the mock Actions system.
  • UI, Settings, and Resources: Stubs out components like configuration registries, UI frameworks, and application environment parameters (e.g., defaulting the platform to "mac" during tests).
  • Environment Flag: Exposes a test_mode = True flag, which allows user scripts to detect if they are running inside a test runner and adjust their behavior dynamically.
  • Grammar Engine: Stubs out classes like Phrase so that runtime type checks or annotations do not raise reference errors.

talon/experimental

This subdirectory provides mock representations for Talon's experimental APIs, ensuring that scripts leveraging newer or unstable features can still be tested:

  • Experimental UI Components: Stubs out objects in the talon.experimental.textarea namespace (such as TextArea, Span, DarkThemeLabels, and LightThemeLabels). By defining these complex graphical elements as safe defaults (like None), user scripts that import them can compile and initialize successfully in non-GUI (headless) test environments.

How the Stubs Work Together

When you run a test suite against your Talon scripts:

  1. Path Interception: pytest prepends this directory to the Python import path.
  2. Module Registration: When your scripts execute from talon import Module, Context, the stubbed classes in talon are loaded.
  3. Action Discovery: As your script defines custom actions using @mod.action_class, the mock Module class intercepts these declarations and registers them into a central, in-memory actions registry.
  4. Experimental Safeguards: If your script utilizes advanced user interface elements, the imports are resolved through talon/experimental without trying to spin up a graphical rendering engine.
  5. Assertion and Introspection: Your unit tests can now safely call user-defined actions, mock specific behavior, and verify that the scripts execute the expected logical paths.