com.unity.test-framework.performance@2.7.0-preview

## [2.7.0] - 2021-02-19

Reduce metadata overhead when running locally by caching dependencies
Remove the need for link.xml
Restructured documentation
Fixed method measurement IterationsPerMeasurement

## [2.6.0] - 2021-01-12

Add build configuration support

Author: Unity Technologies

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [2.7.0] - 2021-02-19
+
+Reduce metadata overhead when running locally by caching dependencies
+Remove the need for link.xml
+Restructured documentation
+Fixed method measurement IterationsPerMeasurement
+
 ## [2.6.0] - 2021-01-12
 
 Add build configuration support

Documentation~/TableOfContents.md

@@ -0,0 +1,10 @@
+* [Performance Testing Extension overview](./index.md)
+* [Taking measurements](./taking-measurements.md)
+  * [Measure.Method](./measure-method.md)
+  * [Measure.Frames](./measure-frames.md)
+  * [Measure.Scope](./measure-scope.md)
+  * [Measure.ProfileMarkers](./measure-profile-markers.md)
+  * [Measure.Custom](./measure-custom.md)
+* [Writing tests](./writing-tests.md)
+* [Viewing results](./viewing-results.md)
+* [Reference](./reference.md)

Documentation~/index.md

@@ -0,0 +1,16 @@
+# Measure.Custom()
+
+When you want to record samples outside of frame time, method time, or profiler markers, use a custom measurement. It can be any value.
+
+#### Example: Use a custom measurement to capture total allocated memory
+
+``` csharp
+[Test, Performance]
+public void Test()
+{
+	SampleGroup samplegroup = new SampleGroup("TotalAllocatedMemory", SampleUnit.Megabyte, false);
+    var allocatedMemory = Profiler.GetTotalAllocatedMemoryLong() / 1048576f
+    Measure.Custom(samplegroup, allocatedMemory);
+
+}
+```

Documentation~/measure-custom.md

@@ -0,0 +1,69 @@
+# Measure.Frames()
+
+Records time per frame by default and provides additional properties/methods to control how the measurements are taken:
+* **WarmupCount(int n)** - number of times to execute before measurements are collected. If unspecified, a default warmup is executed for 80 ms or until at least 3 full frames have rendered, whichever is longest.
+* **MeasurementCount(int n)** - number of frames to capture measurements for. If this value is not specified, as many frames as possible are captured until approximately 500 ms has elapsed.
+* **DontRecordFrametime()** - disables frametime measurement.
+* **ProfilerMarkers(...)** - sample profile markers per frame. Does not work for deep profiling and `Profiler.BeginSample()`
+* **SampleGroup(string name)** - name of the measurement, defaults to "Time" if unspecified.
+* **Scope()** - measures frame times in a given coroutine scope.
+
+
+#### Example 1: Simple frame time measurement using default values of at least 7 frames and default WarmupCount (see description above).
+
+``` csharp
+[UnityTest, Performance]
+public IEnumerator Test()
+{
+    ...
+
+    yield return Measure.Frames().Run();
+}
+```
+
+#### Example 2: Sample profile markers per frame, disable frametime measurement
+
+If you'd like to sample profiler markers across multiple frames and don't need to record frametime, it is possible to disable the frame time measurement.
+
+``` csharp
+[UnityTest, Performance]
+public IEnumerator Test()
+{
+    ...
+
+    yield return Measure.Frames()
+        .ProfilerMarkers(...)
+        .DontRecordFrametime()
+        .Run();
+}
+```
+
+#### Example 3: Sample frame times in a scope
+
+``` csharp
+[UnityTest, Performance]
+public IEnumerator Test()
+{
+    using (Measure.Frames().Scope())
+    {
+        yield return ...;
+    }
+}
+```
+
+#### Example 4: Specify custom WarmupCount and MeasurementCount per frame
+
+If you want more control, you can specify how many frames you want to measure.
+
+``` csharp
+[UnityTest, Performance]
+public IEnumerator Test()
+{
+    ...
+
+    yield return Measure.Frames()
+        .WarmupCount(5)
+        .MeasurementCount(10)
+        .Run();
+}
+```

Documentation~/measure-frames.md

