diff --git a/docs/udon-test-kit/add-to-your-project.md b/docs/udon-test-kit/add-to-your-project.md index 196f5dc..48f650f 100644 --- a/docs/udon-test-kit/add-to-your-project.md +++ b/docs/udon-test-kit/add-to-your-project.md @@ -10,9 +10,10 @@ Install the kit in a VRChat world project, then create the test assemblies your ## Requirements -- **Unity 2022.3.** -- **The [VRChat Worlds SDK](https://creators.vrchat.com/worlds/) 3.8.2 or later**, which includes - UdonSharp and ClientSim. +- **Unity 2022.3**, on Windows, or on Linux with the Windows build target, in the Editor and in + batch mode. +- **The [VRChat Worlds SDK](https://creators.vrchat.com/worlds/) 3.8.2 or a later 3.x version**, + which includes UdonSharp and ClientSim. - **Unity Test Framework**, which new Unity projects already include. ## Install the package @@ -37,7 +38,7 @@ You get a `Tests` folder with three assemblies, each with an example that works: own. Both test assemblies reference it. They reference the kit, UdonSharp, the VRChat SDK, ClientSim and every assembly definition of yours -under `Assets`, and like the kit, they're left out of your world's builds. +under `Assets`, and they're left out of your world's builds. [TestAssemblyCreator](./reference/test-assembly-creator) describes each one. If your scripts have no assembly definition, the menu item logs a warning, and Play Mode tests diff --git a/docs/udon-test-kit/explanations/a-fresh-session-for-every-test.md b/docs/udon-test-kit/explanations/a-fresh-session-for-every-test.md index c454694..802188a 100644 --- a/docs/udon-test-kit/explanations/a-fresh-session-for-every-test.md +++ b/docs/udon-test-kit/explanations/a-fresh-session-for-every-test.md @@ -8,8 +8,8 @@ sidebar_position: 2 [`ClientSimTestBase`](../reference/clientsim-test-base) ends its ClientSim session after every test, and the next test starts its own. A session ends completely: `End` leaves nothing of -ClientSim running. The one thing that carries over is saved data, and the kit never deletes it -unless a test asks. +ClientSim running. The one thing that carries over is saved data, and within a run the kit never +deletes it unless a test asks. ## Why tests don't share a session @@ -24,10 +24,11 @@ order of tests. ## Why saved data carries over -Carrying over is what saved data is for, and ClientSim keeps it in files, not in the session. The -kit never deletes those files on its own. In your world's own scene, they're your ClientSim data, -and some worlds want them to carry over between tests. `ClientSimSession.DeleteSavedData` is there -for a test that needs none. +Carrying over is what saved data is for, and ClientSim keeps it in files, not in the session. In +your world's own scene, they're your ClientSim data, and some worlds want them to carry over +between tests. `ClientSimSession.DeleteSavedData` is there for a test that needs none. The one set +of files the kit deletes on its own is that of the Unity Test Framework test scene, and only once +the run has ended, so test runs don't fill the project folder. ## Alternatives considered diff --git a/docs/udon-test-kit/explanations/what-the-kit-works-around.md b/docs/udon-test-kit/explanations/what-the-kit-works-around.md index 6d7d8f8..69a005b 100644 --- a/docs/udon-test-kit/explanations/what-the-kit-works-around.md +++ b/docs/udon-test-kit/explanations/what-the-kit-works-around.md @@ -74,8 +74,43 @@ the operation it loads with. When the garbage collector finalized that operation Unity crashed after every test had passed, so a command-line run reported failure. `TestScene` finalizes it right after the scene loads, while that's still safe. +## Behaviours added at runtime that run nothing + +An `UdonBehaviour` added to a GameObject at runtime doesn't load the compiled program of its program +source, so it runs nothing. It runs a program only once it's given one with +`AssignProgramAndVariables` and registered with `UdonManager`. `UdonHost.Create` does both. See +[UdonHost](../reference/udon-host). + +## An Udon exception that fails the next test + +When Udon halts a behaviour that threw, it logs an error, and UdonSharp logs a copy of that error on +a later frame. Unity Test Framework fails a test on any error log it didn't expect, so the copy +fails whichever test is running by then, which can be the next one. + +UdonSharp doesn't always log the copy. While it watches the log of the VRChat client, as it does by +default, and finds no VRChat installation, it holds the copy back and logs it once watching stops. +`UdonHost.ExpectUdonException` expects the error, waits up to 10 frames for the copy, and expects +the copy only once it came. + +## Udon code that compiles for the Editor but not for upload + +Before a world build, the VRChat SDK has UdonSharp compile every program for upload. That compile +reads only player assemblies, while the compile UdonSharp runs in the Editor reads every assembly +with a U# assembly definition. A program asset whose script is in an assembly that player builds +leave out, such as a tests-only one, makes the compile for upload log an error and compile no +program at all, and the build still goes on. The compile for upload also leaves out the code inside +`#if UNITY_EDITOR`, so code that compiles only together with that code fails it. + +Tests that run programs in the Editor see none of this. `UdonSharpUploadCompile` runs the compile +for upload in a test, and `UdonHost.Create` refuses a behaviour whose assembly player builds leave +out, so a test double that would break the compile for upload fails its test instead. See +[UdonSharpUploadCompile](../reference/udon-sharp-upload-compile). + ## Test code in a world build -The kit compiles only when Unity Test Framework includes tests (`UNITY_INCLUDE_TESTS`), and so do -the test assemblies it creates. A world build never includes them, so the kit can stay installed -in a world you upload. +All of the kit except `UdonCallLog` compiles only when Unity Test Framework includes tests +(`UNITY_INCLUDE_TESTS`), and so do the test assemblies it creates, so a world build never includes +them. `UdonCallLog` runs as Udon, and UdonSharp compiles only player assemblies for upload, so it +has an assembly of its own, `Tsvrc.UdonTestKit.UdonSpies`, that compiles into player builds. A +world holds its program only when a scene in the world has an `UdonCallLog`, so the kit can stay +installed in a world you upload. diff --git a/docs/udon-test-kit/first-test.md b/docs/udon-test-kit/first-test.md index 68af93c..c0f22d8 100644 --- a/docs/udon-test-kit/first-test.md +++ b/docs/udon-test-kit/first-test.md @@ -97,4 +97,6 @@ what they did. The how-to guides cover the usual next steps: - [Test what happens for a player who isn't the owner](./how-to/testing-a-player-who-isnt-the-owner). - [Check that saved data survives a rejoin](./how-to/testing-saved-data). - [Check the calls your code makes by name](./how-to/checking-calls-made-by-name). +- [Run your behaviours as Udon](./how-to/running-behaviours-as-udon), to test what Udon does with + your code. - [Run tests from the command line](./how-to/running-tests-from-the-command-line). diff --git a/docs/udon-test-kit/how-to/adding-your-worlds-own-setup.md b/docs/udon-test-kit/how-to/adding-your-worlds-own-setup.md index 933ee17..7975cdd 100644 --- a/docs/udon-test-kit/how-to/adding-your-worlds-own-setup.md +++ b/docs/udon-test-kit/how-to/adding-your-worlds-own-setup.md @@ -1,7 +1,7 @@ --- id: adding-your-worlds-own-setup title: Add your world's own test setup -sidebar_position: 6 +sidebar_position: 8 --- # Add your world's own test setup diff --git a/docs/udon-test-kit/how-to/checking-calls-made-by-name.md b/docs/udon-test-kit/how-to/checking-calls-made-by-name.md index 611d0d5..340b4d2 100644 --- a/docs/udon-test-kit/how-to/checking-calls-made-by-name.md +++ b/docs/udon-test-kit/how-to/checking-calls-made-by-name.md @@ -56,10 +56,14 @@ Mode tests can use it: Unity won't add a behaviour from the Edit Mode test assem ## What to watch for -Outside Udon, as in a test, a call by name reaches only a public method with no parameters and -exactly that name. A misspelled name does nothing and raises no error, so always assert on what the -log recorded, not just that nothing failed. +A spy, and code a test adds with `AddComponent`, runs as plain C#. There, a call by name reaches +only a public method with no parameters and exactly that name. A misspelled name does nothing and +raises no error, so always assert on what the log recorded, not just that nothing failed. `SendCustomEventDelayedSeconds` and `SendCustomEventDelayedFrames` never call anything outside Udon. When the code under test delays a call that way, call the delayed method directly from the -test. +test, or run the code as Udon, where the delayed call arrives, as in +[Run your behaviours as Udon](./running-behaviours-as-udon#wait-for-delayed-events). + +To check the calls of code that runs as Udon, see +[Check the calls Udon code makes](./checking-calls-made-from-udon). diff --git a/docs/udon-test-kit/how-to/checking-calls-made-from-udon.md b/docs/udon-test-kit/how-to/checking-calls-made-from-udon.md new file mode 100644 index 0000000..cae5f4e --- /dev/null +++ b/docs/udon-test-kit/how-to/checking-calls-made-from-udon.md @@ -0,0 +1,73 @@ +--- +id: checking-calls-made-from-udon +title: Check the calls Udon code makes +sidebar_position: 6 +--- + +# Check the calls Udon code makes + +When your code runs as Udon, through [`UdonHost`](../reference/udon-host), give it test doubles that +run as Udon too, and have each double record the calls it gets in an +[`UdonCallLog`](../reference/udon-call-log). For code that runs as plain C#, a `CallbackSpy` does +this instead, as in [Check the calls your code makes by name](./checking-calls-made-by-name). + +## Create an assembly for Udon test doubles + +Do this once per project. The `Doubles` assembly that the kit creates compiles only for tests, and +UdonSharp compiles only player assemblies for a world upload, so `UdonHost` refuses doubles in it. +Doubles that run as Udon go in a player assembly of their own: + +1. Create a folder for them, such as `Tests/UdonDoubles`. +2. In it, create an assembly definition (**Assets > Create > Assembly Definition**), such as + `MyWorld.Tests.UdonDoubles`. Add `Tsvrc.UdonTestKit.UdonSpies` and `UdonSharp.Runtime` to its + references, plus any assembly of yours that its doubles use. Leave it on **Any Platform**, with + no define constraints, so it stays in player builds. +3. Next to it, create a U# assembly definition (**Assets > Create > U# Assembly Definition**) and + set its source assembly to the assembly definition from step 2. +4. Add the new assembly to the references of your Play Mode test assembly, if it isn't listed + already. Test assemblies created after it reference it from the start. + +The assembly compiles into the player builds of your world, but a world holds the program of a +double only when one of its scenes has that double. + +## Write a double + +In that folder, create the double with **Assets > Create > U# Script**, which also creates its +program asset. Give it a field for the log and a method for each call your code makes, which adds +the call to the log: + +```csharp +using Tsvrc.UdonTestKit; +using UdonSharp; + +public class RoundListenerDouble : UdonSharpBehaviour +{ + public UdonCallLog Log; + + public void OnRoundEnded() + { + Log.Add(name + ".OnRoundEnded"); + } +} +``` + +## Check the calls + +In a test class that extends [`UdonTestBase`](../reference/udon-test-base), create the log, the +double and the behaviour under test, connect them, act, and assert on what the log recorded: + +```csharp +UdonBehaviour log = Udon.Create("Log"); +UdonBehaviour listener = Udon.Create("Listener"); +listener.SetProgramVariable(nameof(RoundListenerDouble.Log), log); +UdonBehaviour referee = Udon.Create("Referee"); +referee.SetProgramVariable(nameof(RoundReferee.Listener), listener); + +referee.SendCustomEvent(nameof(RoundReferee.EndRound)); + +Assert.That(UdonHost.Calls(log), Is.EqualTo(new[] { "Listener.OnRoundEnded" })); +``` + +A field that holds an `UdonSharpBehaviour` takes the `UdonBehaviour` that `Create` returned. +Doubles that share a log record into it in the order the calls arrive, so one assertion covers +several doubles and the order between them. diff --git a/docs/udon-test-kit/how-to/checking-what-a-world-build-holds.md b/docs/udon-test-kit/how-to/checking-what-a-world-build-holds.md new file mode 100644 index 0000000..fd5d612 --- /dev/null +++ b/docs/udon-test-kit/how-to/checking-what-a-world-build-holds.md @@ -0,0 +1,61 @@ +--- +id: checking-what-a-world-build-holds +title: Check which programs your world build holds +sidebar_position: 11 +--- + +# Check which programs your world build holds + +A world build holds the program of a behaviour only when the scene has that behaviour. To check +that a behaviour your world needs reaches the build, or that one meant only for the Editor stays +out, build the scene in an Edit Mode test with [`BuiltWorld`](../reference/built-world). + +## Steps + +1. In your `Tests/EditMode` folder, create a test class that opens your world scene and builds it + once for all its tests: + + ```csharp + using NUnit.Framework; + using Tsvrc.UdonTestKit; + using UnityEditor.SceneManagement; + + public class WorldBuildTests + { + private BuiltWorld _world; + + [OneTimeSetUp] + public void BuildTheWorld() + { + EditorSceneManager.OpenScene("Assets/Scenes/MyWorld.unity"); + _world = BuiltWorld.FromOpenScene(); + } + } + ``` + +2. Add a test for each behaviour to check: + + ```csharp + [Test] + public void HoldsProgramOf_Scoreboard_IsTrue() + { + Assert.That(_world.HoldsProgramOf(typeof(Scoreboard)), Is.True); + } + + [Test] + public void HoldsProgramOf_DebugMenu_IsFalse() + { + Assert.That(_world.HoldsProgramOf(typeof(DebugMenu)), Is.False); + } + ``` + +3. Run them from the **EditMode** tab of the Test Runner. + +## What to watch for + +The build holds each program as UdonSharp last compiled it for the Editor, because it skips the +compile for upload. To check that compile too, see +[Check that your world compiles for upload](./checking-your-world-compiles-for-upload). + +The scene has to be saved and have exactly one scene descriptor, or the VRChat SDK builds nothing. +`FromOpenScene` checks both first and throws an error that says which. diff --git a/docs/udon-test-kit/how-to/checking-your-world-compiles-for-upload.md b/docs/udon-test-kit/how-to/checking-your-world-compiles-for-upload.md new file mode 100644 index 0000000..757bace --- /dev/null +++ b/docs/udon-test-kit/how-to/checking-your-world-compiles-for-upload.md @@ -0,0 +1,43 @@ +--- +id: checking-your-world-compiles-for-upload +title: Check that your world compiles for upload +sidebar_position: 10 +--- + +# Check that your world compiles for upload + +Before a world upload, UdonSharp compiles every program again, for upload, and a program that +compiles in the Editor can fail there. Check it in an Edit Mode test with +[`UdonSharpUploadCompile`](../reference/udon-sharp-upload-compile), so a failure shows up before you +upload. + +## Steps + +1. In your `Tests/EditMode` folder, create `UploadCompileTests.cs`: + + ```csharp + using NUnit.Framework; + using Tsvrc.UdonTestKit; + + public class UploadCompileTests + { + [Test] + public void UploadCompile_EveryProgram_LogsNoErrors() + { + Assert.That(UdonSharpUploadCompile.Run(), Is.Empty); + } + } + ``` + +2. Run it from the **EditMode** tab of the Test Runner. It compiles every UdonSharp program in the + project for upload, then for the Editor again, so it takes longer than most tests. + +When a program fails, the test fails with the error UdonSharp logged. + +## What makes the compile fail + +The compile for upload reads only player assemblies and leaves out the code inside +`#if UNITY_EDITOR`. A program asset whose script is in a tests-only assembly makes it compile no +program at all, and code that compiles only together with code inside `#if UNITY_EDITOR` fails it. +[What the kit works around](../explanations/what-the-kit-works-around#udon-code-that-compiles-for-the-editor-but-not-for-upload) +explains both. diff --git a/docs/udon-test-kit/how-to/fixing-clientsim-project-settings.md b/docs/udon-test-kit/how-to/fixing-clientsim-project-settings.md index 8e3a25b..32d1d7b 100644 --- a/docs/udon-test-kit/how-to/fixing-clientsim-project-settings.md +++ b/docs/udon-test-kit/how-to/fixing-clientsim-project-settings.md @@ -1,7 +1,7 @@ --- id: fixing-clientsim-project-settings title: Fix the project settings ClientSim rejects -sidebar_position: 9 +sidebar_position: 13 --- # Fix the project settings ClientSim rejects diff --git a/docs/udon-test-kit/how-to/keeping-editor-tooling-out-of-test-runs.md b/docs/udon-test-kit/how-to/keeping-editor-tooling-out-of-test-runs.md index d8c0f96..1bafb25 100644 --- a/docs/udon-test-kit/how-to/keeping-editor-tooling-out-of-test-runs.md +++ b/docs/udon-test-kit/how-to/keeping-editor-tooling-out-of-test-runs.md @@ -1,7 +1,7 @@ --- id: keeping-editor-tooling-out-of-test-runs title: Keep editor tooling from reacting to a test run -sidebar_position: 7 +sidebar_position: 9 --- # Keep editor tooling from reacting to a test run diff --git a/docs/udon-test-kit/how-to/running-behaviours-as-udon.md b/docs/udon-test-kit/how-to/running-behaviours-as-udon.md new file mode 100644 index 0000000..00b4766 --- /dev/null +++ b/docs/udon-test-kit/how-to/running-behaviours-as-udon.md @@ -0,0 +1,92 @@ +--- +id: running-behaviours-as-udon +title: Run your behaviours as Udon +sidebar_position: 5 +--- + +# Run your behaviours as Udon + +A behaviour a test adds with `AddComponent` runs as plain C#. To test what Udon does with your +code, such as halting a behaviour that throws, run it as its compiled Udon program with +[`UdonHost`](../reference/udon-host), in a Play Mode test. + +The behaviour needs a program asset, which a script made with **Assets > Create > U# Script** has. +Its assembly has to be in player builds and referenced by your Play Mode test assembly, as the +assembly definitions of your world are. + +## Steps + +1. Extend [`UdonTestBase`](../reference/udon-test-base) in your Play Mode test class: + + ```csharp + public class DoorTests : UdonTestBase + { + } + ``` + +2. In a test, create the behaviour with `Udon.Create`. It returns the `UdonBehaviour` that runs the + program: + + ```csharp + UdonBehaviour door = Udon.Create("Door"); + ``` + +3. Arrange and drive it by the names of its fields and methods, then assert on its fields: + + ```csharp + door.SetProgramVariable(nameof(Door.IsLocked), false); + + door.SendCustomEvent(nameof(Door.Open)); + + Assert.That(door.GetProgramVariable(nameof(Door.IsOpen)), Is.EqualTo(true)); + ``` + +`UdonTestBase` destroys the GameObjects `Udon` created after every test. + +## Check that your code throws + +When code that runs as Udon throws, Udon halts the behaviour and logs an error, which fails the test +unless the test expects it. Expect it with `UdonHost.ExpectUdonException`, from a `[UnityTest]`: + +```csharp +[UnityTest] +public IEnumerator Unlock_NoKeyAssigned_HaltsTheDoor() +{ + UdonBehaviour door = Udon.Create("Door"); + + yield return UdonHost.ExpectUdonException(() => door.SendCustomEvent(nameof(Door.Unlock))); +} +``` + +The test fails if `Unlock` doesn't throw. + +## Wait for delayed events + +When your code delays an event with `SendCustomEventDelayedFrames` or +`SendCustomEventDelayedSeconds`, Udon runs it on a later frame, once the delay passed, and never +during the call that delays it. Wait for it in a `[UnityTest]`, longer than the delay: + +```csharp +[UnityTest] +public IEnumerator OpenInASecond_AfterTheSecond_OpensTheDoor() +{ + UdonBehaviour door = Udon.Create("Door"); + + door.SendCustomEvent(nameof(Door.OpenInASecond)); + yield return new WaitForSeconds(1.5f); + + Assert.That(door.GetProgramVariable(nameof(Door.IsOpen)), Is.EqualTo(true)); +} +``` + +## Behaviours that need players + +`UdonTestBase` extends `ClientSimTestBase`, so start the session first, as in any ClientSim test: + +```csharp +yield return Session.Start(); +UdonBehaviour door = Udon.Create("Door"); +``` + +To run these tests in a scene of their own, pass a [`TestScene`](../reference/test-scene) to the +[`UdonTestBase` constructor](../reference/udon-test-base#constructors). diff --git a/docs/udon-test-kit/how-to/running-tests-from-the-command-line.md b/docs/udon-test-kit/how-to/running-tests-from-the-command-line.md index b188263..3897f49 100644 --- a/docs/udon-test-kit/how-to/running-tests-from-the-command-line.md +++ b/docs/udon-test-kit/how-to/running-tests-from-the-command-line.md @@ -1,18 +1,25 @@ --- id: running-tests-from-the-command-line title: Run tests from the command line -sidebar_position: 8 +sidebar_position: 12 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Run tests from the command line -[`Invoke-UnityTests.ps1`](../reference/invoke-unity-tests) runs a Unity project's tests from -PowerShell on Windows and prints only what needs your attention: the tests that didn't pass, with -their messages, and a count of the rest. It's a generic script, independent of the kit: copy it -into any Unity project to use it there, whether or not that project has the kit. +[`Invoke-UnityTests.ps1`](../reference/invoke-unity-tests) on Windows and +[`run_unity_tests.sh`](../reference/run-unity-tests) on Linux run a Unity project's tests from the +command line and print only what needs your attention: the tests that didn't pass, with their +messages, and a count of the rest. They're generic scripts, independent of the kit: copy one into +any Unity project to use it there, whether or not that project has the kit. ## Steps + + + 1. Get the script: `Scripts~/Invoke-UnityTests.ps1` in the [kit's repository](https://github.com/tsvrc/udon-test-kit). If you installed the kit through the Creator Companion, it's also in `Packages/com.tsvrc.udon-test-kit/Scripts~`. A `.unitypackage` @@ -20,34 +27,82 @@ into any Unity project to use it there, whether or not that project has the kit. 2. Copy it into your project, such as its root folder. It finds the project by looking up from its own folder. 3. Close the Unity Editor. Batch mode can't open a project another Editor has open. -4. Run it from that folder: +4. Run it from that folder, in PowerShell: ```powershell .\Invoke-UnityTests.ps1 ``` -It runs your project's Edit Mode tests, then its Play Mode tests, each in its own batch-mode Unity -process, and exits with 1 when a test failed or was inconclusive, or a run didn't finish. That makes -it usable as a build step as it is. +If PowerShell refuses to run the script because of its execution policy, allow local scripts once +with `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`. + + + + +1. Get the script: `Scripts~/run_unity_tests.sh` in the + [kit's repository](https://github.com/tsvrc/udon-test-kit), or in + `Packages/com.tsvrc.udon-test-kit/Scripts~` of a project that has the kit installed as a package. + A `.unitypackage` can't carry it. +2. Copy it into your project, such as its root folder, and make the copy executable with + `chmod +x run_unity_tests.sh`. It finds the project by looking up from its own folder. +3. Close the Unity Editor. Batch mode can't open a project another Editor has open. +4. Run it from that folder, in Bash, with the Windows build target: + + ```bash + ./run_unity_tests.sh -- -buildTarget win64 + ``` + +The kit needs the Windows build target on Linux. Everything after `--` goes to Unity, and in batch +mode, Unity opens a project it hasn't imported yet on the Linux build target unless +`-buildTarget` says otherwise. + + + + +Each script runs your project's Edit Mode tests, then its Play Mode tests, each mode in its own +batch-mode Unity process, and exits with 1 when a test failed or was inconclusive, or a run didn't +finish. That makes either one usable as a build step as it is. ## Run part of the tests -Run one mode: +By default, each script runs the tests in every assembly definition under `Assets` and in scripts +without one, and leaves out the tests that come with packages. To run one mode: + + + ```powershell .\Invoke-UnityTests.ps1 -TestMode PlayMode ``` -Run particular test assemblies, separated with `;`: + + + +```bash +./run_unity_tests.sh --test-mode PlayMode -- -buildTarget win64 +``` + + + + +To run particular test assemblies, separated with `;`: + + + ```powershell .\Invoke-UnityTests.ps1 -AssemblyNames "MyWorld.Tests.EditMode;MyWorld.Tests.PlayMode" ``` -By default, the script runs the tests in every assembly definition under `Assets` and in scripts -without one, and leaves out the tests that come with packages. The -[reference page](../reference/invoke-unity-tests) lists every option, including where it looks for -Unity and where it writes results. + + -If PowerShell refuses to run the script because of its execution policy, allow local scripts once -with `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`. +```bash +./run_unity_tests.sh --assembly-names "MyWorld.Tests.EditMode;MyWorld.Tests.PlayMode" -- -buildTarget win64 +``` + + + + +The reference pages list every option, including where each script looks for Unity, where it +writes results, and how it passes other arguments to Unity. diff --git a/docs/udon-test-kit/how-to/sharing-a-session-between-tests.md b/docs/udon-test-kit/how-to/sharing-a-session-between-tests.md index 5f2afb0..8f07452 100644 --- a/docs/udon-test-kit/how-to/sharing-a-session-between-tests.md +++ b/docs/udon-test-kit/how-to/sharing-a-session-between-tests.md @@ -1,7 +1,7 @@ --- id: sharing-a-session-between-tests title: Share one session between the tests in a class -sidebar_position: 5 +sidebar_position: 7 --- # Share one session between the tests in a class diff --git a/docs/udon-test-kit/how-to/testing-saved-data.md b/docs/udon-test-kit/how-to/testing-saved-data.md index ab39040..ea57a60 100644 --- a/docs/udon-test-kit/how-to/testing-saved-data.md +++ b/docs/udon-test-kit/how-to/testing-saved-data.md @@ -53,7 +53,5 @@ yield return Session.Start(); ``` `DeleteSavedData` deletes what ClientSim saved for the active scene, for every player. In your -world's own scene, those files are also the ones you get when you press Play. - -Unity Test Framework names its test scene differently on every run, so each run leaves a few files -in `ClientSimStorage` that no later run reads. Delete them whenever you like. +world's own scene, those files are also the ones you get when you press Play. What tests save in +the Unity Test Framework test scene, the kit deletes when the run ends. diff --git a/docs/udon-test-kit/how-to/testing-scripts-without-an-assembly-definition.md b/docs/udon-test-kit/how-to/testing-scripts-without-an-assembly-definition.md index 25d4a32..20c6c30 100644 --- a/docs/udon-test-kit/how-to/testing-scripts-without-an-assembly-definition.md +++ b/docs/udon-test-kit/how-to/testing-scripts-without-an-assembly-definition.md @@ -1,7 +1,7 @@ --- id: testing-scripts-without-an-assembly-definition title: Test scripts that have no assembly definition -sidebar_position: 10 +sidebar_position: 14 --- # Test scripts that have no assembly definition @@ -15,8 +15,8 @@ when your project has such scripts. Put the tests in any folder named `Editor` that has no assembly definition. Unity compiles them into `Assembly-CSharp-Editor`, which can use your scripts, NUnit and the kit without any -references set up. The Unity Test Runner finds them there, and so does -[`Invoke-UnityTests.ps1`](../reference/invoke-unity-tests). +references set up. The Unity Test Runner finds them there, and so do the scripts that +[run tests from the command line](./running-tests-from-the-command-line). ## Play Mode tests diff --git a/docs/udon-test-kit/intro.md b/docs/udon-test-kit/intro.md index 268961b..207d378 100644 --- a/docs/udon-test-kit/intro.md +++ b/docs/udon-test-kit/intro.md @@ -29,14 +29,17 @@ go into more depth. - Give any GameObject an owner, to test what a player who doesn't own it sees. - Keep saved data between sessions, like a player who leaves and rejoins. - Record the calls your code makes by name, such as with `SendCustomEvent`. +- Run your behaviours as their compiled Udon programs, to see what Udon does with your code. +- Check that your world compiles for upload, and which programs its build holds. - Run each test in a scene of its own, empty or your world's. - Create the test assemblies your world needs from one menu item. -The kit only compiles for tests, so nothing from it ends up in your world's build. +The kit stays out of your world build: everything but one Udon spy compiles only for tests, and +that spy reaches a world only when a scene has one. -It also includes `Invoke-UnityTests.ps1`, a standalone PowerShell script that runs a project's -tests in one command and prints only what failed. It works in any Unity project, with or without -the kit. +It also includes two standalone scripts that run the tests of a project in one command and print +only what failed: `Invoke-UnityTests.ps1` for PowerShell on Windows and `run_unity_tests.sh` for +Bash on Linux. They work in any Unity project, with or without the kit. ## Get started @@ -48,6 +51,8 @@ the kit. - [Run tests in a scene of their own](./how-to/running-tests-in-their-own-scene) - [Test what happens for a player who isn't the owner](./how-to/testing-a-player-who-isnt-the-owner) - [Check that saved data survives a rejoin](./how-to/testing-saved-data) +- [Run your behaviours as Udon](./how-to/running-behaviours-as-udon) +- [Check that your world compiles for upload](./how-to/checking-your-world-compiles-for-upload) - [Run tests from the command line](./how-to/running-tests-from-the-command-line) ## Reference and background diff --git a/docs/udon-test-kit/reference/built-world.md b/docs/udon-test-kit/reference/built-world.md new file mode 100644 index 0000000..98741ba --- /dev/null +++ b/docs/udon-test-kit/reference/built-world.md @@ -0,0 +1,73 @@ +--- +id: built-world +title: BuiltWorld +sidebar_position: 11 +--- + +# BuiltWorld + +`Tsvrc.UdonTestKit.BuiltWorld` builds the open scene into a world file with the VRChat SDK, reads +what the file holds and deletes it, so a test can check what a world build holds, such as which +UdonSharp programs reach it. + +```csharp +public class WorldBuildTests +{ + private BuiltWorld _world; + + [OneTimeSetUp] + public void BuildTheWorld() + { + EditorSceneManager.OpenScene("Assets/Scenes/MyWorld.unity"); + _world = BuiltWorld.FromOpenScene(); + } + + [Test] + public void HoldsProgramOf_Scoreboard_IsTrue() + { + Assert.That(_world.HoldsProgramOf(typeof(Scoreboard)), Is.True); + } +} +``` + +Use it in an Edit Mode test. A build takes a while, so build once per fixture, in +`[OneTimeSetUp]`, and check the result in each test. +[Check which programs your world build holds](../how-to/checking-what-a-world-build-holds) walks +through it. + +## Members + +- `BuiltWorld.FromOpenScene()` is static. It builds the open scene with the world exporter of the + VRChat SDK, reads the world file and deletes it, and returns what it read. +- `Text` is every object in the world file, as text. The `WebExtract` and `binary2text` tools that + ship with the Unity Editor unpack the file and turn it into text. +- `HoldsProgramOf(Type udonSharpClass)` is true when the world holds the compiled program of that + UdonSharp class. A program is in the world when the scene has a behaviour that runs it. + +## What the build skips + +`FromOpenScene` builds without the callbacks the VRChat SDK runs before a build, and one of them is +the UdonSharp compile for upload. The world holds each program as UdonSharp last compiled it for +the Editor. To check the compile for upload, use +[`UdonSharpUploadCompile`](./udon-sharp-upload-compile). + +## Failure modes + +- The world exporter of the VRChat SDK builds only a saved scene with exactly one scene + descriptor. It asks about the descriptors with a dialog, and on Windows about a scene never + saved too, and outside batch mode a dialog waits for a click. `FromOpenScene` checks both first + and throws an `InvalidOperationException` instead, in every mode: + - `The open scene has 0 scene descriptors. The world exporter of the VRChat SDK builds a scene with exactly one.` + An inactive descriptor counts, as it does for the exporter. + - `The open scene was never saved. The world exporter of the VRChat SDK builds only a saved scene.` + Unsaved changes to a saved scene don't matter: the exporter builds it as it is. +- `HoldsProgramOf` throws the same errors as [`UdonHost.Create`](./udon-host#creating-behaviours) + for a class without a program asset, or in an assembly that player builds leave out. + +## Edge cases + +- The exporter records the path of the world file in `EditorPrefs`, which every Unity project of + the same user shares. `FromOpenScene` puts back the path recorded before the build. +- It reads the world in a new folder under the `Temp` folder of the project and deletes the folder + afterwards, so a build in another project, or another test run, at the same time can't delete its + files. diff --git a/docs/udon-test-kit/reference/callback-spy-and-call-log.md b/docs/udon-test-kit/reference/callback-spy-and-call-log.md index a2cd9f3..5de549d 100644 --- a/docs/udon-test-kit/reference/callback-spy-and-call-log.md +++ b/docs/udon-test-kit/reference/callback-spy-and-call-log.md @@ -1,7 +1,7 @@ --- id: callback-spy-and-call-log title: CallbackSpy and CallLog -sidebar_position: 4 +sidebar_position: 6 --- # CallbackSpy and CallLog @@ -63,13 +63,16 @@ Editor-only assembly to a GameObject, and an Edit Mode test assembly is Editor-o ## Calls by name outside Udon -Tests run your UdonSharpBehaviours as plain C#, not as Udon. In that mode, `SendCustomEvent` -calls a public method with no parameters and exactly the given name. Any other name does nothing -and raises no error, so a misspelled callback name passes silently: check what the log recorded, -not just that nothing failed. +A `CallbackSpy`, like any behaviour a test adds with `AddComponent`, runs as plain C#, not as Udon. +To record calls made by code that runs as Udon, use [`UdonCallLog`](./udon-call-log) instead. + +As plain C#, `SendCustomEvent` calls a public method with no parameters and exactly the given name. +Any other name does nothing and raises no error, so a misspelled callback name passes silently: +check what the log recorded, not just that nothing failed. `SendCustomEventDelayedSeconds` and `SendCustomEventDelayedFrames` don't call anything outside -Udon. Code under test that relies on them needs its delayed method called directly from the test. +Udon. Code under test that relies on them needs its delayed method called directly from the test, +or has to run as Udon, through [`UdonHost`](./udon-host#edge-cases). ## Failure modes diff --git a/docs/udon-test-kit/reference/clientsim-project-settings.md b/docs/udon-test-kit/reference/clientsim-project-settings.md index 7aa01b0..88fd178 100644 --- a/docs/udon-test-kit/reference/clientsim-project-settings.md +++ b/docs/udon-test-kit/reference/clientsim-project-settings.md @@ -1,7 +1,7 @@ --- id: clientsim-project-settings title: ClientSimProjectSettings -sidebar_position: 7 +sidebar_position: 12 --- # ClientSimProjectSettings diff --git a/docs/udon-test-kit/reference/clientsim-session.md b/docs/udon-test-kit/reference/clientsim-session.md index a2d2477..98cab3a 100644 --- a/docs/udon-test-kit/reference/clientsim-session.md +++ b/docs/udon-test-kit/reference/clientsim-session.md @@ -48,7 +48,9 @@ If ClientSim isn't ready within 10 seconds, `Start` throws a `TimeoutException`. `SpawnRemotePlayer(string displayName)` spawns a remote player and returns it. The player is in the player list by the time the call returns, so a test can assert on it in the same frame. The -returned player is looked up by display name, so give every player its own. +session finds the new player by its display name, so it throws an `ArgumentException` for an empty +name or one a player in the session has already, the local player included. The name of a removed +player can be used again. `RemovePlayer(VRCPlayerApi player)` removes a player, also within the call. @@ -99,9 +101,10 @@ ClientSim saves each player's data in your project folder, one file per player a - `ClientSimStorage/PlayerObjects/PlayerObject__.json` `ClientSimSession.DeleteSavedData()` is static and deletes both kinds of file for the active scene, -for every player. Nothing else in the kit deletes saved data: in your world's own scene, those -files are your ClientSim data. [Check that saved data survives a rejoin](../how-to/testing-saved-data) -uses both. +for every player. [Check that saved data survives a rejoin](../how-to/testing-saved-data) uses +both. -Unity Test Framework gives its test scene a new name on every run, so each run leaves a few files -in `ClientSimStorage` that no later run reads. You can delete them whenever you like. +When a test run ends, the kit deletes the files of the scene Unity Test Framework runs Play Mode +tests in, named `InitTestScene` and digits, so test runs don't fill `ClientSimStorage`. It deletes +nothing else on its own: the files of your world's own scene are your ClientSim data, and the files +of a [`TestScene`](./test-scene) stay too. diff --git a/docs/udon-test-kit/reference/invoke-unity-tests.md b/docs/udon-test-kit/reference/invoke-unity-tests.md index 5da4c5d..3376ba0 100644 --- a/docs/udon-test-kit/reference/invoke-unity-tests.md +++ b/docs/udon-test-kit/reference/invoke-unity-tests.md @@ -1,7 +1,7 @@ --- id: invoke-unity-tests title: Invoke-UnityTests.ps1 -sidebar_position: 9 +sidebar_position: 14 --- # Invoke-UnityTests.ps1 @@ -10,7 +10,7 @@ sidebar_position: 9 report. It's a single, standalone file: it doesn't use the kit or anything else beyond Unity Test Framework, and it's meant to be copied into any Unity project that wants it, with or without the kit. [Run tests from the command line](../how-to/running-tests-from-the-command-line) walks through -using it. +using it, and [`run_unity_tests.sh`](./run-unity-tests) does the same from Bash on Linux. ## Getting it @@ -41,12 +41,24 @@ Close the Unity Editor first: batch mode can't open a project that another Edito | `-ProjectPath` | The nearest folder with a `ProjectSettings\ProjectVersion.txt`, looking up from the script's folder, then from the current folder. | | `-UnityPath` | The Editor version in `ProjectVersion.txt`, in the Unity Hub default install folder under `Program Files`. | | `-ResultsPath` | A new folder under the temp folder, named after the date and time. | +| Any other argument | Goes to Unity, after the arguments of the script. | Without assembly names, Unity runs every test it finds, including the tests that come with -packages, such as the VRChat SDK. The default list is every assembly definition under `Assets`, -plus the assemblies Unity compiles scripts without one into (`Assembly-CSharp`, +packages, such as the VRChat SDK. The default list is every assembly definition Unity imports under +`Assets`, plus the assemblies Unity compiles scripts without one into (`Assembly-CSharp`, `Assembly-CSharp-firstpass`, `Assembly-CSharp-Editor` and `Assembly-CSharp-Editor-firstpass`), so -tests in `Editor` folders run too. A name with no tests in it is harmless. +tests in `Editor` folders run too. Like Unity, it skips folders with the Windows Hidden attribute, +files and folders whose names start with a dot, and folders whose names end with `~`. A name with +no tests in it is harmless. + +Arguments the script doesn't know go to Unity, such as a build target: + +```powershell +.\Invoke-UnityTests.ps1 -buildTarget win64 +``` + +The Unity manual lists them under +[Editor command line arguments](https://docs.unity3d.com/2022.3/Documentation/Manual/EditorCommandLineArguments.html). ## What it does @@ -72,6 +84,9 @@ The script exits with 1 when Unity reported a failed or inconclusive test, or a out, and when a mode wrote no results, in which case it prints the log's path. Otherwise it exits with 0, so a build server can use it as a step that fails the build. +It also exits with 1, without starting Unity, when it finds no project or no Unity, or can't create +the results folder, such as when `-ResultsPath` names a file. Its message says which. + ## Execution policy If PowerShell refuses to run the script because of its execution policy, allow local scripts once: diff --git a/docs/udon-test-kit/reference/private-field-access.md b/docs/udon-test-kit/reference/private-field-access.md index b753a02..3d661bf 100644 --- a/docs/udon-test-kit/reference/private-field-access.md +++ b/docs/udon-test-kit/reference/private-field-access.md @@ -1,7 +1,7 @@ --- id: private-field-access title: PrivateFieldAccess -sidebar_position: 5 +sidebar_position: 8 --- # PrivateFieldAccess diff --git a/docs/udon-test-kit/reference/run-unity-tests.md b/docs/udon-test-kit/reference/run-unity-tests.md new file mode 100644 index 0000000..39b6924 --- /dev/null +++ b/docs/udon-test-kit/reference/run-unity-tests.md @@ -0,0 +1,78 @@ +--- +id: run-unity-tests +title: run_unity_tests.sh +sidebar_position: 15 +--- + +# run_unity_tests.sh + +`run_unity_tests.sh` runs a Unity project's tests from Bash on Linux and prints a short report. It's +a single, standalone file: it doesn't use the kit or anything else beyond Unity Test Framework, and +it's meant to be copied into any Unity project that wants it, with or without the kit. +[Run tests from the command line](../how-to/running-tests-from-the-command-line) walks +through using it, and [`Invoke-UnityTests.ps1`](./invoke-unity-tests) does the same from PowerShell +on Windows. + +## Getting it + +The script is `Scripts~/run_unity_tests.sh` in the +[kit's repository](https://github.com/tsvrc/udon-test-kit). An installed kit package also has it on +disk, under `Packages/com.tsvrc.udon-test-kit/Scripts~`, unless it came from a `.unitypackage`: +Unity doesn't import folders ending in `~`, so a `.unitypackage` can't include it. + +Copy it anywhere inside your project, such as its root folder, and make the copy executable with +`chmod +x run_unity_tests.sh`. It finds the project by looking up from its own folder. It needs +Bash 4 or later and `awk`. + +## Running it + +Close the Unity Editor first: batch mode can't open a project that another Editor has open. Then: + +```bash +./run_unity_tests.sh +``` + +`./run_unity_tests.sh --help` lists the same options as the table below. + +## Options + +| Option | Default | +| --- | --- | +| `-m`, `--test-mode` | `All`, which runs `EditMode` and then `PlayMode`. Pass one of those to run one mode. | +| `-a`, `--assembly-names` | Your project's own assemblies, separated with `;` (see below). | +| `-p`, `--project-path` | The nearest folder with a `ProjectSettings/ProjectVersion.txt`, looking up from the script's folder, then from the current folder. | +| `-u`, `--unity-path` | The Editor version in `ProjectVersion.txt`, in the Unity Hub default install folder, `~/Unity/Hub/Editor`. | +| `-r`, `--results-path` | A new folder under `$TMPDIR`, or `/tmp` when it isn't set, named after the date and time. | +| `-h`, `--help` | Prints the options. | +| `-- ARGUMENTS` | Everything after `--` goes to Unity, after the arguments of the script. | + +Without assembly names, Unity runs every test it finds, including the tests that come with +packages, such as the VRChat SDK. The default list is every assembly definition Unity imports under +`Assets`, plus the assemblies Unity compiles scripts without one into (`Assembly-CSharp`, +`Assembly-CSharp-firstpass`, `Assembly-CSharp-Editor` and `Assembly-CSharp-Editor-firstpass`), so +tests in `Editor` folders run too. Like Unity, it skips files and folders whose names start with a +dot, and folders whose names end with `~`. A name with no tests in it is harmless. + +Arguments for Unity go after `--`, such as a build target: + +```bash +./run_unity_tests.sh -- -buildTarget win64 +``` + +The Unity manual lists them under +[Editor command line arguments](https://docs.unity3d.com/2022.3/Documentation/Manual/EditorCommandLineArguments.html). + +## What it does + +Each test mode starts Unity once, in batch mode, with `-runTests`. Unity writes the results of the +mode to `.xml` and its log to `.log` in the results folder. For each mode, the script +prints every test that didn't pass, with its result and message, then a count of the tests that +passed, failed, and were inconclusive or skipped. + +## Exit code + +- 0 when every test passed or was skipped. +- 1 when Unity reported a failed or inconclusive test, or a run that errored out, or when a mode + wrote no results, in which case it prints the path of the log. It also exits with 1, without + starting Unity, when it finds no project or no Unity, or can't create the results folder. +- 2 when the options are wrong, such as an unknown option or a test mode other than the three. diff --git a/docs/udon-test-kit/reference/test-assembly-creator.md b/docs/udon-test-kit/reference/test-assembly-creator.md index 0207d92..5f8812b 100644 --- a/docs/udon-test-kit/reference/test-assembly-creator.md +++ b/docs/udon-test-kit/reference/test-assembly-creator.md @@ -1,7 +1,7 @@ --- id: test-assembly-creator title: TestAssemblyCreator -sidebar_position: 8 +sidebar_position: 13 --- # TestAssemblyCreator @@ -32,17 +32,23 @@ or symbols. A name that ends up empty, or starts with a digit, becomes `World`. When assemblies with those names already exist, the new ones get a number, such as `MyWorld2.Tests.EditMode`. Two assemblies with the same name stop a project compiling. -Each assembly references the kit, UdonSharp, the VRChat SDK, ClientSim, and every assembly -definition of yours with scripts under `Assets`, other than test assemblies. The two test assemblies -also reference the doubles assembly and Unity Test Framework. All three compile only when Unity -Test Framework includes tests, so none of them reaches a world build, and none is referenced -automatically by other assemblies. +Each assembly references both kit assemblies, `Tsvrc.UdonTestKit` and +`Tsvrc.UdonTestKit.UdonSpies`, along with UdonSharp, the VRChat SDK with Udon, ClientSim, and every +assembly definition of yours with scripts under `Assets`, other than test assemblies. The two test +assemblies also reference the doubles assembly and Unity Test Framework. All three compile only +when Unity Test Framework includes tests, so none of them reaches a world build, and none is +referenced automatically by other assemblies. The `Doubles` assembly is for behaviours your tests add to GameObjects, such as [`CallbackSpy`](./callback-spy-and-call-log) subclasses. It has no NUnit reference. Unity won't add a behaviour from the Editor-only Edit Mode assembly to a GameObject, and Unity requires Edit Mode and Play Mode tests to be in separate assemblies, so behaviours both kinds of test use go here. +Test doubles that run as Udon, through [`UdonHost`](./udon-host), can't go in the `Doubles` +assembly. UdonSharp compiles only player assemblies for a world upload, and `Doubles` compiles only +for tests, so `UdonHost` refuses them. They need a player assembly of their own, as in +[Check the calls Udon code makes](../how-to/checking-calls-made-from-udon#create-an-assembly-for-udon-test-doubles). + Each example compiles and passes as created. ## Edge cases diff --git a/docs/udon-test-kit/reference/test-run.md b/docs/udon-test-kit/reference/test-run.md index 0dcb253..ea0177a 100644 --- a/docs/udon-test-kit/reference/test-run.md +++ b/docs/udon-test-kit/reference/test-run.md @@ -1,7 +1,7 @@ --- id: test-run title: TestRun -sidebar_position: 6 +sidebar_position: 9 --- # TestRun diff --git a/docs/udon-test-kit/reference/test-scene.md b/docs/udon-test-kit/reference/test-scene.md index cd0d805..27e8b9a 100644 --- a/docs/udon-test-kit/reference/test-scene.md +++ b/docs/udon-test-kit/reference/test-scene.md @@ -29,9 +29,10 @@ Neither one loads anything until `Load` runs. already loaded, so the Unity Test Framework test scene stays loaded, and makes it the active scene. It does nothing when the scene is already loaded. -`Unload()` makes the scene that was active before `Load` active again, then unloads this scene and -everything in it. It finishes before it returns, so it also works where a test can't wait, such as -in `[OneTimeTearDown]`. It does nothing when the scene isn't loaded. +`Unload()` unloads this scene and everything in it. When this scene is the active one, it first +makes the scene that was active before `Load` active again, if that scene is still loaded. It +finishes before it returns, so it also works where a test can't wait, such as in +`[OneTimeTearDown]`. It does nothing when the scene isn't loaded. `IsLoaded` is true between a `Load` that finished and the next `Unload`. diff --git a/docs/udon-test-kit/reference/udon-call-log.md b/docs/udon-test-kit/reference/udon-call-log.md new file mode 100644 index 0000000..2f2438a --- /dev/null +++ b/docs/udon-test-kit/reference/udon-call-log.md @@ -0,0 +1,62 @@ +--- +id: udon-call-log +title: UdonCallLog +sidebar_position: 7 +--- + +# UdonCallLog + +`Tsvrc.UdonTestKit.UdonCallLog` is a spy that runs as Udon. Test doubles that run as Udon call its +`Add` for each call they get, and a test reads the calls, in order, with +[`UdonHost.Calls`](./udon-host#reading-the-calls-of-an-udoncalllog). + +A test double that records into it is an `UdonSharpBehaviour` with a field for the log: + +```csharp +public class RoundListenerDouble : UdonSharpBehaviour +{ + public UdonCallLog Log; + + public void OnRoundEnded() + { + Log.Add(name + ".OnRoundEnded"); + } +} +``` + +The test creates both with [`UdonHost`](./udon-host), gives the double the log, and reads the calls: + +```csharp +UdonBehaviour log = Udon.Create("Log"); +UdonBehaviour listener = Udon.Create("Listener"); +listener.SetProgramVariable(nameof(RoundListenerDouble.Log), log); + +// Act: the code under test calls the listener. + +Assert.That(UdonHost.Calls(log), Is.EqualTo(new[] { "Listener.OnRoundEnded" })); +``` + +[Check the calls Udon code makes](../how-to/checking-calls-made-from-udon) walks through it, +including where the double goes. + +## Members + +- `Add(string call)` records a call, such as `"Listener.OnRoundEnded"`: the GameObject name, a dot + and the method. +- `Calls` holds the calls recorded so far as one string, each followed by `;`. `UdonHost.Calls` + splits it into an array, so a recorded call can't contain `;`. + +Its sync mode is None, so nothing it records is synced. + +## Its assembly + +`UdonCallLog` is in `Tsvrc.UdonTestKit.UdonSpies`, the one kit assembly that compiles into player +builds. UdonSharp compiles only player assemblies for a world upload, so a behaviour that runs as +Udon has to be in one. The assembly has a U# assembly definition, and `UdonCallLog` has its program +asset. + +The test assemblies [`TestAssemblyCreator`](./test-assembly-creator) creates reference the +assembly, and scripts without an assembly definition can use it directly. An assembly of Udon test +doubles needs `Tsvrc.UdonTestKit.UdonSpies` in its references. + +A world file holds the program of `UdonCallLog` only when a scene in the world has one. diff --git a/docs/udon-test-kit/reference/udon-host.md b/docs/udon-test-kit/reference/udon-host.md new file mode 100644 index 0000000..4d0183a --- /dev/null +++ b/docs/udon-test-kit/reference/udon-host.md @@ -0,0 +1,95 @@ +--- +id: udon-host +title: UdonHost +sidebar_position: 4 +--- + +# UdonHost + +`Tsvrc.UdonTestKit.UdonHost` runs UdonSharp behaviours in a Play Mode test as their compiled Udon +programs, the way VRChat runs them, instead of as their C# classes. Disposing it destroys the +GameObjects it created. [`UdonTestBase`](./udon-test-base) gives every test one, and +[Run your behaviours as Udon](../how-to/running-behaviours-as-udon) walks through using it. + +```csharp +using var udon = new UdonHost(); +UdonBehaviour door = udon.Create("Door"); + +door.SendCustomEvent(nameof(Door.Open)); + +Assert.That(door.GetProgramVariable(nameof(Door.IsOpen)), Is.EqualTo(true)); +``` + +A behaviour that a test adds with `AddComponent` runs as plain C#. One created with `UdonHost` runs +the program UdonSharp compiled from it, so the test sees what Udon does with that code, including +Udon halting the behaviour when it throws. + +## Creating behaviours + +`Create(string name, bool active = true)` creates a GameObject named `name` with an +`UdonBehaviour` that runs the compiled program of `T`, an `UdonSharpBehaviour`, and returns that +`UdonBehaviour`. The test reaches the program through it, by the names of the methods and fields +of `T`: `SendCustomEvent`, `SetProgramVariable` and `GetProgramVariable`. + +With `active: false`, the GameObject starts inactive, and the behaviour starts once the test +activates it. Udon runs the `Start` of a program on a later frame, so a test that checks what +`Start` did yields until `UdonBehaviour.HasDoneStart` is true. + +`Create` throws an `InvalidOperationException` that says what to do in two cases: + +- `T` has no program asset. A script made with **Assets > Create > U# Script** gets one along with + it. For a script without one, the error reads + `Door has no UdonSharp program asset. Create one with Assets > Create > VRChat > Udon > Udon C# Program Asset and set its Source Script.` +- `T` is in an assembly that player builds leave out. The compile UdonSharp runs for a world upload + reads only player assemblies, and a program asset whose script is in any other assembly makes + that compile log an error and compile no program at all. The error names the assembly and points + to **Assets > Create > U# Assembly Definition**. + +The second case covers the `Doubles` assembly that +[`TestAssemblyCreator`](./test-assembly-creator) creates, which compiles only for tests. Test +doubles that run as Udon need an assembly of their own, as in +[Check the calls Udon code makes](../how-to/checking-calls-made-from-udon#create-an-assembly-for-udon-test-doubles). +[What the kit works around](../explanations/what-the-kit-works-around#udon-code-that-compiles-for-the-editor-but-not-for-upload) +explains the upload compile. + +## Disposing + +`Dispose()` destroys every GameObject that `Create` made, skipping any the test destroyed already. +`using var udon = new UdonHost();` is all the cleanup a test needs. + +## Reading the calls of an UdonCallLog + +`UdonHost.Calls(UdonBehaviour log)` is static and returns the calls an +[`UdonCallLog`](./udon-call-log) recorded, in the order they arrived. Pass the `UdonBehaviour` that +`Create` returned. + +## Expecting an Udon exception + +`UdonHost.ExpectUdonException(Action act)` is static and a coroutine: yield it from a +`[UnityTest]`. It runs `act`, which makes an Udon behaviour throw, and expects the error Udon logs +as it halts the behaviour: + +```csharp +yield return UdonHost.ExpectUdonException(() => door.SendCustomEvent(nameof(Door.Unlock))); +``` + +UdonSharp logs a copy of that error on a later frame, which would fail the next test. +`ExpectUdonException` waits up to 10 frames for the copy and expects it too, once it came. +UdonSharp doesn't always log the copy, as +[What the kit works around](../explanations/what-the-kit-works-around#an-udon-exception-that-fails-the-next-test) +explains. + +When `act` doesn't make Udon throw, the error it expects never comes, and Unity Test Framework fails +the test. Like any coroutine, it does nothing until the test yields it. + +## Edge cases + +- Use it in Play Mode tests. A behaviour created with it doesn't need ClientSim, so start a + [`ClientSimSession`](./clientsim-session) only when the behaviour needs players. +- Udon runs the events a program delays with `SendCustomEventDelayedFrames` and + `SendCustomEventDelayedSeconds` on a later frame, once the delay passed, never during the call + that delays them. A test waits for them in a `[UnityTest]`, as in + [Run your behaviours as Udon](../how-to/running-behaviours-as-udon#wait-for-delayed-events). +- It runs each program as UdonSharp last compiled it, normally the compile for the Editor, which + keeps the code inside `#if UNITY_EDITOR`. To check the compile for upload, use + [`UdonSharpUploadCompile`](./udon-sharp-upload-compile). diff --git a/docs/udon-test-kit/reference/udon-sharp-upload-compile.md b/docs/udon-test-kit/reference/udon-sharp-upload-compile.md new file mode 100644 index 0000000..d58f00b --- /dev/null +++ b/docs/udon-test-kit/reference/udon-sharp-upload-compile.md @@ -0,0 +1,44 @@ +--- +id: udon-sharp-upload-compile +title: UdonSharpUploadCompile +sidebar_position: 10 +--- + +# UdonSharpUploadCompile + +`Tsvrc.UdonTestKit.UdonSharpUploadCompile` compiles every UdonSharp program in the project the way +the VRChat SDK has UdonSharp compile them before a world build, so a test can check that your +programs compile for upload as well as for the Editor. + +```csharp +[Test] +public void UploadCompile_EveryProgram_LogsNoErrors() +{ + Assert.That(UdonSharpUploadCompile.Run(), Is.Empty); +} +``` + +Use it in an Edit Mode test, as in +[Check that your world compiles for upload](../how-to/checking-your-world-compiles-for-upload). + +## Run + +`Run()` compiles every program for upload, for the active build target, and returns the errors that +compile logged, as an `IReadOnlyList`. Then it compiles every program for the Editor again, +so the Editor goes on running programs compiled for the Editor. + +The compile for upload reads only player assemblies and leaves out the code inside +`#if UNITY_EDITOR`, so programs that compile in the Editor can fail it, and the VRChat SDK can go on +with a build whose programs failed. +[What the kit works around](../explanations/what-the-kit-works-around#udon-code-that-compiles-for-the-editor-but-not-for-upload) +explains both. + +## Failure modes + +- The errors are also logged, and Unity Test Framework fails a test on an error log it didn't + expect, so a test whose compile logs errors fails even before its assertion runs. To look at the + list instead, set + [`LogAssert.ignoreFailingMessages`](https://docs.unity3d.com/Packages/com.unity.test-framework@1.1/api/UnityEngine.TestTools.LogAssert.html) + to `true` first. +- The list holds only the errors logged during the compile for upload. An error logged after `Run` + returns isn't in it. diff --git a/docs/udon-test-kit/reference/udon-test-base.md b/docs/udon-test-kit/reference/udon-test-base.md new file mode 100644 index 0000000..c784d0f --- /dev/null +++ b/docs/udon-test-kit/reference/udon-test-base.md @@ -0,0 +1,61 @@ +--- +id: udon-test-base +title: UdonTestBase +sidebar_position: 5 +--- + +# UdonTestBase + +`Tsvrc.UdonTestKit.UdonTestBase` is an abstract base class for Play Mode test fixtures that run +behaviours as Udon. It extends [`ClientSimTestBase`](./clientsim-test-base) and gives every test a +new [`UdonHost`](./udon-host) in its protected `Udon` property, which destroys what the test created +with it after the test. + +```csharp +public class DoorTests : UdonTestBase +{ + [Test] + public void Open_Closed_OpensTheDoor() + { + UdonBehaviour door = Udon.Create("Door"); + + door.SendCustomEvent(nameof(Door.Open)); + + Assert.That(door.GetProgramVariable(nameof(Door.IsOpen)), Is.EqualTo(true)); + } +} +``` + +Everything from `ClientSimTestBase` is there too. A test that needs players starts the session with +`yield return Session.Start()`, and the session ends after every test. + +## Constructors + +`UdonTestBase` has the two constructors of +[`ClientSimTestBase`](./clientsim-test-base#constructors) and passes their arguments on: + +- `UdonTestBase()` runs every test in the Unity Test Framework test scene, which the whole run + shares. +- `UdonTestBase(TestScene scene, TestSceneLifetime lifetime = TestSceneLifetime.PerTest)` runs every + test in `scene`, so the GameObjects `Udon` creates go into it. + +Pass the scene from the constructor of your fixture: + +```csharp +public class LobbyTests : UdonTestBase +{ + public LobbyTests() : base(TestScene.Empty("Lobby")) + { + } +} +``` + +## Lifecycle + +`UdonTestBase` adds two methods to those of `ClientSimTestBase`: + +- `[SetUp]` `CreateUdonHost` creates `Udon`. It runs before your own `[SetUp]`. +- `[TearDown]` `DisposeUdonHost` disposes it. It runs after your own `[TearDown]` and before + `ClientSimTestBase` ends the session, so your `[UnityTearDown]` runs once both are gone. + +[ClientSimTestBase](./clientsim-test-base#lifecycle) lists the rest of the order. diff --git a/i18n/es/code.json b/i18n/es/code.json index 6fe5273..20eca4d 100644 --- a/i18n/es/code.json +++ b/i18n/es/code.json @@ -21,7 +21,7 @@ "message": "Una forma estructurada de crear mundos de VRChat con UdonSharp: inicio consistente, dependencias ya conectadas y código generado en vez de conectarlo todo a mano." }, "homepage.projects.udonTestKit.description": { - "message": "Tests automatizados para mundos de VRChat: los tests de modo Play ejecutan tus behaviours de UdonSharp en una sesión real de ClientSim, con jugadores reales." + "message": "Tests de Unity Test Framework para mundos de VRChat, con tus behaviours de UdonSharp ejecutándose en una sesión real de ClientSim." }, "homepage.projects.github": { "message": "{name} en GitHub" diff --git a/i18n/es/docusaurus-plugin-content-docs/current/udon-test-kit/intro.md b/i18n/es/docusaurus-plugin-content-docs/current/udon-test-kit/intro.md index c58785c..ffc89d5 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/udon-test-kit/intro.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/udon-test-kit/intro.md @@ -32,14 +32,18 @@ de Unity lo explican con más detalle. - Darle un dueño a cualquier GameObject, para probar lo que ve un jugador que no es su dueño. - Conservar los datos guardados entre sesiones, como un jugador que sale y vuelve a entrar. - Registrar las llamadas que tu código hace por nombre, como con `SendCustomEvent`. +- Ejecutar tus behaviours como sus programas de Udon compilados, para ver qué hace Udon con tu + código. +- Comprobar que tu mundo compila para subirlo, y qué programas lleva su build. - Ejecutar cada test en una escena propia, vacía o la de tu mundo. - Crear desde un elemento de menú los assemblies de test que necesita tu mundo. -El kit solo se compila para los tests, así que nada de él llega a la build de tu mundo. +El kit se queda fuera de la build de tu mundo: todo menos un espía de Udon se compila solo para los +tests, y ese espía llega a un mundo solo cuando una escena tiene uno. -También incluye `Invoke-UnityTests.ps1`, un script de PowerShell independiente que ejecuta los -tests de un proyecto con un solo comando y muestra solo lo que falló. Funciona en cualquier -proyecto de Unity, con o sin el kit. +También incluye dos scripts independientes que ejecutan los tests de un proyecto con un solo +comando y muestran solo lo que falló: `Invoke-UnityTests.ps1` para PowerShell en Windows y +`run_unity_tests.sh` para Bash en Linux. Funcionan en cualquier proyecto de Unity, con o sin el kit. ## Empieza aquí @@ -51,6 +55,8 @@ proyecto de Unity, con o sin el kit. - [Ejecutar tests en una escena propia](./how-to/running-tests-in-their-own-scene) - [Probar qué pasa con un jugador que no es el dueño](./how-to/testing-a-player-who-isnt-the-owner) - [Comprobar que los datos guardados sobreviven al volver a entrar](./how-to/testing-saved-data) +- [Ejecutar tus behaviours como Udon](./how-to/running-behaviours-as-udon) +- [Comprobar que tu mundo compila para subirlo](./how-to/checking-your-world-compiles-for-upload) - [Ejecutar tests desde la línea de comandos](./how-to/running-tests-from-the-command-line) ## Referencia y contexto diff --git a/src/components/homepage/Projects.tsx b/src/components/homepage/Projects.tsx index 92b9743..358a4da 100644 --- a/src/components/homepage/Projects.tsx +++ b/src/components/homepage/Projects.tsx @@ -21,8 +21,8 @@ function useProjects(): Project[] { description: translate({ id: 'homepage.projects.udonTestKit.description', message: - 'Automated tests for VRChat worlds: Play Mode tests run your UdonSharp behaviours in a ' + - 'real ClientSim session, with real players.', + 'Unity Test Framework tests for VRChat worlds, with your UdonSharp behaviours running in ' + + 'a real ClientSim session.', }), docsHref: '/docs/udon-test-kit/intro', repo: 'tsvrc/udon-test-kit',