Escritura y ejecución de pruebas: MRTK2

Para asegurarse de que MRTK es confiable, MRTK tiene un conjunto de pruebas para asegurarse de que los cambios en el código no retroceden el comportamiento existente. Tener una buena cobertura de pruebas en un código base grande como MRTK es fundamental para la estabilidad y tener confianza al realizar cambios.

MRTK usa el ejecutor de pruebas de Unity, que usa una integración de Unity de NUnit. En esta guía se proporciona un punto de partida sobre cómo agregar pruebas a MRTK. No explicará el ejecutor de pruebas de Unity y NUnit, que se pueden buscar en los vínculos proporcionados.

Antes de enviar una solicitud de incorporación de cambios, asegúrese de:

  1. Ejecute las pruebas localmente para que los cambios no vuelvan al comportamiento existente (no se permitirá completar las solicitudes de incorporación de cambios si se produce un error en las pruebas).

  2. Si se corrige un error, escriba una prueba para probar la corrección y asegúrese de que las futuras modificaciones de código no vuelvan a interrumpirla.

  3. Si escribe una característica, escriba nuevas pruebas para evitar que los próximos cambios en el código rompan esta característica.

    Actualmente, las pruebas de playmode están diseñadas para ejecutarse en Unity 2018.4 y podrían producir errores en otras versiones de Unity.

Ejecución de pruebas

Editor de Unity

El ejecutor de pruebas de Unity se puede encontrar en Window>General>Test Runner y muestra todas las pruebas de modo de edición y reproducción de MRTK disponibles.

Línea de comandos

Las pruebas también se pueden ejecutar mediante un script de PowerShell ubicado en Scripts\test\run_playmode_tests.ps1. Esto ejecuta las pruebas de playmode exactamente como se ejecutan en GitHub o CI (vea a continuación) e imprime los resultados. Estos son algunos ejemplos de cómo ejecutar el script

Ejecute las pruebas en el proyecto ubicado en H:\mrtk.dev, con Unity 2018.4 (por ejemplo, Unity 2018.4.26f1):

.\run_playmode_tests.ps1 H:\mrtk.dev -unityExePath "C:\Program Files\Unity\Hub\Editor\2018.4.26f1\Editor\Unity.exe"

Ejecute las pruebas en el proyecto ubicado en H:\mrtk.dev, con Unity 2018.4, genere resultados en C:\playmode_test_out

.\run_playmode_tests.ps1 H:\mrtk.dev -unityExePath "C:\Program Files\Unity\Hub\Editor\2018.4.26f1\Editor\Unity.exe" -outFolder "C:\playmode_test_out\"

También es posible ejecutar las pruebas de playmode varias veces a través del run_repeat_tests.ps1 script. Se pueden usar todos los parámetros usados en run_playmode_tests.ps1 .

.\run_repeat_tests.ps1 -Times 5

Validación de solicitudes de incorporación de cambios

LA CI de MRTK compila MRTK en todas las configuraciones y ejecuta todas las pruebas de modo de edición y reproducción. Ci se puede desencadenar mediante la publicación de un comentario en la solicitud de incorporación de /azp run mrtk_pr cambios de GitHub si el usuario tiene derechos suficientes. Las ejecuciones de CI se pueden ver en la pestaña "comprobaciones" de la solicitud de incorporación de cambios.

Solo después de que todas las pruebas se hayan superado correctamente, la solicitud de incorporación de cambios se puede combinar en principal.

Pruebas de esfuerzo/pruebas masivas

A veces, las pruebas solo producirán errores ocasionalmente, lo que puede resultar frustrante para depurar.

Para tener varias ejecuciones de prueba localmente, modifique los scripts de prueba según. El siguiente script de Python debe hacer que este escenario sea más cómodo.

El requisito previo para ejecutar el script de Python es tener Python 3.X instalado.

Para una sola prueba que debe ejecutarse varias veces:

[UnityTest]
public IEnumerator MyTest() {...}

Ejecute los siguientes comandos desde una línea de comandos (se recomienda PowerShell ):

cd scripts\tests
# Repeat the test 5 times. Default is 100
python .\generate_repeat_tests.py -n 5 -t MyTest

