Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions docs/udon-test-kit/add-to-your-project.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down
41 changes: 38 additions & 3 deletions docs/udon-test-kit/explanations/what-the-kit-works-around.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 2 additions & 0 deletions docs/udon-test-kit/first-test.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
2 changes: 1 addition & 1 deletion docs/udon-test-kit/how-to/adding-your-worlds-own-setup.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
12 changes: 8 additions & 4 deletions docs/udon-test-kit/how-to/checking-calls-made-by-name.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
73 changes: 73 additions & 0 deletions docs/udon-test-kit/how-to/checking-calls-made-from-udon.md
Original file line number Diff line number Diff line change
@@ -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<UdonCallLog>("Log");
UdonBehaviour listener = Udon.Create<RoundListenerDouble>("Listener");
listener.SetProgramVariable(nameof(RoundListenerDouble.Log), log);
UdonBehaviour referee = Udon.Create<RoundReferee>("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.
61 changes: 61 additions & 0 deletions docs/udon-test-kit/how-to/checking-what-a-world-build-holds.md
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Loading
Loading