Pisanie i uruchamianie testów — MRTK2
Aby zapewnić niezawodność zestawu narzędzi MRTK, zestaw narzędzi MRTK zawiera zestaw testów zapewniających, że zmiany w kodzie nie pogarszają istniejącego zachowania. Posiadanie dobrego pokrycia testowego w dużej bazie kodu, takiej jak MRTK, ma kluczowe znaczenie dla stabilności i pewności podczas wprowadzania zmian.
Zestaw narzędzi MRTK używa modułu uruchamiającego testy aparatu Unity , który używa integracji aparatu Unity z narzędziem NUnit. Ten przewodnik zawiera punkt wyjścia do dodawania testów do zestawu narzędzi MRTK. Nie będzie on wyjaśniał modułu uruchamiającego testy aparatu Unity i NUnit , który można wyszukać w podanych linkach.
Przed przesłaniem żądania ściągnięcia upewnij się, że:
Uruchom testy lokalnie, aby zmiany nie ulegały pogorszeniu istniejącego zachowania (ukończenie żądania ściągnięcia nie będzie dozwolone w przypadku niepowodzenia testów).
Jeśli usunięto usterkę, napisz test w celu przetestowania poprawki i upewnij się, że przyszłe modyfikacje kodu nie będą ponownie przerywane.
Jeśli pisać funkcję, napisz nowe testy, aby zapobiec nadchodzącym zmianom kodu powodującym niezgodność tej funkcji.
Obecnie testy playmode mają być uruchamiane w środowisku Unity 2018.4 i mogą zakończyć się niepowodzeniem w innych wersjach aparatu Unity
Uruchamianie testów
Edytor aparatu Unity
Moduł uruchamiający testy aparatu Unity można znaleźć w obszarze Moduł>uruchamiający testyogólne> okna i wyświetli wszystkie dostępne testy trybu odtwarzania i edytowania zestawu narzędzi MRTK.
Wiersz polecenia
Testy można również uruchamiać za pomocą skryptu programu PowerShell znajdującego się w lokalizacji Scripts\test\run_playmode_tests.ps1. Spowoduje to uruchomienie testów playmode dokładnie tak, jak są wykonywane w witrynie github /CI (patrz poniżej) i wydrukować wyniki. Oto kilka przykładów uruchamiania skryptu
Uruchom testy w projekcie znajdującym się w lokalizacji H:\mrtk.dev z aparatem Unity 2018.4 (na przykład Unity 2018.4.26f1)
.\run_playmode_tests.ps1 H:\mrtk.dev -unityExePath "C:\Program Files\Unity\Hub\Editor\2018.4.26f1\Editor\Unity.exe"
Uruchom testy w projekcie znajdującym się w lokalizacji H:\mrtk.dev, a środowisko Unity 2018.4 generuje wyniki do katalogu 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\"
Istnieje również możliwość wielokrotnego uruchamiania testów playmode za pomocą skryptu run_repeat_tests.ps1 . Można użyć wszystkich parametrów używanych w run_playmode_tests.ps1 programie .
.\run_repeat_tests.ps1 -Times 5
Walidacja żądania ściągnięcia
Ciągła integracja zestawu narzędzi mrTK skompiluje zestaw narzędzi MRTK we wszystkich konfiguracjach i uruchomi wszystkie testy trybu edycji i odtwarzania. Ciągła integracja może zostać wyzwolona przez opublikowanie komentarza do żądania ściągnięcia /azp run mrtk_pr w usłudze GitHub, jeśli użytkownik ma wystarczające prawa. Przebiegi ciągłej integracji można zobaczyć na karcie "kontrole" żądania ściągnięcia.
Dopiero po pomyślnym wykonaniu wszystkich testów żądanie ściągnięcia można scalić z głównym.
Testy przeciążeczne/testy zbiorcze
Czasami testy kończą się niepowodzeniem tylko od czasu do czasu, co może być frustrujące do debugowania.
Aby lokalnie przeprowadzić wiele przebiegów testów, zmodyfikuj odpowiednie skrypty testowe. Poniższy skrypt języka Python powinien sprawić, że ten scenariusz będzie wygodniejszy.
Wymagania wstępne dotyczące uruchamiania skryptu języka Python mają zainstalowany język Python 3.X.
W przypadku pojedynczego testu, który należy wykonać wiele razy:
[UnityTest]
public IEnumerator MyTest() {...}
Uruchom następujące polecenie z poziomu wiersza polecenia (zaleca się program PowerShell )
cd scripts\tests
# Repeat the test 5 times. Default is 100
python .\generate_repeat_tests.py -n 5 -t MyTest
Skopiuj i wklej dane wyjściowe do pliku testowego. Następujący skrypt służy do uruchamiania wielu testów w sekwencji:
cd scripts\tests
# Repeat the test 5 times. Default is 100
python .\generate_repeat_tests.py -n 5 -t MyTest MySecondTest
Nowy plik testowy powinien teraz zawierać
[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() {...}
Otwórz moduł uruchamiający testy i obserwuj nowe testy, które mogą być teraz wywoływane wielokrotnie.
Pisanie testów
Istnieją dwa typy testów, które można dodać dla nowego kodu
- Testy trybu odtwarzania
- Edytowanie testów trybu
Testy trybu odtwarzania
Testy trybu odtwarzania zestawu narzędzi MRTK mają możliwość testowania reakcji nowej funkcji na różne źródła danych wejściowych, takie jak ręce lub oczy.
Można dziedziczyć testy trybu odtwarzania BasePlayModeTests lub szkielet poniżej.
Aby utworzyć nowy test trybu odtwarzania:
- Przejdź do pozycji Zasoby > testy zestawu narzędzi > MRTK > PlayModeTests
- Kliknij prawym przyciskiem myszy pozycję Create Testing C# Test Script (Tworzenie > skryptu testowego języka > C#)
- Zastąp szablon domyślny szkieletem poniżej
#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
Edytowanie testów trybu
Testy trybu edycji są wykonywane w trybie edycji aparatu Unity i można je dodać w folderze MrTK>Tests>EditModeTests w repozytorium zestawu narzędzi Mixed Reality. Aby utworzyć nowy test, można użyć następującego szablonu:
// 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()
{
}
}
}
Konwencje nazewnictwa testów
Testy powinny być zwykle nazwane na podstawie klasy, którą testują, lub scenariusza, w ramach którego są testowane. Na przykład, biorąc pod uwagę klasę do przetestowania:
namespace Microsoft.MixedReality.Toolkit.Input
{
class InterestingInputClass
{
}
}
Rozważ nadanie testowi nazwy
namespace Microsoft.MixedReality.Toolkit.Tests.Input
{
class InterestingInputClassTest
{
}
}
Rozważ umieszczenie testu w hierarchii folderów podobnej do odpowiadającego mu pliku nietestowego. Na przykład:
Non-Test: Assets/MRTK/Core/Utilities/InterestingUtilityClass.cs
Test: Assets/MRTK/Tests/EditModeTests/Core/Utilities/InterestingUtilityClassTest.cs
Ma to na celu zapewnienie jasnego sposobu znajdowania odpowiedniej klasy testowej każdej klasy, jeśli taka klasa testowa istnieje.
Umieszczanie testów opartych na scenariuszu jest mniej zdefiniowane — jeśli test wykonuje ćwiczenia ogólnego systemu wejściowego, na przykład rozważ umieszczenie go w folderze "InputSystem" w odpowiednim trybie edycji lub folderze testowym trybu odtwarzania.
Ikony skryptów testowych
Podczas dodawania nowego testu zmodyfikuj skrypt, aby miał poprawną ikonę zestawu narzędzi MRTK. Istnieje łatwe narzędzie MRTK, które należy wykonać:
- Przejdź do elementu menu zestawu narzędzi Mixed Reality.
- Kliknij pozycję Narzędzia, a następnie pozycję Aktualizuj, a następnie pozycję Ikony.
- Kliknij pozycję Testy, a aktualizator zostanie uruchomiony automatycznie, aktualizując wszystkie skrypty testowe bez ich ikon.
Metody narzędzi MRTK
W tej sekcji przedstawiono niektóre z najczęściej używanych fragmentów kodu/metod podczas pisania testów dla zestawu narzędzi MRTK.
Istnieją dwie klasy narzędzi, które ułatwiają konfigurowanie zestawu narzędzi MRTK i testowanie interakcji ze składnikami w zestawie narzędzi MRTK
Narzędzia TestUtilities udostępniają następujące metody konfigurowania sceny zestawu narzędzi MRTK i obiektów 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();
Zapoznaj się z dokumentacją interfejsu TestUtilities API i PlayModeTestUtilities , aby uzyskać dalsze metody tych klas narzędzi, ponieważ są one regularnie rozszerzane, podczas gdy nowe testy są dodawane do zestawu narzędzi MRTK.