Copie y pegue la salida en el archivo de prueba. El siguiente script es para ejecutar varias pruebas en secuencia:

cd scripts\tests
# Repeat the test 5 times. Default is 100
python .\generate_repeat_tests.py -n 5 -t MyTest MySecondTest

El nuevo archivo de prueba ahora debe contener

[UnityTest]
public IEnumerator A1MyTest0(){ yield return MyTest();}
[UnityTest]
public IEnumerator A2MyTest0(){ yield return MyTest();}
[UnityTest]
public IEnumerator A3MyTest0(){ yield return MyTest();}
[UnityTest]
public IEnumerator A4MyTest0(){ yield return MyTest();}
[UnityTest]
public IEnumerator MyTest() {...}

Abra el ejecutor de pruebas y observe las nuevas pruebas a las que ahora se puede llamar repetidamente.

Escritura de pruebas

Hay dos tipos de pruebas que se pueden agregar para el nuevo código:

  • Pruebas de modo de reproducción
  • Pruebas de modo de edición

Pruebas de modo de reproducción

Las pruebas de modo de reproducción de MRTK tienen la capacidad de probar cómo responde la nueva característica a diferentes orígenes de entrada, como manos o ojos.

Las nuevas pruebas de modo de reproducción pueden heredar BasePlayModeTests o se puede usar el siguiente esqueleto.

Para crear una nueva prueba de modo de reproducción:

  1. Vaya a AssetsMRTK Tests PlayModeTests (Pruebas>de MRTK>de recursos>) PlayModeTests.
  2. Haga clic con el botón derecho en Crear> script deprueba>de C#.
  3. Reemplace la plantilla predeterminada por el siguiente esqueleto:
#if !WINDOWS_UWP
// When the .NET scripting backend is enabled and C# projects are built
// The assembly that this file is part of is still built for the player,
// even though the assembly itself is marked as a test assembly (this is not
// expected because test assemblies should not be included in player builds).
// Because the .NET backend is deprecated in 2018 and removed in 2019 and this
// issue will likely persist for 2018, this issue is worked around by wrapping all
// play mode tests in this check.

using Microsoft.MixedReality.Toolkit.Input;
using Microsoft.MixedReality.Toolkit.Utilities;
using NUnit.Framework;
using System;
using System.Collections;
using System.Linq;
using UnityEngine;
using UnityEngine.TestTools;

namespace Microsoft.MixedReality.Toolkit.Tests
{
    class ExamplePlayModeTests
    {
        // This method is called once before we enter play mode and execute any of the tests
        // do any kind of setup here that can't be done in playmode
        public void Setup()
        {
            // eg installing unity packages is only possible in edit mode
            // so if a test requires TextMeshPro we will need to check for the package before entering play mode
            PlayModeTestUtilities.InstallTextMeshProEssentials();
        }

        // Do common setup for each of your tests here - this will be called for each individual test after entering playmode
        // Note that this uses UnitySetUp instead of [SetUp] because the init function needs to await a frame passing
        // to ensure that the MRTK system has had the chance to fully set up before the test runs.
        [UnitySetUp]
        public IEnumerator Init()
        {
            // in most play mode test cases you would want to at least create an MRTK GameObject using the default profile
            TestUtilities.InitializeMixedRealityToolkit(true);
            yield return null;
        }

        // Destroy the scene - this method is called after each test listed below has completed
        // Note that this uses UnityTearDown instead of [TearDown] because the init function needs to await a frame passing
        // to ensure that the MRTK system has fully torn down before the next test setup->run cycle starts.
        [UnityTearDown]
        public IEnumerator TearDown()
        {
            PlayModeTestUtilities.TearDown();
            yield return null;
        }

        #region Tests

