Testes de escrita e execução

Para garantir que o MRTK é fiável, o MRTK dispõe de um conjunto de testes para garantir que as alterações ao código não regredirem o comportamento existente. Ter uma boa cobertura de teste numa grande base de códigos como o MRTK é crucial para a estabilidade e para ter confiança ao fazer alterações.

O MRTK utiliza o Unity Test Runner que utiliza uma integração de unidade da NUnit. Este guia fornecerá um ponto de partida sobre como adicionar testes ao MRTK. Não explicará o Unity Test Runner e o NUnit que podem ser analisados nos links fornecidos.

Antes de apresentar um pedido de retirada, certifique-se de:

  1. Faça os testes localmente para que as suas alterações não regredam o comportamento existente (não será permitido completar pRs se algum teste falhar).

  2. Se consertar um erro, escreva um teste para testar a correção e certifique-se de que as futuras modificações de código não o partam novamente.

  3. Se escrever uma funcionalidade, escreva novos testes para evitar que as próximas alterações de código desacriem esta funcionalidade.

Atualmente, os testes de playmode deverão ser executados na Unidade 2018.4 e podem falhar noutras versões da Unidade

Testes de execução

Editor de unidade

O Unity Test Runner pode ser encontrado no WindowGeneralTest Runner e mostrará todos os testes de modo de reprodução e edição de mrtk disponíveis.

Linha de comandos

Os testes também podem ser executados por um script powershell localizado em . Isto irá executar os testes de playmode exatamente tal como são executados no github/CI (ver abaixo) e os resultados de impressão. Aqui estão alguns exemplos de como executar o script

Realizar os testes no projeto localizado em H:\mrtk.dev, com Unidade 2018.4 (por exemplo Unidade 2018.4.26f1)

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

Realizar os testes no projeto localizado em H:\mrtk.dev, com Unidade 2018.4, resultados de saída para 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\"

Também é possível executar os testes de playmode várias vezes através do run_repeat_tests.ps1 script. Podem ser utilizados todos os parâmetros run_playmode_tests.ps1 utilizados.

.\run_repeat_tests.ps1 -Times 5

Retirar validação de pedido

O CI do MRTK construirá mrtk em todas as configurações e executará todos os testes de edição e modo de reprodução. O CI pode ser desencadeado publicando um comentário sobre o GITHUB PR /azp run mrtk_pr se o utilizador tiver direitos suficientes. As operações de CI podem ser vistas no separador 'cheques' do RP.

Só depois de todos os testes terem sido realizados com sucesso é que o RP pode ser fundido em principal.

Testes de stress / testes a granel

Por vezes, os testes só falham ocasionalmente, o que pode ser frustrante depurar.

Para ter várias corridas de teste localmente, modifique os scripts de teste de acordo. O seguinte roteiro python deve tornar este cenário mais conveniente.

O pré-requisito para executar o script python é ter Python 3.X instalado.

Para um único teste que precisa ser executado várias vezes:

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

Executar o seguinte a partir de uma linha de comando(Recomenda-se powerShell)

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

Copie e cole a saída no seu ficheiro de teste. O seguinte script é para executar vários testes em sequência:

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

O novo ficheiro de teste deve agora conter

[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 o test runner e observe os novos testes que agora podem ser chamados repetidamente.

Testes de escrita

Existem dois tipos de testes que podem ser adicionados para novo código

  • Testes de modo de reprodução
  • Editar testes de modo

Testes de modo de reprodução

Os testes do modo de reprodução MRTK têm a capacidade de testar como a sua nova funcionalidade responde a diferentes fontes de entrada, como mãos ou olhos.

Os novos testes do modo de reprodução podem herdar BasePlayModeTests ou o esqueleto abaixo pode ser usado.

Para criar um novo teste de modo de reprodução:

  • Navegue para ativos > MRTK > Tests > PlayModeTests
  • Clique à direita, Crie > o Script de Teste > C#
  • Substitua o modelo padrão pelo esqueleto abaixo
#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 testes de modo

Os testes de modo de edição são executados no modo de edição da Unidade e podem ser adicionados sob a pasta DE Testes MRTKEditModeTests no repo de Ferramentas de Realidade Mista. Para criar um novo teste, pode utilizar-se o seguinte modelo:

// 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()
        {

        }
    }
}

Convenções de nomeação de testes

Os testes devem geralmente ser nomeados com base na classe que estão a testar, ou no cenário que estão a testar. Por exemplo, dada uma classe a ser testada:

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

Considere nomear o teste

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

Considere colocar o teste numa hierarquia de pasta semelhante à respetiva ficha de não teste. Por exemplo:

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

Isto é para garantir que há uma maneira clara de encontrar a classe de teste correspondente de cada classe, se tal classe de teste existir.

A colocação de testes baseados em cenários é menos definida - se o teste exercer o sistema de entrada geral, por exemplo, considerar colocá-lo numa pasta "InputSystem" no modo de edição correspondente ou na pasta de teste do modo de reprodução.

Ícones de script de teste

Ao adicionar um novo teste, por favor, modifique o script para ter o ícone MRTK correto. Há uma ferramenta mrtk fácil para fazê-lo:

  1. Vá ao item do menu de ferramentas de realidade mista
  2. Clique em Utilitários, em seguida, Atualizar e, em seguida, Ícones
  3. Clique em Testes e o atualizador será executado automaticamente, atualizando quaisquer scripts de teste que faltem aos seus ícones

Métodos de utilidade MRTK

Esta secção mostra alguns dos cortes/métodos de código comumente utilizados ao escrever testes para MRTK.

Existem duas classes de utilidade que ajudam a configurar o MRTK e testar interações com componentes em MRTK

As testutilidades fornecem os seguintes métodos para configurar a sua cena MRTK e 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();

Por favor, consulte os docs da API TestUtilities e PlayModeTestUtilities para mais métodos destas classes util, uma vez que são estendidas regularmente enquanto novos testes são adicionados ao MRTK.