psychopy 2025.2.4__py3-none-any.whl

psychopy/tests/test_tools/test_stringtools.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""Tests for psychopy.tools.mathtools
+"""
+
+from psychopy.tools import stringtools as tools
+import pytest
+
+@pytest.mark.stringtools
+def test_name_wrap():
+    cases = [
+        {"text": "Hello There", "wrap": 12, "ans": "Hello There"},  # No wrap
+        {"text": "Hello There", "wrap": 8, "ans": "Hello \nThere"},  # Basic wrap
+        {"text": "Hello There Hello There Hello There", "wrap": 11, "ans": "Hello There \nHello There \nHello There"},  # Multiple wraps
+        {"text": "Eyetracker Calibration", "wrap": 10, "ans": "Eyetracker \nCalibratio-\nn"},  # One word longer than wrap length
+    ]
+    for case in cases:
+        assert tools.wrap(case['text'], case['wrap']) == case['ans']
+
+
+@pytest.mark.stringtools
+def test_get_variables():
+    exemplars = [
+        {"code": "x=1\ny=2", "ans": {'x': 1, 'y': 2}},  # numbers
+        {"code": "x=\"a\"\ny=\"b\"", "ans": {'x': "a", 'y': "b"}},  # double quotes
+        {"code": "x='a'\ny='b'", "ans": {'x': "a", 'y': "b"}},  # single quotes
+        {"code": "x=(1, 2)\ny=(3, 4)", "ans": {'x': (1, 2), 'y': (3, 4)}},  # arrays
+    ]
+    tykes = [
+        {"code": "x='(1, 2)'\ny='(3, 4)'", "ans": {'x': "(1, 2)", 'y': "(3, 4)"}},  # string representation of array (single)
+        {"code": "x=\"(1, 2)\"\ny=\"(3, 4)\"", "ans": {'x': "(1, 2)", 'y': "(3, 4)"}},  # string representation of array (double)
+    ]
+    for case in exemplars + tykes:
+        assert tools.getVariableDefs(case['code']) == case['ans']
+
+
+@pytest.mark.stringtools
+def test_get_arguments():
+    exemplars = [
+        {"code": "x=1,y=2", "ans": {'x': 1, 'y': 2}},  # numbers
+        {"code": "x=\"a\",y=\"b\"", "ans": {'x': "a", 'y': "b"}},  # double quotes
+        {"code": "x='a',y='b'", "ans": {'x': "a", 'y': "b"}},  # single quotes
+        {"code": "x=(1, 2), y=(3, 4)", "ans": {'x': (1, 2), 'y': (3, 4)}},  # arrays
+
+    ]
+    tykes = [
+        {"code": "(x=1, y=2)", "ans": {'x': 1, 'y': 2}},  # outer brackets
+        {"code": "x='(1, 2)', y='(3, 4)'", "ans": {'x': "(1, 2)", 'y': "(3, 4)"}},  # string representation of array (single)
+        {"code": "x=\"(1, 2)\", y=\"(3, 4)\"", "ans": {'x': "(1, 2)", 'y': "(3, 4)"}},  # string representation of array (double)
+    ]
+    for case in exemplars + tykes:
+        assert tools.getArgs(case['code']) == case['ans']
+
+
+@pytest.mark.stringtools
+def test_make_valid_name():
+    cases = [
+        # Already valid names
+        {"in": "ALREADYVALIDUPPER", "case": "upper", "out": "ALREADYVALIDUPPER"},
+        {"in": "AlreadyValidTitle", "case": "title", "out": "AlreadyValidTitle"},
+        {"in": "alreadyValidCamel", "case": "camel", "out": "alreadyValidCamel"},
+        {"in": "already_valid_snake", "case": "snake", "out": "already_valid_snake"},
+        {"in": "alreadyvalidlower", "case": "lower", "out": "alreadyvalidlower"},
+        # Sentence style names
+        {"in": "make upper", "case": "upper", "out": "MAKEUPPER"},
+        {"in": "make title", "case": "title", "out": "MakeTitle"},
+        {"in": "make camel", "case": "camel", "out": "makeCamel"},
+        {"in": "make snake", "case": "snake", "out": "make_snake"},
+        {"in": "make lower", "case": "lower", "out": "makelower"},
+        # Numbers on end
+        {"in": "upper case 1", "case": "upper", "out": "UPPERCASE1"},
+        {"in": "title case 2", "case": "title", "out": "TitleCase2"},
+        {"in": "camel case 3", "case": "camel", "out": "camelCase3"},
+        {"in": "snake case 4", "case": "snake", "out": "snake_case_4"},
+        {"in": "lower case 5", "case": "lower", "out": "lowercase5"},
+        # Numbers at start
+        {"in": "1 upper case", "case": "upper", "out": "UPPERCASE"},
+        {"in": "2 title case", "case": "title", "out": "TitleCase"},
+        {"in": "3 camel case", "case": "camel", "out": "camelCase"},
+        {"in": "4 snake case", "case": "snake", "out": "snake_case"},
+        {"in": "5 lower case", "case": "lower", "out": "lowercase"},
+        # Numbers inbetween
+        {"in": "upper 1 case", "case": "upper", "out": "UPPER1CASE"},
+        {"in": "title 2 case", "case": "title", "out": "Title2Case"},
+        {"in": "camel 3 case", "case": "camel", "out": "camel3Case"},
+        {"in": "snake 4 case", "case": "snake", "out": "snake_4_case"},
+        {"in": "lower 5 case", "case": "lower", "out": "lower5case"},
+        # Invalid chars
+        {"in": "exclamation!mark", "case": "snake", "out": "exclamation_mark"},
+        {"in": "question?mark", "case": "snake", "out": "question_mark"},
+        # Protected/private/core syntax
+        {"in": "_privateAttribute", "case": "snake", "out": "_private_attribute"},
+        {"in": "_privateAttribute", "case": "camel", "out": "_privateAttribute"},
+        {"in": "__protectedAttribute", "case": "snake", "out": "__protected_attribute"},
+        {"in": "__protectedAttribute", "case": "camel", "out": "__protectedAttribute"},
+        {"in": "__core__", "case": "snake", "out": "__core__"},
+        {"in": "__core__", "case": "lower", "out": "__core__"},
+        # Known tykes
+    ]
+
+    for case in cases:
+        assert tools.makeValidVarName(name=case['in'], case=case['case']) == case['out']
+
+
+def test_CaseSwitcher():
+
+    cases = [
+        # to camel
+        {'fcn': "pascal2camel", 'in': "alreadyValidCamel", 'out': "alreadyValidCamel"},
+        {'fcn': "title2camel", 'in': "alreadyValidCamel", 'out': "alreadyValidCamel"},
+        {'fcn': "snake2camel", 'in': "alreadyValidCamel", 'out': "alreadyValidCamel"},
+        {'fcn': "pascal2camel", 'in': "MakeCamel", 'out': "makeCamel"},
+        {'fcn': "title2camel", 'in': "Make Camel", 'out': "makeCamel"},
+        {'fcn': "snake2camel", 'in': "make_camel", 'out': "makeCamel"},
+        # to pascal
+        {'fcn': "camel2pascal", 'in': "AlreadyValidPascal", 'out': "AlreadyValidPascal"},
+        {'fcn': "title2pascal", 'in': "AlreadyValidPascal", 'out': "AlreadyValidPascal"},
+        {'fcn': "snake2pascal", 'in': "AlreadyValidPascal", 'out': "AlreadyValidPascal"},
+        {'fcn': "camel2pascal", 'in': "makePascal", 'out': "MakePascal"},
+        {'fcn': "title2pascal", 'in': "Make Pascal", 'out': "MakePascal"},
+        {'fcn': "snake2pascal", 'in': "make_pascal", 'out': "MakePascal"},
+        # to title
+        {'fcn': "camel2title", 'in': "Already Valid Title", 'out': "Already Valid Title"},
+        {'fcn': "pascal2title", 'in': "Already Valid Title", 'out': "Already Valid Title"},
+        {'fcn': "snake2title", 'in': "Already Valid Title", 'out': "Already Valid Title"},
+        {'fcn': "camel2title", 'in': "makeTitle", 'out': "Make Title"},
+        {'fcn': "pascal2title", 'in': "MakeTitle", 'out': "Make Title"},
+        {'fcn': "snake2title", 'in': "make_title", 'out': "Make Title"},
+        # to snake
+        {'fcn': "camel2snake", 'in': "already_valid_snake", 'out': "already_valid_snake"},
+        {'fcn': "pascal2snake", 'in': "already_valid_snake", 'out': "already_valid_snake"},
+        {'fcn': "title2snake", 'in': "already_valid_snake", 'out': "already_valid_snake"},
+        {'fcn': "camel2snake", 'in': "makeSnake", 'out': "make_snake"},
+        {'fcn': "pascal2snake", 'in': "MakeSnake", 'out': "make_snake"},
+        {'fcn': "title2snake", 'in': "Make Snake", 'out': "make_snake"},
+    ]
+
+    for case in cases:
+        # get function
+        fcn = getattr(tools.CaseSwitcher, case['fcn'])
+        # call function
+        case['result'] = fcn(case['in'])
+        # check result
+        assert case['result'] == case['out'], "CaseSwitcher.{fcn}({in}) should be {out}, was {result}.".format(**case)

psychopy/tests/test_tools/test_versionchooser.py

@@ -0,0 +1,209 @@
+# -*- coding: utf-8 -*-
+"""Tests for psychopy.tools.versionchooser"""
+import os
+import sys
+import unittest
+import subprocess
+import shutil
+from pathlib import Path
+
+import psychopy
+from psychopy.tools.versionchooser import Version, VersionRange, useVersion, versionMap
+from psychopy import prefs, experiment
+from psychopy.scripts.psyexpCompile import generateScript
+from psychopy.experiment.components import polygon
+from tempfile import mkdtemp
+
+USERDIR = prefs.paths['userPrefsDir']
+VER_SUBDIR = 'versions'
+VERSIONSDIR = os.path.join(USERDIR, VER_SUBDIR)
+
+pyVersion = Version(".".join(
+    [str(sys.version_info.major), str(sys.version_info.minor)]
+))
+
+
+class TestVersionChooser():
+    def setup_method(self):
+        self.temp = Path(mkdtemp())
+
+    def test_same_version(self):
+        # pick a version which works with installed Python
+        rVers = versionMap[pyVersion][0]
+        # use it
+        vers = useVersion(rVers)
+        vers = Version(vers)
+        # confirm that it is being used
+        assert (vers.major, vers.minor) == (rVers.major, rVers.minor)
+
+    def test_version_folder(self):
+        assert(os.path.isdir(VERSIONSDIR))
+
+    def test_writing(self):
+        # Can't run this test on anything beyond 3.6
+        if pyVersion > Version("3.6"):
+            return
+
+        # Create simple experiment with a Polygon
+        exp = experiment.Experiment()
+        rt = experiment.routines.Routine(name="testRoutine", exp=exp)
+        exp.addRoutine("testRoutine", rt)
+        exp.flow.addRoutine(rt, 0)
+        comp = polygon.PolygonComponent(exp=exp, parentName="testRoutine")
+        rt.addComponent(comp)
+        # Set use version
+        exp.settings.params['Use version'].val = "2021.1.4"
+        # Save experiment
+        exp.saveToXML(str(self.temp / "versionText.psyexp"))
+
+        # --- Python ---
+        # Write script
+        scriptFile = str(self.temp / "versionText.py")
+        generateScript(
+            outfile=scriptFile,
+            exp=exp,
+            target="PsychoPy"
+        )
+        # Read script
+        with open(scriptFile, "r") as f:
+            script = f.read()
+        # Get args passed to comp
+        args = script.split(f"{comp.name} = visual.ShapeStim(")[1]
+        args = args.split(")")[0]
+        # If using 2021.1.4, there shouldn't be any "anchor" arg in ShapeStim, as it wasn't implemented yet
+        assert "anchor" not in args, (
+            "When compiling Py with useversion 2021.1.4, found 'anchor' argument in ShapeStim; this was not "
+            "implemented in requested version."
+        )
+
+        # --- JS ---
+        # Write script
+        scriptFile = str(self.temp / "versionText.js")
+        generateScript(
+            outfile=scriptFile,
+            exp=exp,
+            target="PsychoJS"
+        )
+        # Read script
+        with open(scriptFile, "r") as f:
+            script = f.read()
+        # Check for correct version import statement
+        assert "import { PsychoJS } from './lib/core-2021.1.4.js'" in script, (
+            "When compiling JS with useversion 2021.1.4, could not find version-specific import statement."
+        )
+
+
+class TestVersionRange:
+    def test_comparisons(self):
+        """
+        Test that version numbers below the range register as less than.
+        """
+        cases = [
+            # value < range
+            {'range': ("2023.1.0", "2023.2.0"), 'value': "2022.2.0",
+             'lt': False, 'eq': False, 'gt': True},
+            # value == range.first
+            {'range': ("2023.1.0", "2023.2.0"), 'value': "2023.1.0",
+             'lt': False, 'eq': True, 'gt': False},
+            # value in range
+            {'range': ("2023.1.0", "2023.2.0"), 'value': "2023.1.5",
+             'lt': False, 'eq': True, 'gt': False},
+            # value == range.last
+            {'range': ("2023.1.0", "2023.2.0"), 'value': "2023.2.0",
+             'lt': False, 'eq': True, 'gt': False},
+            # value > range
+            {'range': ("2023.1.0", "2023.2.0"), 'value': "2024.1.0",
+             'lt': True, 'eq': False, 'gt': False},
+
+            # value < range.last with no first
+            {'range': (None, "2023.2.0"), 'value': "2022.2.0",
+             'lt': False, 'eq': True, 'gt': False},
+            # value == range.last with no first
+            {'range': (None, "2023.2.0"), 'value': "2023.2.0",
+             'lt': False, 'eq': True, 'gt': False},
+            # value > range.last with no first
+            {'range': (None, "2023.2.0"), 'value': "2024.1.0",
+             'lt': True, 'eq': False, 'gt': False},
+
+            # value < range.first with no last
+            {'range': ("2023.1.0", None), 'value': "2022.2.0",
+             'lt': False, 'eq': False, 'gt': True},
+            # value == range.first with no last
+            {'range': ("2023.1.0", None), 'value': "2023.1.0",
+             'lt': False, 'eq': True, 'gt': False},
+            # value > range.first with no last
+            {'range': ("2023.1.0", None), 'value': "2024.1.0",
+             'lt': False, 'eq': True, 'gt': False},
+
+            # no last or first
+            {'range': (None, None), 'value': "2022.2.0",
+             'lt': False, 'eq': True, 'gt': False},
+            {'range': (None, None), 'value': "2023.1.0",
+             'lt': False, 'eq': True, 'gt': False},
+            {'range': (None, None), 'value': "2024.1.0",
+             'lt': False, 'eq': True, 'gt': False},
+        ]
+
+        for case in cases:
+            # make VersionRange
+            r = VersionRange(
+                first=case['range'][0],
+                last=case['range'][1]
+            )
+            # work out le and ge from case values
+            case['le'] = case['lt'] or case['eq']
+            case['ge'] = case['gt'] or case['eq']
+            # confirm that comparisons work as expected
+            assert (r > case['value']) == case['gt'], (
+                "VersionRange%(range)s > '%(value)s' should be %(gt)s" % case
+            )
+            assert (r >= case['value']) == case['ge'], (
+                "VersionRange%(range)s >= '%(value)s' should be %(ge)s" % case
+            )
+            assert (case['value'] in r) == case['eq'], (
+                "'%(value)s' in VersionRange%(range)s should be %(eq)s" % case
+            )
+            assert (r <= case['value']) == case['le'], (
+                "VersionRange%(range)s <= '%(value)s' should be %(le)s" % case
+            )
+            assert (r < case['value']) == case['lt'], (
+                "VersionRange%(range)s < '%(value)s' should be %(lt)s" % case
+            )
+
+
+class TestGitInstallation(unittest.TestCase):
+    def test_git_installed(self):
+        # Test if Git is installed on this system.
+        try:
+            # Attempt to get the Git version
+            result = subprocess.run(["git", "--version"], check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+            # Check if the command was successful
+            self.assertTrue(result.returncode == 0, "Git is not installed or not in the PATH.")
+        except subprocess.CalledProcessError:
+            # If an error occurs, the test should fail
+            self.fail("Git is not installed or not in the PATH.")
+
+
+class TestGitClone(unittest.TestCase):
+    def test_git_can_clone_repo(self):
+        # Test that Git can clone a repository
+        repo_url = "https://github.com/git/git"  # Using a reliable repo that is always available
+        target_dir = "temp_repo"
+
+        try:
+            # Ensure the target directory does not exist before cloning
+            if os.path.exists(target_dir):
+                shutil.rmtree(target_dir)
+
+            # Run 'git clone' and capture output
+            subprocess.run(['git', 'clone', repo_url, target_dir], check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        except subprocess.CalledProcessError as e:
+            # If Git clone fails for any reason
+            self.fail(f"Git clone command failed: {e}")
+        except FileNotFoundError:
+            # If the 'git' command is not found
+            self.fail("Git is not installed on this system.")
+        finally:
+            # Clean up by removing the cloned directory if it exists
+            if os.path.exists(target_dir):
+                shutil.rmtree(target_dir)

psychopy/tests/test_tools/test_viewtools.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+"""Tests for psychopy.tools.viewtools
+"""
+
+from psychopy.tools.mathtools import alignTo, lookAt, distance
+from psychopy.tools.viewtools import *
+import numpy as np
+import pytest
+
+
+@pytest.mark.viewtools
+def test_visualAngle():
+    """Test visual angle calculation.
+
+    This tests the visual angle calculation for a few values. The test is
+    performed by converting the visual angle back to a distance and checking if
+    it is the same as the original distance.
+
+    """
+    # test calculation against value computed by hand
+    # obj distance = 0.57m, obj size = 0.01m
+    assert np.isclose(visualAngle(0.01, 0.57), 1.0051633)  # ~1 degree
+
+    # test input vectorization
+    N = 1000
+    np.random.seed(12345)
+    distances = np.random.uniform(0.1, 100.0, (N,))
+    sizes = np.random.uniform(0.01, 10.0, (N,))
+
+    a  = visualAngle(sizes, distances)
+    b = visualAngle(sizes, 0.57)
+    c = visualAngle(1.0, distances)
+
+    # make sure no values are >180 degrees or less than 0
+    assert np.all(a <= 180) and np.all(b <= 180) and np.all(c <= 180)
+    assert np.all(a >= 0) and np.all(b >= 0) and np.all(c >= 0)
+
+
+@pytest.mark.viewtools
+def test_viewMatrix():
+    """Test view matrix generation.
+
+    This create a view matrix using `lookAt` and `viewMatrix` and checks if
+    they look at the same point.
+
+    """
+    N = 1000
+    np.random.seed(12345)
+    targets = np.random.uniform(-100., 100., (N, 3,))
+    origin = [0, 0, 0]
+    orthoProj = orthoProjectionMatrix(-1, 1, -1, 1, 0.1, 100)
+
+    for i in range(N):
+        target = targets[i].tolist()
+
+        # View matrix generation using a quaternion will be canted, but will 
+        # center on the same point
+        V0 = viewMatrix(origin, alignTo([0, 0, -1], target))
+        
+        # Use `lookAt` to generate a view matrix, same as `gluLookAt`
+        V1 = lookAt(origin, target, [0, 1, 0])
+
+        # Check if the the matricies look at the same point if we project the 
+        # target to NDC space. They should both be near the very center of the 
+        # screen
+        posOut0 = pointToNdc(target, V0, orthoProj)
+        posOut1 = pointToNdc(target, V1, orthoProj)
+
+        assert np.isclose(posOut0, posOut1).all()
+
+
+@pytest.mark.viewtools
+def test_projectFrustumToPlane():
+    """Test the projection of the frustum to a plane.
+    """
+    N = 1000
+    np.random.seed(12345)
+    nearClip = 0.025
+    scrDims = np.random.uniform(0.01, 10.0, (N, 2,))
+    viewDists = np.random.uniform(nearClip, 10.0, (N,))
+    eyeOffsets = np.random.uniform(-0.1, 0.1, (N,))
+
+    for i in range(N):
+        scrWidth = scrDims[i, 0]
+        scrAspect = scrDims[i, 0] / scrDims[i, 1]
+        scrHeight = scrWidth * (1.0 / scrAspect)
+        viewDist = viewDists[i]
+
+        farClip = viewDist
+
+        frustum = computeFrustum(
+            scrWidth,
+            scrAspect,
+            viewDist,
+            eyeOffset=eyeOffsets[i],
+            nearClip=nearClip,
+            farClip=farClip)
+
+        frustum = [v.item() for v in frustum]
+
+        topLeft, bottomLeft, _, topRight = projectFrustumToPlane(
+            frustum, viewDist)
+        
+        # should match the screen dimensions
+        assert (np.isclose(distance(topLeft, topRight), scrWidth) and 
+                np.isclose(distance(topLeft, bottomLeft), scrHeight))
+
+
+@pytest.mark.viewtools
+def test_frustumToProjectionMatrix():
+    """Ensure the `computeFrustum` + `perspectiveProjectionMatrix` and
+    `generalizedPerspectiveProjection` give similar results, therefore testing
+    them both at the same time.
+
+    """
+    # random screen parameters
+    N = 1000
+    np.random.seed(12345)
+    scrDims = np.random.uniform(0.01, 10.0, (N, 2,))
+    viewDists = np.random.uniform(0.025, 10.0, (N,))
+    eyeOffsets = np.random.uniform(-0.1, 0.1, (N,))
+
+    for i in range(N):
+        scrWidth = scrDims[i, 0]
+        scrAspect = scrDims[i, 0] / scrDims[i, 1]
+        viewDist = viewDists[i]
+
+        # nearClip some distance between screen and eye
+        nearClip = np.random.uniform(0.001, viewDist, (1,))
+
+        # nearClip some distance beyond screen
+        fcMin = viewDist + nearClip
+        farClip = np.random.uniform(fcMin, 1000.0, (1,))
+
+        frustum = computeFrustum(
+            scrWidth,
+            scrAspect,
+            viewDist,
+            eyeOffset=eyeOffsets[i],
+            nearClip=nearClip,
+            farClip=farClip)
+        
+        frustum = [v.item() for v in frustum]  # ensure scalars
+
+        P = perspectiveProjectionMatrix(*frustum)
+
+        # configuration of screen and eyes
+        x = scrWidth / 2.
+        y = scrDims[i, 1] / 2.0
+        z = -viewDist
+        posBottomLeft = [-x, -y, z]
+        posBottomRight = [x, -y, z]
+        posTopLeft = [-x, y, z]
+        posEye = [eyeOffsets[i], 0.0, 0.0]
+
+        # create projection and view matrices
+        GP, _ = generalizedPerspectiveProjection(posBottomLeft,
+                                                 posBottomRight,
+                                                 posTopLeft,
+                                                 posEye,
+                                                 nearClip=nearClip,
+                                                 farClip=farClip)
+
+        assert np.allclose(P, GP)
+
+
+if __name__ == "__main__":
+    pytest.main()

psychopy/tests/test_validators/test_voicekeyValidator.py

@@ -0,0 +1,95 @@
+import pytest
+from psychopy import core, constants, sound, validation
+from psychopy.hardware import microphone, soundsensor, DeviceManager
+
+
+@pytest.mark.needs_sound
+class TestAudioValidator:
+    def setup_class(cls):
+        cls.vk = cls.speaker = None
+        # find best vk/speaker pair to use
+        for profile in DeviceManager.getAvailableDevices(
+            "psychopy.hardware.soundsensor.MicrophoneSoundSensorEmulator"
+        ):
+            # setup sound sensor
+            try:
+                # make sure the mic exists
+                if not DeviceManager.getDevice(profile['device']):
+                    for micProfile in DeviceManager.getAvailableDevices(
+                        "psychopy.hardware.microphone.MicrophoneDevice"
+                    ):
+                        if micProfile['index'] == profile['device']:
+                            DeviceManager.addDevice(**micProfile)
+                # create sound sensor emulator
+                vk = DeviceManager.addDevice(**profile)
+            except Exception as err:
+                continue
+            # find matching speakers
+            foundSpeakers = vk.findSpeakers(channel=0)
+            # check that speakers can be initialised
+            for speaker in foundSpeakers:
+                try:
+                    sound.Sound("A", speaker=speaker)
+                except:
+                    continue
+                else:
+                    # if successful, we have a matching pair!
+                    cls.speaker = speaker
+                    cls.vk = vk
+        # skip if no devices were found
+        if cls.vk is None or cls.speaker is None:
+            pytest.skip()
+        # create validator
+        cls.validator = validation.AudioValidator(cls.vk)
+    
+    def test_soundHeard(self):
+        """
+        Check that the sound sensor validator detects a sound played from an audible speaker.
+        """
+        # setup timing
+        clock = core.Clock()
+        self.validator.resetTimer(clock)
+        t = 0
+        # setup sound
+        snd = sound.Sound("A", speaker=self.speaker)
+        snd.tStart = snd.tStop = None
+        # set starting statuses
+        snd.status = self.validator.status = constants.NOT_STARTED
+        # begin a frame loop
+        while t < 3:
+            t = clock.getTime()
+            # validate start
+            if self.validator.status == constants.STARTED and snd.status == constants.STARTED:
+                self.validator.tStart, self.validator.valid = self.validator.validate(
+                    state=True, 
+                    t=snd.tStart,
+                    adjustment=0.12
+                )
+                if self.validator.tStart:
+                    self.validator.status = constants.FINISHED
+                    assert self.validator.valid            
+            # validate stop
+            if self.validator.status == constants.STARTED and snd.status == constants.FINISHED:
+                self.validator.tStop, self.validator.valid = self.validator.validate(
+                    state=False, 
+                    t=snd.tStop,
+                    adjustment=0
+                )
+                if self.validator.tStop:
+                    self.validator.status = constants.FINISHED
+                    assert self.validator.valid
+            # start sound
+            if snd.status == constants.NOT_STARTED and t > 1:
+                snd.play()
+                snd.tStart = t
+                snd.status = constants.STARTED
+                self.validator.status = constants.STARTED
+            # stop sound
+            if snd.status == constants.STARTED and t > 2:
+                snd.stop()
+                snd.tStop = t
+                snd.status = constants.FINISHED
+                self.validator.status = constants.STARTED
+        # make sure the validator got some times
+        assert self.validator.tStart is not None
+        assert self.validator.tStop is not None