        /// <summary>
        /// Skeleton for a new MRTK play mode test.
        /// </summary>
        [UnityTest]
        public IEnumerator TestMyFeature()
        {
            // ----------------------------------------------------------
            // EXAMPLE PLAY MODE TEST METHODS
            // ----------------------------------------------------------
            // Getting the input system
            // var inputSystem = PlayModeTestUtilities.GetInputSystem();

            // Creating a new test hand for input
            // var rightHand = new TestHand(Handedness.Right);
            // yield return rightHand.Show(new Vector3(0, 0, 0.5f));

            // Moving the new test hand
            // We are doing a yield return here because moving the hand to a new position
            // requires multiple frames to complete the action.
            // yield return rightHand.MoveTo(new Vector3(0, 0, 2.0f));

            // Getting a specific pointer from the hand
            // var linePointer = PointerUtils.GetPointer<LinePointer>(Handedness.Right);
            // Assert.IsNotNull(linePointer);
            // ---------------------------------------------------------

            // Your new test here
            yield return null;
        }
        #endregion
    }
}
#endif

Pruebas de modo de edición

Las pruebas de modo de edición se ejecutan en el modo de edición de Unity y se pueden agregar en la carpetaEdición depruebas>MRTKModeTests> del repositorio Mixed Reality Toolkit. Para crear una nueva prueba, se puede usar la plantilla siguiente:

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

using NUnit.Framework;

namespace Microsoft.MixedReality.Toolkit.Tests
{
    class EditModeExampleTest
    {
        [Test]
        /// the name of this method will be used as test name in the unity test runner
        public void TestEditModeExampleFeature()
        {

        }
    }
}

Convenciones de nomenclatura de prueba

Por lo general, las pruebas se deben denominar en función de la clase que están probando o del escenario en el que se están probando. Por ejemplo, dada una clase que se va a probar:

namespace Microsoft.MixedReality.Toolkit.Input
{
    class InterestingInputClass
    {
    }
}

Considere la posibilidad de asignar un nombre a la prueba

namespace Microsoft.MixedReality.Toolkit.Tests.Input
{
    class InterestingInputClassTest
    {
    }
}

Considere la posibilidad de colocar la prueba en una jerarquía de carpetas similar a su archivo que no es de prueba correspondiente. Por ejemplo:

Non-Test: Assets/MRTK/Core/Utilities/InterestingUtilityClass.cs
Test: Assets/MRTK/Tests/EditModeTests/Core/Utilities/InterestingUtilityClassTest.cs

Esto es para asegurarse de que hay una manera clara y obvia de encontrar la clase de prueba correspondiente de cada clase, si existe dicha clase de prueba.

La ubicación de las pruebas basadas en escenarios está menos definida: si la prueba realiza el ejercicio del sistema de entrada general, por ejemplo, considere la posibilidad de colocarla en una carpeta "InputSystem" en la carpeta de prueba del modo de edición o modo de reproducción correspondiente.

Iconos de script de prueba

Al agregar una nueva prueba, modifique el script para que tenga el icono de MRTK correcto. Hay una herramienta MRTK fácil para hacerlo:

  1. Vaya al elemento de menú Mixed Reality Toolkit.
  2. Seleccione Iconos deactualización>de utilidades>.
  3. Seleccione Pruebas y el actualizador se ejecuta automáticamente, actualizando los scripts de prueba que falten sus iconos.

Métodos de la utilidad MRTK

En esta sección se muestran algunos de los fragmentos de código o métodos usados habitualmente al escribir pruebas para MRTK.

Hay dos clases de utilidad que ayudan a configurar MRTK y probar las interacciones con los componentes de MRTK

TestUtilities proporciona los métodos siguientes para configurar la escena de MRTK y GameObjects:

/// creates the mrtk GameObject and sets the default profile if passed param is true
TestUtilities.InitializeMixedRealityToolkit()

/// creates an empty scene prior to adding the mrtk GameObject to it
TestUtilities.InitializeMixedRealityToolkitAndCreateScenes();

/// sets the initial playspace transform and camera position
TestUtilities.InitializePlayspace();

/// destroys previously created mrtk GameObject and playspace
TestUtilities.ShutdownMixedRealityToolkit();

Para obtener más información, consulte los documentos de API de TestUtilities y PlayModeTestUtilities para obtener más métodos de estas clases util, ya que se amplían periódicamente mientras se agregan nuevas pruebas a MRTK.

  • Se actualizó por última vez el