Escritura y ejecución de pruebas: MRTK2

  • Artículo

Para asegurarse de que MRTK es confiable, MRTK tiene un conjunto de pruebas para asegurarse de que los cambios en el código no retrocede 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. Esta guía proporcionará 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 corrige un error, escriba una prueba para probar la corrección y asegúrese de que las modificaciones futuras del código no se interrumpirán de nuevo.

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

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

Ejecución de las pruebas

Editor de Unity

El ejecutor de pruebas de Unity sepuede encontrar enEjecutor general de pruebas de la ventana>> y mostrará todas las pruebas en modo de reproducción y edició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 ejecutará las pruebas de playmode exactamente como se ejecutan en github /CI (consulte a continuación) e imprimirá 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, resultados de salida 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 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 las solicitudes de incorporación de cambios

La CI de MRTK compilará MRTK en todas las configuraciones y ejecutará todas las pruebas de modo de edición y reproducción. La ci se puede desencadenar publicando un comentario en la solicitud de incorporación /azp run mrtk_pr de 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 main.

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. El siguiente script de Python debe facilitar este escenario.

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

Para una sola prueba que se debe ejecutar varias veces:

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

Ejecute lo siguiente 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 debe contener ahora

[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 en modo de reproducción
  • Editar pruebas en modo

Pruebas en 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 las manos o los ojos.

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

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

  • Vaya a Assets > MRTK Tests PlayModeTests (Activos de pruebas de > MRTK>)
  • Haga clic con el botón derecho en Create Testing C# Test Script (Crear > script de prueba de C# para pruebas > )
  • Reemplace la plantilla predeterminada por el esqueleto siguiente
#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

Editar pruebas en modo

Las pruebas en modo de edición se ejecutan en el modo de edición de Unity y se pueden agregar en la carpeta MRTK>Tests>EditModeTests 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 deben denominarse en función de la clase que están probando, o el 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 no 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 de encontrar la clase de prueba correspondiente de cada clase, si existe dicha clase de prueba.

La colocación de pruebas basadas en escenarios es menos definida: si la prueba ejerce el sistema de entrada general, por ejemplo, considere la posibilidad de colocarla en una carpeta "InputSystem" en el modo de edición correspondiente o en la carpeta de prueba del modo de reproducción.

Probar iconos de script

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

  1. Vaya al elemento de menú Mixed Reality Toolkit.
  2. Haga clic en Utilidades y, a continuación, en Actualizar y en Iconos.
  3. Haga clic en Pruebas y el actualizador se ejecutará automáticamente y actualizará los scripts de prueba que falten en 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 interacciones con componentes en 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();

Consulte los documentos de API de TestUtilities y PlayModeTestUtilities para conocer otros métodos de estas clases de utilidad, ya que se extienden periódicamente mientras se agregan nuevas pruebas a MRTK.