org.apache.lucene.util

## Class LuceneTestCase

- java.lang.Object
- - org.junit.Assert
  - - org.apache.lucene.util.LuceneTestCase

- Direct Known Subclasses:
    BaseBitSetTestCase, BaseCompoundFormatTestCase, BaseDirectoryTestCase, BaseDocIdSetTestCase, BaseDocValuesFormatTestCase, BaseExplanationTestCase, BaseFieldInfoFormatTestCase, BaseGeoPointTestCase, BaseLockFactoryTestCase, BaseMergePolicyTestCase, BaseNormsFormatTestCase, BasePointsFormatTestCase, BasePostingsFormatTestCase, BaseRangeFieldQueryTestCase, BaseSegmentInfoFormatTestCase, BaseStoredFieldsFormatTestCase, BaseTermVectorsFormatTestCase, BaseTestCheckIndex, BaseTokenStreamTestCase, CollationTestBase, MockFileSystemTestCase, SearchEquivalenceTestBase, ShardSearchingTestBase, ThreadedIndexingAndSearchingTestCase

      @TestMethodProviders(value={LuceneJUnit3MethodProvider.class,com.carrotsearch.randomizedtesting.JUnit4MethodProvider.class})
       @Listeners(value={RunListenerPrintReproduceInfo.class,FailureMarker.class})
       @SeedDecorators(value=com.carrotsearch.randomizedtesting.MixWithSuiteName.class)
       @TestRuleLimitSysouts.Limit(bytes=8192)
      public abstract class LuceneTestCase
      extends Assert

  Base class for all Lucene unit tests, Junit3 or Junit4 variant.

  ### Class and instance setup.

  The preferred way to specify class (suite-level) setup/cleanup is to use static methods annotated with `BeforeClass` and `AfterClass`. Any code in these methods is executed within the test framework's control and ensure proper setup has been made. Try not to use static initializers (including complex final field initializers). Static initializers are executed before any setup rules are fired and may cause you (or somebody else) headaches.

  For instance-level setup, use `Before` and `After` annotated methods. If you override either `setUp()` or `tearDown()` in your subclass, make sure you call `super.setUp()` and `super.tearDown()`. This is detected and enforced.

  ### Specifying test cases

  Any test method with a `testXXX` prefix is considered a test case. Any test method annotated with `Test` is considered a test case.

  ### Randomized execution and test facilities

  `LuceneTestCase` uses `RandomizedRunner` to execute test cases. `RandomizedRunner` has built-in support for tests randomization including access to a repeatable `Random` instance. See `random()` method. Any test using `Random` acquired from `random()` should be fully reproducible (assuming no race conditions between threads etc.). The initial seed for a test case is reported in many ways:

  - as part of any exception thrown from its body (inserted as a dummy stack trace entry),
  - 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),
  - the master seed can also be accessed manually by getting the current context (`RandomizedContext.current()`) and then calling `RandomizedContext.getRunnerSeedAsString()`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `LuceneTestCase.AwaitsFix` Annotation for tests which exhibit a known issue and are temporarily disabled.
    `static interface` | `LuceneTestCase.BadApple` Annotation for tests that fail frequently and should be moved to a "vault" plan in Jenkins.
    `static interface` | `LuceneTestCase.Monster` Annotation for monster tests that require special setup (e.g.
    `static interface` | `LuceneTestCase.Nightly` Annotation for tests that should only be run during nightly builds.
    `static interface` | `LuceneTestCase.Slow` Annotation for tests that are slow.
    `static interface` | `LuceneTestCase.SuppressCodecs` Annotation for test classes that should avoid certain codec types (because they are expensive, for example).
    `static interface` | `LuceneTestCase.SuppressFileSystems` Annotation for test classes that should avoid mock filesystem types (because they test a bug that only happens on linux, for example).
    `static interface` | `LuceneTestCase.SuppressFsync` Annotation for test classes that should avoid always omit actual fsync calls from reaching the filesystem.
    `static interface` | `LuceneTestCase.SuppressReproduceLine` Suppress the default `reproduce with: ant test...` Your own listener can be added as needed for your build.
    `static interface` | `LuceneTestCase.SuppressSysoutChecks` Ignore `TestRuleLimitSysouts` for any suite which is known to print over the default limit of bytes to `System.out` or `System.err`.
    `static interface` | `LuceneTestCase.SuppressTempFileChecks` Marks any suites which are known not to close all the temporary files.
    `static interface` | `LuceneTestCase.ThrowingRunnable` A runnable that can throw any checked exception.
    `static interface` | `LuceneTestCase.Weekly` Annotation for tests that should only be run during weekly builds

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `assertsAreEnabled` True if assertions (-ea) are enabled (at least for this class).
    `static org.junit.rules.TestRule` | `classRules` This controls how suite-level rules are nested.
    `static String` | `DEFAULT_LINE_DOCS_FILE` TODO: javadoc?
    `static boolean` | `INFOSTREAM` Enables or disables dumping of `InfoStream` messages.
    `static String` | `JENKINS_LARGE_LINE_DOCS_FILE` TODO: javadoc?
    `static boolean` | `LEAVE_TEMPORARY` Leave temporary files on disk, even on successful runs.
    `static QueryCachingPolicy` | `MAYBE_CACHE_POLICY` A `QueryCachingPolicy` that randomly caches.
    `static int` | `RANDOM_MULTIPLIER` A random multiplier which you should use when writing random tests: multiply it by the number of iterations to scale your tests (for nightly builds).
    `org.junit.rules.TestRule` | `ruleChain` This controls how individual test rules are nested.
    `protected static TestRuleMarkFailure` | `suiteFailureMarker` Suite failure marker (any error in the test or suite scope).
    `static String` | `SYSPROP_AWAITSFIX`
    `static String` | `SYSPROP_BADAPPLES`
    `static String` | `SYSPROP_FAILFAST`
    `static String` | `SYSPROP_MAXFAILURES`
    `static String` | `SYSPROP_MONSTER`
    `static String` | `SYSPROP_NIGHTLY`
    `static String` | `SYSPROP_SLOW`
    `static String` | `SYSPROP_WEEKLY`
    `static boolean` | `TEST_ASSERTS_ENABLED`
    `static boolean` | `TEST_AWAITSFIX` Whether or not `LuceneTestCase.AwaitsFix` tests should run.
    `static String` | `TEST_CODEC` Gets the codec to run tests with.
    `static String` | `TEST_DIRECTORY` Gets the directory to run tests with
    `static String` | `TEST_DOCVALUESFORMAT` Gets the docValuesFormat to run tests with
    `static String` | `TEST_LINE_DOCS_FILE` the line file used by LineFileDocs
    `static boolean` | `TEST_NIGHTLY` Whether or not `LuceneTestCase.Nightly` tests should run.
    `static String` | `TEST_POSTINGSFORMAT` Gets the postingsFormat to run tests with.
    `static boolean` | `TEST_SLOW` Whether or not `LuceneTestCase.Slow` tests should run.
    `static MockDirectoryWrapper.Throttling` | `TEST_THROTTLING` Throttling, see `MockDirectoryWrapper.setThrottling(Throttling)`.
    `static boolean` | `TEST_WEEKLY` Whether or not `LuceneTestCase.Weekly` tests should run.
    `static boolean` | `VERBOSE` True if and only if tests are run in verbose mode.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LuceneTestCase()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Path` | `addVirusChecker(Path path)`
    `void` | `assertDeletedDocsEquals(String info, IndexReader leftReader, IndexReader rightReader)`
    `void` | `assertDocsAndPositionsEnumEquals(String info, PostingsEnum leftDocs, PostingsEnum rightDocs)` checks docs + freqs + positions + payloads, sequentially
    `void` | `assertDocsEnumEquals(String info, PostingsEnum leftDocs, PostingsEnum rightDocs, boolean hasFreqs)` checks docs + freqs, sequentially
    `void` | `assertDocsSkippingEquals(String info, IndexReader leftReader, int docFreq, PostingsEnum leftDocs, PostingsEnum rightDocs, boolean hasFreqs)` checks advancing docs
    `void` | `assertDocValuesEquals(String info, IndexReader leftReader, IndexReader rightReader)` checks that docvalues across all fields are equivalent
    `void` | `assertDocValuesEquals(String info, int num, NumericDocValues leftDocValues, NumericDocValues rightDocValues)`
    `void` | `assertFieldInfosEquals(String info, IndexReader leftReader, IndexReader rightReader)`
    `void` | `assertFieldsEquals(String info, IndexReader leftReader, Fields leftFields, Fields rightFields, boolean deep)` Fields api equivalency
    `void` | `assertFieldStatisticsEquals(String info, Fields leftFields, Fields rightFields)` checks that top-level statistics on Fields are the same
    `void` | `assertNormsEquals(String info, IndexReader leftReader, IndexReader rightReader)` checks that norms are the same across all fields
    `void` | `assertPointsEquals(String info, IndexReader leftReader, IndexReader rightReader)`
    `void` | `assertPositionsSkippingEquals(String info, IndexReader leftReader, int docFreq, PostingsEnum leftDocs, PostingsEnum rightDocs)` checks advancing docs + positions
    `void` | `assertReaderEquals(String info, IndexReader leftReader, IndexReader rightReader)`
    `void` | `assertReaderStatisticsEquals(String info, IndexReader leftReader, IndexReader rightReader)` checks that reader-level statistics are the same
    `void` | `assertStoredFieldEquals(String info, IndexableField leftField, IndexableField rightField)` checks that two stored fields are equivalent
    `void` | `assertStoredFieldsEquals(String info, IndexReader leftReader, IndexReader rightReader)` checks that stored fields of all documents are the same
    `void` | `assertTermsEnumEquals(String info, IndexReader leftReader, TermsEnum leftTermsEnum, TermsEnum rightTermsEnum, boolean deep)` checks the terms enum sequentially if deep is false, it does a 'shallow' test that doesnt go down to the docsenums
    `void` | `assertTermsEquals(String info, IndexReader leftReader, Terms leftTerms, Terms rightTerms, boolean deep)` Terms api equivalency
    `void` | `assertTermsStatisticsEquals(String info, Terms leftTerms, Terms rightTerms)` checks collection-level statistics on Terms
    `void` | `assertTermStatsEquals(String info, TermsEnum leftTermsEnum, TermsEnum rightTermsEnum)` checks term-level statistics
    `void` | `assertTermVectorsEquals(String info, IndexReader leftReader, IndexReader rightReader)` checks that term vectors across all fields are equivalent
    `static <T> Set<T>` | `asSet(T... args)` Return `args` as a `Set` instance.
    `static void` | `assumeFalse(String msg, boolean condition)`
    `static void` | `assumeNoException(String msg, Exception e)`
    `static void` | `assumeTrue(String msg, boolean condition)`
    `static void` | `assumeWorkingMMapOnWindows()` Assumes that the current MMapDirectory implementation supports unmapping, so the test will not fail on Windows.
    `static int` | `atLeast(int i)`
    `static int` | `atLeast(Random random, int i)` Returns a number of at least `i`
    `static <T extends Closeable> T` | `closeAfterSuite(T resource)` Registers a `Closeable` resource that should be closed after the suite completes.
    `<T extends Closeable> T` | `closeAfterTest(T resource)` Registers a `Closeable` resource that should be closed after the test completes.
    `static int` | `collate(Collator collator, String s1, String s2)` Compares two strings with a collator, also looking to see if the the strings are impacted by jdk bugs.
    `static Path` | `createTempDir()` Creates an empty, temporary folder (when the name of the folder is of no importance).
    `static Path` | `createTempDir(String prefix)` Creates an empty, temporary folder with the given name prefix under the test class's `getBaseTempDirForTestClass()`.
    `static Path` | `createTempFile()` Creates an empty temporary file.
    `static Path` | `createTempFile(String prefix, String suffix)` Creates an empty file with the given prefix and suffix under the test class's `getBaseTempDirForTestClass()`.
    `static void` | `dumpArray(String label, Object[] objs, PrintStream stream)` Convenience method for logging an array.
    `static void` | `dumpIterator(String label, Iterator<?> iter, PrintStream stream)` Convenience method for logging an iterator.
    `static <T extends Throwable> T` | `expectThrows(Class<T> expectedType, LuceneTestCase.ThrowingRunnable runnable)` Checks a specific exception class is thrown by the given runnable, and returns it.
    `static <TO extends Throwable,TW extends Throwable> TW` | `expectThrows(Class<TO> expectedOuterType, Class<TW> expectedWrappedType, LuceneTestCase.ThrowingRunnable runnable)` Checks that specific wrapped and outer exception classes are thrown by the given runnable, and returns the wrapped exception.
    `static Path` | `getBaseTempDirForTestClass()` Deprecated.
    `protected InputStream` | `getDataInputStream(String name)` Gets a resource from the test's classpath as `InputStream`.
    `protected Path` | `getDataPath(String name)` Gets a resource from the test's classpath as `Path`.
    `static LeafReader` | `getOnlyLeafReader(IndexReader reader)` Some tests expect the directory to contain a single segment, and want to do tests on that segment's reader.
    `static Class<?>` | `getTestClass()` Return the current class being tested.
    `String` | `getTestName()` Return the name of the currently executing test case.
    `static boolean` | `hasWorkingMMapOnWindows()` Returns true, if MMapDirectory supports unmapping on this platform (required for Windows), or if we are not on Windows.
    `protected boolean` | `isTestThread()` Returns true if and only if the calling thread is the primary thread executing the test case.
    `static Locale` | `localeForLanguageTag(String languageTag)` return a Locale object equivalent to its programmatic name
    `static void` | `maybeChangeLiveIndexWriterConfig(Random r, LiveIndexWriterConfig c)`
    `static IndexReader` | `maybeWrapReader(IndexReader r)` Sometimes wrap the IndexReader as slow, parallel or filter reader (or combinations of that)
    `static AlcoholicMergePolicy` | `newAlcoholicMergePolicy()`
    `static AlcoholicMergePolicy` | `newAlcoholicMergePolicy(Random r, TimeZone tz)`
    `static BaseDirectoryWrapper` | `newDirectory()` Returns a new Directory instance.
    `static BaseDirectoryWrapper` | `newDirectory(Directory d)` Returns a new Directory instance, with contents copied from the provided directory.
    `static BaseDirectoryWrapper` | `newDirectory(Random r)` Returns a new Directory instance, using the specified random.
    `static BaseDirectoryWrapper` | `newDirectory(Random r, Directory d)` Returns a new Directory instance, using the specified random with contents copied from the provided directory.
    `static BaseDirectoryWrapper` | `newDirectory(Random r, LockFactory lf)` Returns a new Directory instance, using the specified random.
    `static Field` | `newField(Random random, String name, Object value, FieldType type)`
    `static Field` | `newField(String name, String value, FieldType type)`
    `static BaseDirectoryWrapper` | `newFSDirectory(Path f)` Returns a new FSDirectory instance over the given file, which must be a folder.
    `static BaseDirectoryWrapper` | `newFSDirectory(Path f, LockFactory lf)` Returns a new FSDirectory instance over the given file, which must be a folder.
    `static IndexWriterConfig` | `newIndexWriterConfig()` create a new index writer config with random defaults
    `static IndexWriterConfig` | `newIndexWriterConfig(Analyzer a)` create a new index writer config with random defaults
    `static IndexWriterConfig` | `newIndexWriterConfig(Random r, Analyzer a)` create a new index writer config with random defaults using the specified random
    `static IOContext` | `newIOContext(Random random)` TODO: javadoc
    `static IOContext` | `newIOContext(Random random, IOContext oldContext)` TODO: javadoc
    `static LogMergePolicy` | `newLogMergePolicy()`
    `static MergePolicy` | `newLogMergePolicy(boolean useCFS)`
    `static MergePolicy` | `newLogMergePolicy(boolean useCFS, int mergeFactor)`
    `static MergePolicy` | `newLogMergePolicy(int mergeFactor)`
    `static LogMergePolicy` | `newLogMergePolicy(Random r)`
    `static BaseDirectoryWrapper` | `newMaybeVirusCheckingDirectory()` Like `newDirectory()` except randomly the `VirusCheckingFS` may be installed
    `static BaseDirectoryWrapper` | `newMaybeVirusCheckingFSDirectory(Path f)` Like `newFSDirectory(Path)`, but randomly insert `VirusCheckingFS`
    `static MergePolicy` | `newMergePolicy()`
    `static MergePolicy` | `newMergePolicy(Random r)`
    `static MockDirectoryWrapper` | `newMockDirectory()`
    `static MockDirectoryWrapper` | `newMockDirectory(Random r)`
    `static MockDirectoryWrapper` | `newMockDirectory(Random r, LockFactory lf)`
    `static MockDirectoryWrapper` | `newMockFSDirectory(Path f)`
    `static MockDirectoryWrapper` | `newMockFSDirectory(Path f, LockFactory lf)`
    `static IndexSearcher` | `newSearcher(IndexReader r)` Create a new searcher over the reader.
    `static IndexSearcher` | `newSearcher(IndexReader r, boolean maybeWrap)` Create a new searcher over the reader.
    `static IndexSearcher` | `newSearcher(IndexReader r, boolean maybeWrap, boolean wrapWithAssertions)` Create a new searcher over the reader.
    `static Field` | `newStringField(Random random, String name, BytesRef value, Field.Store stored)`
    `static Field` | `newStringField(Random random, String name, String value, Field.Store stored)`
    `static Field` | `newStringField(String name, BytesRef value, Field.Store stored)`
    `static Field` | `newStringField(String name, String value, Field.Store stored)`
    `static Field` | `newTextField(Random random, String name, String value, Field.Store stored)`
    `static Field` | `newTextField(String name, String value, Field.Store stored)`
    `static TieredMergePolicy` | `newTieredMergePolicy()`
    `static TieredMergePolicy` | `newTieredMergePolicy(Random r)`
    `static void` | `overrideDefaultQueryCache()`
    `void` | `overrideTestDefaultQueryCache()`
    `static Random` | `random()` Access to the current `RandomizedContext`'s Random instance.
    `static Locale` | `randomLocale(Random random)` Return a random Locale from the available locales on the system.
    `static TimeZone` | `randomTimeZone(Random random)` Return a random TimeZone from the available timezones on the system
    `static boolean` | `rarely()`
    `static boolean` | `rarely(Random random)` Returns true if something should happen rarely,
    `static TestRuleIgnoreAfterMaxFailures` | `replaceMaxFailureRule(TestRuleIgnoreAfterMaxFailures newValue)` Temporarily substitute the global `TestRuleIgnoreAfterMaxFailures`.
    `static void` | `resetDefaultQueryCache()`
    `static void` | `restoreCPUCoreCount()`
    `void` | `restoreIndexWriterMaxDocs()` Returns to the default `IndexWriter.MAX_DOCS` limit.
    `static void` | `restoreSpins()`
    `static <T> T` | `runWithRestrictedPermissions(PrivilegedExceptionAction<T> action, Permission... permissions)` Runs a code part with restricted permissions (be sure to add all required permissions, because it would start with empty permissions).
    `void` | `setIndexWriterMaxDocs(int limit)` Tells `IndexWriter` to enforce the specified limit as the maximum number of documents in one index; call `restoreIndexWriterMaxDocs()` once your test is done.
    `void` | `setUp()` For subclasses to override.
    `static void` | `setupCPUCoreCount()`
    `static void` | `setupSpins()`
    `static boolean` | `slowFileExists(Directory dir, String fileName)` Returns true if the file exists (can be opened), false if it cannot be opened, and (unlike Java's File.exists) throws IOException if there's some unexpected error.
    `void` | `tearDown()` For subclasses to override.
    `static boolean` | `usually()`
    `static boolean` | `usually(Random random)`
    `static IndexReader` | `wrapReader(IndexReader r)`

    - ### Methods inherited from class org.junit.Assert

      `assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertArrayEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertThat, assertThat, assertTrue, assertTrue, fail, fail`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SYSPROP_NIGHTLY

          public static final String SYSPROP_NIGHTLY

      See Also:
        Constant Field Values

    - #### SYSPROP_WEEKLY

          public static final String SYSPROP_WEEKLY

      See Also:
        Constant Field Values

    - #### SYSPROP_MONSTER

          public static final String SYSPROP_MONSTER

      See Also:
        Constant Field Values

    - #### SYSPROP_AWAITSFIX

          public static final String SYSPROP_AWAITSFIX

      See Also:
        Constant Field Values

    - #### SYSPROP_SLOW

          public static final String SYSPROP_SLOW

      See Also:
        Constant Field Values

    - #### SYSPROP_BADAPPLES

          public static final String SYSPROP_BADAPPLES

      See Also:
        Constant Field Values

    - #### SYSPROP_MAXFAILURES

          public static final String SYSPROP_MAXFAILURES

      See Also:
        `ignoreAfterMaxFailures`, Constant Field Values

    - #### SYSPROP_FAILFAST

          public static final String SYSPROP_FAILFAST

      See Also:
        `ignoreAfterMaxFailures`, Constant Field Values

    - #### VERBOSE

          public static final boolean VERBOSE

      True if and only if tests are run in verbose mode. If this flag is false tests are not expected to print any messages. Enforced with `TestRuleLimitSysouts`.

    - #### INFOSTREAM

          public static final boolean INFOSTREAM

      Enables or disables dumping of `InfoStream` messages.

    - #### RANDOM_MULTIPLIER

          public static final int RANDOM_MULTIPLIER

      A random multiplier which you should use when writing random tests: multiply it by the number of iterations to scale your tests (for nightly builds).

    - #### TEST_ASSERTS_ENABLED

          public static final boolean TEST_ASSERTS_ENABLED

    - #### DEFAULT_LINE_DOCS_FILE

          public static final String DEFAULT_LINE_DOCS_FILE

      TODO: javadoc?
      See Also:
        Constant Field Values

    - #### JENKINS_LARGE_LINE_DOCS_FILE

          public static final String JENKINS_LARGE_LINE_DOCS_FILE

      TODO: javadoc?
      See Also:
        Constant Field Values

    - #### TEST_CODEC

          public static final String TEST_CODEC

      Gets the codec to run tests with.

    - #### TEST_POSTINGSFORMAT

          public static final String TEST_POSTINGSFORMAT

      Gets the postingsFormat to run tests with.

    - #### TEST_DOCVALUESFORMAT

          public static final String TEST_DOCVALUESFORMAT

      Gets the docValuesFormat to run tests with

    - #### TEST_DIRECTORY

          public static final String TEST_DIRECTORY

      Gets the directory to run tests with

    - #### TEST_LINE_DOCS_FILE

          public static final String TEST_LINE_DOCS_FILE

      the line file used by LineFileDocs

    - #### TEST_NIGHTLY

          public static final boolean TEST_NIGHTLY

      Whether or not `LuceneTestCase.Nightly` tests should run.

    - #### TEST_WEEKLY

          public static final boolean TEST_WEEKLY

      Whether or not `LuceneTestCase.Weekly` tests should run.

    - #### TEST_AWAITSFIX

          public static final boolean TEST_AWAITSFIX

      Whether or not `LuceneTestCase.AwaitsFix` tests should run.

    - #### TEST_SLOW

          public static final boolean TEST_SLOW

      Whether or not `LuceneTestCase.Slow` tests should run.

    - #### TEST_THROTTLING

          public static final MockDirectoryWrapper.Throttling TEST_THROTTLING

      Throttling, see `MockDirectoryWrapper.setThrottling(Throttling)`.

    - #### LEAVE_TEMPORARY

          public static final boolean LEAVE_TEMPORARY

      Leave temporary files on disk, even on successful runs.

    - #### MAYBE_CACHE_POLICY

          public static final QueryCachingPolicy MAYBE_CACHE_POLICY

      A `QueryCachingPolicy` that randomly caches.

    - #### suiteFailureMarker

          protected static TestRuleMarkFailure suiteFailureMarker

      Suite failure marker (any error in the test or suite scope).

    - #### classRules

          public static org.junit.rules.TestRule classRules

      This controls how suite-level rules are nested. It is important that _all_ rules declared in `LuceneTestCase` are executed in proper order if they depend on each other.

    - #### ruleChain

          public final org.junit.rules.TestRule ruleChain

      This controls how individual test rules are nested. It is important that _all_ rules declared in `LuceneTestCase` are executed in proper order if they depend on each other.

    - #### assertsAreEnabled

          public static final boolean assertsAreEnabled

      True if assertions (-ea) are enabled (at least for this class).

  - ### Constructor Detail

    - #### LuceneTestCase

          public LuceneTestCase()

  - ### Method Detail

    - #### hasWorkingMMapOnWindows

          public static boolean hasWorkingMMapOnWindows()

      Returns true, if MMapDirectory supports unmapping on this platform (required for Windows), or if we are not on Windows.

    - #### assumeWorkingMMapOnWindows

          public static void assumeWorkingMMapOnWindows()

      Assumes that the current MMapDirectory implementation supports unmapping, so the test will not fail on Windows.
      See Also:
        `hasWorkingMMapOnWindows()`

    - #### replaceMaxFailureRule

          public static TestRuleIgnoreAfterMaxFailures replaceMaxFailureRule(TestRuleIgnoreAfterMaxFailures newValue)

      Temporarily substitute the global `TestRuleIgnoreAfterMaxFailures`. See `ignoreAfterMaxFailuresDelegate` for some explanation why this method is needed.

    - #### setUp

          public void setUp()
                     throws Exception

      For subclasses to override. Overrides must call `super.setUp()`.
      Throws:
        `Exception`

    - #### tearDown

          public void tearDown()
                        throws Exception

      For subclasses to override. Overrides must call `super.tearDown()`.
      Throws:
        `Exception`

    - #### setIndexWriterMaxDocs

          public void setIndexWriterMaxDocs(int limit)

      Tells `IndexWriter` to enforce the specified limit as the maximum number of documents in one index; call `restoreIndexWriterMaxDocs()` once your test is done.

    - #### restoreIndexWriterMaxDocs

          public void restoreIndexWriterMaxDocs()

      Returns to the default `IndexWriter.MAX_DOCS` limit.

    - #### random

          public static Random random()

      Access to the current `RandomizedContext`'s Random instance. It is safe to use this method from multiple threads, etc., but it should be called while within a runner's scope (so no static initializers). The returned `Random` instance will be different when this method is called inside a `BeforeClass` hook (static suite scope) and within `Before`/ `After` hooks or test methods.

      The returned instance must not be shared with other threads or cross a single scope's boundary. For example, a `Random` acquired within a test method shouldn't be reused for another test case.

      There is an overhead connected with getting the `Random` for a particular context and thread. It is better to cache the `Random` locally if tight loops with multiple invocations are present or create a derivative local `Random` for millions of calls like this:

           Random random = new Random(random().nextLong());
           // tight loop with many invocations.

    - #### closeAfterTest

          public <T extends Closeable> T closeAfterTest(T resource)

      Registers a `Closeable` resource that should be closed after the test completes.
      Returns:
        `resource` (for call chaining).

    - #### closeAfterSuite

          public static <T extends Closeable> T closeAfterSuite(T resource)

      Registers a `Closeable` resource that should be closed after the suite completes.
      Returns:
        `resource` (for call chaining).

    - #### getTestClass

          public static Class<?> getTestClass()

      Return the current class being tested.

    - #### getTestName

          public String getTestName()

      Return the name of the currently executing test case.

    - #### getOnlyLeafReader

          public static LeafReader getOnlyLeafReader(IndexReader reader)

      Some tests expect the directory to contain a single segment, and want to do tests on that segment's reader. This is an utility method to help them.

    - #### isTestThread

          protected boolean isTestThread()

      Returns true if and only if the calling thread is the primary thread executing the test case.

    - #### atLeast

          public static int atLeast(Random random,
                                    int i)

      Returns a number of at least `i`

      The actual number returned will be influenced by whether `TEST_NIGHTLY` is active and `RANDOM_MULTIPLIER`, but also with some random fudge.

    - #### atLeast

          public static int atLeast(int i)

    - #### rarely

          public static boolean rarely(Random random)

      Returns true if something should happen rarely,

      The actual number returned will be influenced by whether `TEST_NIGHTLY` is active and `RANDOM_MULTIPLIER`.

    - #### rarely

          public static boolean rarely()

    - #### usually

          public static boolean usually(Random random)

    - #### usually

          public static boolean usually()

    - #### assumeTrue

          public static void assumeTrue(String msg,
                                        boolean condition)

    - #### assumeFalse

          public static void assumeFalse(String msg,
                                         boolean condition)

    - #### assumeNoException

          public static void assumeNoException(String msg,
                                               Exception e)

    - #### asSet

          @SafeVarargs
          public static <T> Set<T> asSet(T... args)

      Return `args` as a `Set` instance. The order of elements is not preserved in iterators.

    - #### dumpIterator

          public static void dumpIterator(String label,
                                          Iterator<?> iter,
                                          PrintStream stream)

      Convenience method for logging an iterator.
      Parameters:
        `label` - String logged before/after the items in the iterator
        `iter` - Each next() is toString()ed and logged on it's own line. If iter is null this is logged differnetly then an empty iterator.
        `stream` - Stream to log messages to.

    - #### dumpArray

          public static void dumpArray(String label,
                                       Object[] objs,
                                       PrintStream stream)

      Convenience method for logging an array. Wraps the array in an iterator and delegates
      See Also:
        `dumpIterator(String,Iterator,PrintStream)`

    - #### newIndexWriterConfig

          public static IndexWriterConfig newIndexWriterConfig()

      create a new index writer config with random defaults

    - #### newIndexWriterConfig

          public static IndexWriterConfig newIndexWriterConfig(Analyzer a)

      create a new index writer config with random defaults

    - #### newIndexWriterConfig

          public static IndexWriterConfig newIndexWriterConfig(Random r,
                                                               Analyzer a)

      create a new index writer config with random defaults using the specified random

    - #### newMergePolicy

          public static MergePolicy newMergePolicy(Random r)

    - #### newMergePolicy

          public static MergePolicy newMergePolicy()

    - #### newLogMergePolicy

          public static LogMergePolicy newLogMergePolicy()

    - #### newTieredMergePolicy

          public static TieredMergePolicy newTieredMergePolicy()

    - #### newAlcoholicMergePolicy

          public static AlcoholicMergePolicy newAlcoholicMergePolicy()

    - #### newAlcoholicMergePolicy

          public static AlcoholicMergePolicy newAlcoholicMergePolicy(Random r,
                                                                     TimeZone tz)

    - #### newLogMergePolicy

          public static LogMergePolicy newLogMergePolicy(Random r)

    - #### newTieredMergePolicy

          public static TieredMergePolicy newTieredMergePolicy(Random r)

    - #### newLogMergePolicy

          public static MergePolicy newLogMergePolicy(boolean useCFS)

    - #### newLogMergePolicy

          public static MergePolicy newLogMergePolicy(boolean useCFS,
                                                      int mergeFactor)

    - #### newLogMergePolicy

          public static MergePolicy newLogMergePolicy(int mergeFactor)

    - #### maybeChangeLiveIndexWriterConfig

          public static void maybeChangeLiveIndexWriterConfig(Random r,
                                                              LiveIndexWriterConfig c)

    - #### newDirectory

          public static BaseDirectoryWrapper newDirectory()

      Returns a new Directory instance. Use this when the test does not care about the specific Directory implementation (most tests).

      The Directory is wrapped with `BaseDirectoryWrapper`. this means usually it will be picky, such as ensuring that you properly close it and all open files in your test. It will emulate some features of Windows, such as not allowing open files to be overwritten.

    - #### newMaybeVirusCheckingDirectory

          public static BaseDirectoryWrapper newMaybeVirusCheckingDirectory()

      Like `newDirectory()` except randomly the `VirusCheckingFS` may be installed

    - #### newDirectory

          public static BaseDirectoryWrapper newDirectory(Random r)

      Returns a new Directory instance, using the specified random. See `newDirectory()` for more information.

    - #### newDirectory

          public static BaseDirectoryWrapper newDirectory(Random r,
                                                          LockFactory lf)

      Returns a new Directory instance, using the specified random. See `newDirectory()` for more information.

    - #### newMockDirectory

          public static MockDirectoryWrapper newMockDirectory()

    - #### newMockDirectory

          public static MockDirectoryWrapper newMockDirectory(Random r)

    - #### newMockDirectory

          public static MockDirectoryWrapper newMockDirectory(Random r,
                                                              LockFactory lf)

    - #### newMockFSDirectory

          public static MockDirectoryWrapper newMockFSDirectory(Path f)

    - #### newMockFSDirectory

          public static MockDirectoryWrapper newMockFSDirectory(Path f,
                                                                LockFactory lf)

    - #### addVirusChecker

          public static Path addVirusChecker(Path path)

    - #### newDirectory

          public static BaseDirectoryWrapper newDirectory(Directory d)
                                                   throws IOException

      Returns a new Directory instance, with contents copied from the provided directory. See `newDirectory()` for more information.
      Throws:
        `IOException`

    - #### newFSDirectory

          public static BaseDirectoryWrapper newFSDirectory(Path f)

      Returns a new FSDirectory instance over the given file, which must be a folder.

    - #### newMaybeVirusCheckingFSDirectory

          public static BaseDirectoryWrapper newMaybeVirusCheckingFSDirectory(Path f)

      Like `newFSDirectory(Path)`, but randomly insert `VirusCheckingFS`

    - #### newFSDirectory

          public static BaseDirectoryWrapper newFSDirectory(Path f,
                                                            LockFactory lf)

      Returns a new FSDirectory instance over the given file, which must be a folder.

    - #### newDirectory

          public static BaseDirectoryWrapper newDirectory(Random r,
                                                          Directory d)
                                                   throws IOException

      Returns a new Directory instance, using the specified random with contents copied from the provided directory. See `newDirectory()` for more information.
      Throws:
        `IOException`

    - #### newStringField

          public static Field newStringField(String name,
                                             String value,
                                             Field.Store stored)

    - #### newStringField

          public static Field newStringField(String name,
                                             BytesRef value,
                                             Field.Store stored)

    - #### newTextField

          public static Field newTextField(String name,
                                           String value,
                                           Field.Store stored)

    - #### newStringField

          public static Field newStringField(Random random,
                                             String name,
                                             String value,
                                             Field.Store stored)

    - #### newStringField

          public static Field newStringField(Random random,
                                             String name,
                                             BytesRef value,
                                             Field.Store stored)

    - #### newTextField

          public static Field newTextField(Random random,
                                           String name,
                                           String value,
                                           Field.Store stored)

    - #### newField

          public static Field newField(String name,
                                       String value,
                                       FieldType type)

    - #### newField

          public static Field newField(Random random,
                                       String name,
                                       Object value,
                                       FieldType type)

    - #### randomLocale

          public static Locale randomLocale(Random random)

      Return a random Locale from the available locales on the system.
      See Also:
        LUCENE-4020

    - #### randomTimeZone

          public static TimeZone randomTimeZone(Random random)

      Return a random TimeZone from the available timezones on the system
      See Also:
        LUCENE-4020

    - #### localeForLanguageTag

          public static Locale localeForLanguageTag(String languageTag)

      return a Locale object equivalent to its programmatic name

    - #### wrapReader

          public static IndexReader wrapReader(IndexReader r)
                                        throws IOException

      Throws:
        `IOException`

    - #### maybeWrapReader

          public static IndexReader maybeWrapReader(IndexReader r)
                                             throws IOException

      Sometimes wrap the IndexReader as slow, parallel or filter reader (or combinations of that)
      Throws:
        `IOException`

    - #### newIOContext

          public static IOContext newIOContext(Random random)

      TODO: javadoc

    - #### newIOContext

          public static IOContext newIOContext(Random random,
                                               IOContext oldContext)

      TODO: javadoc

    - #### overrideTestDefaultQueryCache

          public void overrideTestDefaultQueryCache()

    - #### overrideDefaultQueryCache

          public static void overrideDefaultQueryCache()

    - #### resetDefaultQueryCache

          public static void resetDefaultQueryCache()

    - #### setupCPUCoreCount

          public static void setupCPUCoreCount()

    - #### restoreCPUCoreCount

          public static void restoreCPUCoreCount()

    - #### setupSpins

          public static void setupSpins()

    - #### restoreSpins

          public static void restoreSpins()

    - #### newSearcher

          public static IndexSearcher newSearcher(IndexReader r)

      Create a new searcher over the reader. This searcher might randomly use threads.

    - #### newSearcher

          public static IndexSearcher newSearcher(IndexReader r,
                                                  boolean maybeWrap)

      Create a new searcher over the reader. This searcher might randomly use threads.

    - #### newSearcher

          public static IndexSearcher newSearcher(IndexReader r,
                                                  boolean maybeWrap,
                                                  boolean wrapWithAssertions)

      Create a new searcher over the reader. This searcher might randomly use threads. if `maybeWrap` is true, this searcher might wrap the reader with one that returns null for getSequentialSubReaders. If `wrapWithAssertions` is true, this searcher might be an `AssertingIndexSearcher` instance.

    - #### getDataPath

          protected Path getDataPath(String name)
                              throws IOException

      Gets a resource from the test's classpath as `Path`. This method should only be used, if a real file is needed. To get a stream, code should prefer `getDataInputStream(String)`.
      Throws:
        `IOException`

    - #### getDataInputStream

          protected InputStream getDataInputStream(String name)
                                            throws IOException

      Gets a resource from the test's classpath as `InputStream`.
      Throws:
        `IOException`

    - #### assertReaderEquals

          public void assertReaderEquals(String info,
                                         IndexReader leftReader,
                                         IndexReader rightReader)
                                  throws IOException

      Throws:
        `IOException`

    - #### assertReaderStatisticsEquals

          public void assertReaderStatisticsEquals(String info,
                                                   IndexReader leftReader,
                                                   IndexReader rightReader)
                                            throws IOException

      checks that reader-level statistics are the same
      Throws:
        `IOException`

    - #### assertFieldsEquals

          public void assertFieldsEquals(String info,
                                         IndexReader leftReader,
                                         Fields leftFields,
                                         Fields rightFields,
                                         boolean deep)
                                  throws IOException

      Fields api equivalency
      Throws:
        `IOException`

    - #### assertFieldStatisticsEquals

          public void assertFieldStatisticsEquals(String info,
                                                  Fields leftFields,
                                                  Fields rightFields)
                                           throws IOException

      checks that top-level statistics on Fields are the same
      Throws:
        `IOException`

    - #### assertTermsEquals

          public void assertTermsEquals(String info,
                                        IndexReader leftReader,
                                        Terms leftTerms,
                                        Terms rightTerms,
                                        boolean deep)
                                 throws IOException

      Terms api equivalency
      Throws:
        `IOException`

    - #### assertTermsStatisticsEquals

          public void assertTermsStatisticsEquals(String info,
                                                  Terms leftTerms,
                                                  Terms rightTerms)
                                           throws IOException

      checks collection-level statistics on Terms
      Throws:
        `IOException`

    - #### assertTermsEnumEquals

          public void assertTermsEnumEquals(String info,
                                            IndexReader leftReader,
                                            TermsEnum leftTermsEnum,
                                            TermsEnum rightTermsEnum,
                                            boolean deep)
                                     throws IOException

      checks the terms enum sequentially if deep is false, it does a 'shallow' test that doesnt go down to the docsenums
      Throws:
        `IOException`

    - #### assertDocsAndPositionsEnumEquals

          public void assertDocsAndPositionsEnumEquals(String info,
                                                       PostingsEnum leftDocs,
                                                       PostingsEnum rightDocs)
                                                throws IOException

      checks docs + freqs + positions + payloads, sequentially
      Throws:
        `IOException`

    - #### assertDocsEnumEquals

          public void assertDocsEnumEquals(String info,
                                           PostingsEnum leftDocs,
                                           PostingsEnum rightDocs,
                                           boolean hasFreqs)
                                    throws IOException

      checks docs + freqs, sequentially
      Throws:
        `IOException`

    - #### assertDocsSkippingEquals

          public void assertDocsSkippingEquals(String info,
                                               IndexReader leftReader,
                                               int docFreq,
                                               PostingsEnum leftDocs,
                                               PostingsEnum rightDocs,
                                               boolean hasFreqs)
                                        throws IOException

      checks advancing docs
      Throws:
        `IOException`

    - #### assertPositionsSkippingEquals

          public void assertPositionsSkippingEquals(String info,
                                                    IndexReader leftReader,
                                                    int docFreq,
                                                    PostingsEnum leftDocs,
                                                    PostingsEnum rightDocs)
                                             throws IOException

      checks advancing docs + positions
      Throws:
        `IOException`

    - #### assertTermStatsEquals

          public void assertTermStatsEquals(String info,
                                            TermsEnum leftTermsEnum,
                                            TermsEnum rightTermsEnum)
                                     throws IOException

      checks term-level statistics
      Throws:
        `IOException`

    - #### assertNormsEquals

          public void assertNormsEquals(String info,
                                        IndexReader leftReader,
                                        IndexReader rightReader)
                                 throws IOException

      checks that norms are the same across all fields
      Throws:
        `IOException`

    - #### assertStoredFieldsEquals

          public void assertStoredFieldsEquals(String info,
                                               IndexReader leftReader,
                                               IndexReader rightReader)
                                        throws IOException

      checks that stored fields of all documents are the same
      Throws:
        `IOException`

    - #### assertStoredFieldEquals

          public void assertStoredFieldEquals(String info,
                                              IndexableField leftField,
                                              IndexableField rightField)

      checks that two stored fields are equivalent

    - #### assertTermVectorsEquals

          public void assertTermVectorsEquals(String info,
                                              IndexReader leftReader,
                                              IndexReader rightReader)
                                       throws IOException

      checks that term vectors across all fields are equivalent
      Throws:
        `IOException`

    - #### assertDocValuesEquals

          public void assertDocValuesEquals(String info,
                                            IndexReader leftReader,
                                            IndexReader rightReader)
                                     throws IOException

      checks that docvalues across all fields are equivalent
      Throws:
        `IOException`

    - #### assertDocValuesEquals

          public void assertDocValuesEquals(String info,
                                            int num,
                                            NumericDocValues leftDocValues,
                                            NumericDocValues rightDocValues)
                                     throws IOException

      Throws:
        `IOException`

    - #### assertDeletedDocsEquals

          public void assertDeletedDocsEquals(String info,
                                              IndexReader leftReader,
                                              IndexReader rightReader)
                                       throws IOException

      Throws:
        `IOException`

    - #### assertFieldInfosEquals

          public void assertFieldInfosEquals(String info,
                                             IndexReader leftReader,
                                             IndexReader rightReader)
                                      throws IOException

      Throws:
        `IOException`

    - #### assertPointsEquals

          public void assertPointsEquals(String info,
                                         IndexReader leftReader,
                                         IndexReader rightReader)
                                  throws IOException

      Throws:
        `IOException`

    - #### expectThrows

          public static <T extends Throwable> T expectThrows(Class<T> expectedType,
                                                             LuceneTestCase.ThrowingRunnable runnable)

      Checks a specific exception class is thrown by the given runnable, and returns it.

    - #### expectThrows

          public static <TO extends Throwable,TW extends Throwable> TW expectThrows(Class<TO> expectedOuterType,
                                                                                    Class<TW> expectedWrappedType,
                                                                                    LuceneTestCase.ThrowingRunnable runnable)

      Checks that specific wrapped and outer exception classes are thrown by the given runnable, and returns the wrapped exception.

    - #### slowFileExists

          public static boolean slowFileExists(Directory dir,
                                               String fileName)
                                        throws IOException

      Returns true if the file exists (can be opened), false if it cannot be opened, and (unlike Java's File.exists) throws IOException if there's some unexpected error.
      Throws:
        `IOException`

    - #### getBaseTempDirForTestClass

          @Deprecated
          public static Path getBaseTempDirForTestClass()

      Deprecated.
      This method is deprecated for a reason. Do not use it. Call `createTempDir()` or `createTempDir(String)` or `createTempFile(String, String)`.

    - #### createTempDir

          public static Path createTempDir()

      Creates an empty, temporary folder (when the name of the folder is of no importance).
      See Also:
        `createTempDir(String)`

    - #### createTempDir

          public static Path createTempDir(String prefix)

      Creates an empty, temporary folder with the given name prefix under the test class's `getBaseTempDirForTestClass()`.

      The folder will be automatically removed after the test class completes successfully. The test should close any file handles that would prevent the folder from being removed.

    - #### createTempFile

          public static Path createTempFile(String prefix,
                                            String suffix)
                                     throws IOException

      Creates an empty file with the given prefix and suffix under the test class's `getBaseTempDirForTestClass()`.

      The file will be automatically removed after the test class completes successfully. The test should close any file handles that would prevent the folder from being removed.

      Throws:
        `IOException`

    - #### createTempFile

          public static Path createTempFile()
                                     throws IOException

      Creates an empty temporary file.
      Throws:
        `IOException`
      See Also:
        `createTempFile(String, String)`

    - #### runWithRestrictedPermissions

          public static <T> T runWithRestrictedPermissions(PrivilegedExceptionAction<T> action,
                                                           Permission... permissions)
                                                    throws Exception

      Runs a code part with restricted permissions (be sure to add all required permissions, because it would start with empty permissions). You cannot grant more permissions than our policy file allows, but you may restrict writing to several dirs...

      Note: This assumes a `SecurityManager` enabled, otherwise it stops test execution. If enabled, it needs the following `SecurityPermission`: `"createAccessControlContext"`

      Throws:
        `Exception`

    - #### collate

          public static int collate(Collator collator,
                                    String s1,
                                    String s2)

      Compares two strings with a collator, also looking to see if the the strings are impacted by jdk bugs. may not avoid all jdk bugs in tests. see https://bugs.openjdk.java.net/browse/JDK-8071862

Copyright © 2000-2018 Apache Software Foundation. All Rights Reserved.