@@ -0,0 +1,38 @@
+# Measure.Method()
+
+Executes the provided method, sampling performance using the following additional properties/methods to control how the measurements are taken:
+* **WarmupCount(int n)** - number of times to execute before measurements are collected. If unspecified, a default warmup is executed for 100 ms or until at least 3 method executions have completed, whichever is longer.
+* **MeasurementCount(int n)** - number of measurements to capture, defaults to 9 if not specified.
+* **IterationsPerMeasurement(int n)** - number of method executions per measurement to use. If this value is not specified, the method is executed as many times as possible until approximately 100 ms has elapsed.
+* **SampleGroup(string name)** - name of the measurement, defaults to "Time" if unspecified.
+* **GC()** - if specified, measures the total number of Garbage Collection allocation calls.
+* **SetUp(Action action)** - is called every iteration before method execution. Setup time is not measured.
+* **CleanUp(Action action)** - is called every iteration after method execution. Cleanup time is not measured.
+
+
+#### Example 1: Simple method measurement using default values
+
+``` csharp
+[Test, Performance]
+public void Test()
+{
+    Measure.Method(() => { ... }).Run();
+}
+```
+
+#### Example 2: Customize Measure.Method properties
+
+```
+[Test, Performance]
+public void Test()
+{
+    Measure.Method(() => { ... })
+        .WarmupCount(10)
+        .MeasurementCount(10)
+        .IterationsPerMeasurement(5)
+        .GC()
+        .SetUp(()=> {/*setup code*/})
+        .CleanUp(()=> {/*cleanup code*/})
+        .Run();
+}
+```

Documentation~/measure-method.md

@@ -0,0 +1,24 @@
+# Measure.ProfilerMarkers()
+
+Used to record profiler markers. Profiler marker timings are recorded automatically and sampled within the scope of the `using` statement. Names should match profiler marker labels. Profiler markers are sampled once per frame. Sampling the same profiler marker per frame will result in the sum of all invocations. Note that deep and editor profiling is not available. Profiler markers created using `Profiler.BeginSample()` are not supported, switch to `ProfilerMarker` if possible. 
+
+#### Example: Measuring profiler markers in a scope
+
+``` csharp
+[Test, Performance]
+public void Test()
+{
+    string[] markers =
+    {
+        "Instantiate",
+        "Instantiate.Copy",
+        "Instantiate.Produce",
+        "Instantiate.Awake"
+    };
+
+    using(Measure.ProfilerMarkers(markers))
+    {
+        ...
+    }
+}
+```

Documentation~/measure-profile-markers.md

@@ -0,0 +1,16 @@
+# Measure.Scope(string name = "Time")
+
+Measures execution time for the scope as a single time, for both synchronous and coroutine methods. Passing the name argument overrides the name of the created SampleGroup.
+
+#### Example: Measuring a scope; execution time is measured for everything in the using statement
+
+``` csharp
+[Test, Performance]
+public void Test()
+{
+    using(Measure.Scope())
+    {
+        ...
+    }
+}
+```

Documentation~/measure-scope.md

@@ -0,0 +1,23 @@
+# Reference
+
+This section contains a reference for attributes and classes the Performance Testing Extension supports.
+
+## Test Attributes
+**[Performance]** - Use this with  `Test` and `UnityTest` attributes. It will initialize necessary test setup for performance tests.
+
+**[Test]** -  Non-yielding test. This type of test starts and ends within the same frame.
+
+**[UnityTest]** - Yielding test. This is a good choice if you want to sample measurements across multiple frames. For more on the difference between `[Test]` and `[UnityTest]`, see the Unity Test Framework [documentation](https://docs.unity3d.com/Packages/com.unity.test-framework@1.1/manual/reference-attribute-unitytest.html).
+
+**[Version(string version)]** - Performance tests should be versioned with every change. If not specified, the default used is 1. This is essential when comparing results as results will vary any time the test changes.
+
+
+## SampleGroup
+
+**class SampleGroup** - represents a group of samples with the same purpose that share a name, sample unit and whether an increase is better. 
+
+Optional parameters
+- **Name** : Name of the measurement. If unspecified, "Time" is used as the default name.
+- **Unit** : Unit of the measurement to report samples in. Possible values are:
+Nanosecond, Microsecond, Millisecond, Second, Byte, Kilobyte, Megabyte, Gigabyte
+- **IncreaseIsBetter** : If true, an increase in the measurement value is considered a performance improvement (progression). If false, an increase is treated as a performance regression. False by default. 

Documentation~/reference.md

@@ -0,0 +1,12 @@
+# Taking measurements
+
+The Performance Testing Extension provides several API methods for taking measurements in your performance test, depending on what you need to measure and how you want to do it. Include `using Unity.PerformanceTesting` at the top of your script to access the methods.
+
+The pages in this section detail the specifics of each measurement method with examples:
+
+* [Measure.Method](./measure-method.md)
+* [Measure.Frames](./measure-frames.md)
+* [Measure.Scope](./measure-scope.md)
+* [Measure.ProfilerMarkers](./measure-profile-markers.md)
+* [Measure.Custom](./measure-custom.md)
+