You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucenenet.apache.org by ni...@apache.org on 2021/12/22 16:24:18 UTC
[lucenenet] 02/04: Lucene.Net.TestFramework.Util.LuceneTestCase: Updated XML doc comments on how to configure the random seed and culture via file, attribute, or environment variable.
This is an automated email from the ASF dual-hosted git repository.
nightowl888 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/lucenenet.git
commit 5f1b653f552d38f5e082f4a3ff5104b67b3e5540
Author: Shad Storhaug <sh...@shadstorhaug.com>
AuthorDate: Wed Dec 22 21:54:33 2021 +0700
Lucene.Net.TestFramework.Util.LuceneTestCase: Updated XML doc comments on how to configure the random seed and culture via file, attribute, or environment variable.
---
.../Support/JavaCompatibility/LuceneTestCase.cs | 8 +-
.../Util/LuceneTestCase.cs | 111 ++++++++++++++-------
2 files changed, 79 insertions(+), 40 deletions(-)
diff --git a/src/Lucene.Net.TestFramework/Support/JavaCompatibility/LuceneTestCase.cs b/src/Lucene.Net.TestFramework/Support/JavaCompatibility/LuceneTestCase.cs
index 7b0da1a..e20635d 100644
--- a/src/Lucene.Net.TestFramework/Support/JavaCompatibility/LuceneTestCase.cs
+++ b/src/Lucene.Net.TestFramework/Support/JavaCompatibility/LuceneTestCase.cs
@@ -25,10 +25,10 @@ namespace Lucene.Net.Util
* limitations under the License.
*/
- /// <summary>
- /// LUCENENET specific extensions to <see cref="LuceneTestCase"/> to make it easier to port tests
- /// from Java with fewer changes.
- /// </summary>
+
+ // LUCENENET specific extensions to <see cref="LuceneTestCase"/> to make it easier to port tests
+ // from Java with fewer changes.
+ // LUCENENET NOTE: Don't add xml doc comments here, they must be applied only to the main LuceneTestCase class
[System.Diagnostics.CodeAnalysis.SuppressMessage("Style", "IDE1006:Naming Styles", Justification = "These methods are for making porting tests from Java simpler")]
public abstract partial class LuceneTestCase
{
diff --git a/src/Lucene.Net.TestFramework/Util/LuceneTestCase.cs b/src/Lucene.Net.TestFramework/Util/LuceneTestCase.cs
index 968c1d9..6b99270 100644
--- a/src/Lucene.Net.TestFramework/Util/LuceneTestCase.cs
+++ b/src/Lucene.Net.TestFramework/Util/LuceneTestCase.cs
@@ -70,7 +70,7 @@ namespace Lucene.Net.Util
/// static methods annotated with <see cref="OneTimeSetUp"/> and <see cref="OneTimeTearDown"/>. Any
/// code in these methods is executed within the test framework's control and
/// ensure proper setup has been made. <b>Try not to use static initializers
- /// (including complex final field initializers).</b> Static initializers are
+ /// (including complex readonly field initializers).</b> Static initializers are
/// executed before any setup rules are fired and may cause you (or somebody
/// else) headaches.
/// </para>
@@ -87,42 +87,81 @@ namespace Lucene.Net.Util
/// <para>
/// Any test method annotated with <see cref="Test"/> is considered a test case.
/// </para>
+ ///
+ /// <h3>Randomized execution and test facilities</h3>
+ ///
+ /// <para>
+ /// <see cref="LuceneTestCase"/> uses a custom <see cref="TestFixtureAttribute"/> to execute test cases.
+ /// The custom <see cref="TestFixtureAttribute"/> has built-in support for test randomization
+ /// including access to a repeatable <see cref="Random"/> instance. See
+ /// <see cref="Random"/> property. Any test using <see cref="Random"/> acquired from
+ /// <see cref="Random"/> should be fully reproducible (assuming no race conditions
+ /// between threads etc.). The initial seed for a test case is reported in the failure
+ /// test message.
+ /// </para>
+ /// <para>
+ /// The seed can be configured with a RunSettings file, a <c>lucene.testSettings.config</c> JSON file,
+ /// an environment variable, or using <see cref="RandomSeedAttribute"/> at the assembly level.
+ /// It is recommended to configure the culture also, since they are randomly picked from a list
+ /// of cultures installed on a given machine, so the culture will vary from one machine to the next.
+ /// </para>
+ ///
+ /// <h4><i>.runsettings</i> File Configuration Example</h4>
+ ///
+ /// <code>
+ /// <RunSettings>
+ /// <TestRunParameters>
+ /// <Parameter name="tests:seed" value="0x1ffa1d067056b0e6" />
+ /// <Parameter name="tests:culture" value="sw-TZ" />
+ /// </TestRunParameters>
+ /// </RunSettings>
+ /// </code>
+ /// <para>
+ /// See the <i>.runsettings</i> documentation at: <a href="https://docs.microsoft.com/en-us/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file">
+ /// https://docs.microsoft.com/en-us/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file</a>.
+ /// </para>
+ ///
+ /// <h4>Attribute Configuration Example</h4>
+ ///
+ /// <code>
+ /// [assembly: Lucene.Net.Util.RandomSeed("0x1ffa1d067056b0e6")]
+ /// [assembly: NUnit.Framework.SetCulture("sw-TZ")]
+ /// </code>
+ ///
+ /// <h4><i>lucene.testSettings.config</i> File Configuration Example</h4>
+ ///
+ /// <para>
+ /// Add a file named <i>lucene.testSettings.config</i> to the executable directory or
+ /// any directory between the executable and the root of the drive with the following contents.
+ /// </para>
+ ///
+ /// <code>
+ /// {
+ /// "tests": {
+ /// "seed": "0x1ffa1d067056b0e6",
+ /// "culture": "sw-TZ"
+ /// }
+ /// }
+ /// </code>
+ ///
+ /// <h4>Environment Variable Configuration Example</h4>
+ ///
+ /// <list type="table">
+ /// <listheader>
+ /// <term>Variable</term>
+ /// <term>Value</term>
+ /// </listheader>
+ /// <item>
+ /// <term>lucene:tests:seed</term>
+ /// <term>0x1ffa1d067056b0e6</term>
+ /// </item>
+ /// <item>
+ /// <term>lucene:tests:culture</term>
+ /// <term>sw-TZ</term>
+ /// </item>
+ /// </list>
+ ///
/// </summary>
-
- // LUCENENET TODO: Randomized seed
- ///// <h3>Randomized execution and test facilities</h3>
- /////
- ///// <para>
- ///// <see cref="LuceneTestCase"/> uses <see cref="RandomizedRunner"/> to execute test cases.
- ///// <see cref="RandomizedRunner"/> has built-in support for tests randomization
- ///// including access to a repeatable <see cref="Random"/> instance. See
- ///// <see cref="Random"/> property. Any test using <see cref="Random"/> acquired from
- ///// <see cref="Random"/> should be fully reproducible (assuming no race conditions
- ///// between threads etc.). The initial seed for a test case is reported in many
- ///// ways:
- ///// <list type="bullet">
- ///// <item>
- ///// <description>
- ///// as part of any exception thrown from its body (inserted as a dummy stack
- ///// trace entry),
- ///// </description>
- ///// </item>
- ///// <item>
- ///// <description>
- ///// as part of the main thread executing the test case (if your test hangs,
- ///// just dump the stack trace of all threads and you'll see the seed),
- ///// </description>
- ///// </item>
- ///// <item>
- ///// <description>
- ///// the master seed can also be accessed manually by getting the current
- ///// context (<see cref="RandomizedContext.Current"/>) and then calling
- ///// <see cref="RandomizedContext.RunnerSeed"/>.
- ///// </description>
- ///// </item>
- ///// </list>
- ///// </para>
- ///// </summary>
[TestFixture]
public abstract partial class LuceneTestCase //: Assert // Wait long for leaked threads to complete before failure. zk needs this. - See LUCENE-3995 for rationale.
{