org.apache.lucene.util

## Class LuceneTestCase

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

Direct Known Subclasses:
  BaseBitSetTestCase, BaseDirectoryTestCase, BaseDocIdSetTestCase, BaseExplanationTestCase, BaseGeoPointTestCase, BaseIndexFileFormatTestCase, BaseLiveDocsFormatTestCase, BaseLockFactoryTestCase, BaseMergePolicyTestCase, BaseRangeFieldQueryTestCase, BaseSimilarityTestCase, BaseTestCheckIndex, BaseTokenStreamTestCase, BaseXYPointTestCase, 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=8192L,
                                hardLimit=2147483648L)
    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
`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 are not executed in Jenkins builds to not spam mailing lists with false reports.
`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
`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 boolean` `TEST_BADAPPLES` Whether or not `LuceneTestCase.BadApple` 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_MONSTER` Whether or not `LuceneTestCase.Monster` tests should run.
`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
`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` `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, IndexReader rightReader, boolean deep)` Fields api equivalency
`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 boolean` `callStackContains(Class<?> clazz)` Inspects stack trace if the given class called us.
`static boolean` `callStackContains(Class<?> clazz, String methodName)` Inspects stack trace to figure out if a method of a specific class called us.
`static boolean` `callStackContainsAnyOf(String... methodNames)` Inspects stack trace to figure out if one of the given method names (no class restriction) called us.
`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.
`protected static IndexWriterConfig` `ensureSaneIWCOnNightly(IndexWriterConfig conf)` Ensures that the MergePolicy has sane values for tests that test with lots of documents.
`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 <T extends Throwable> T` `expectThrows(Class<T> expectedType, String noExceptionMessage, 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 <TO extends Throwable,TW extends Throwable> TO` `expectThrowsAnyOf(LinkedHashMap<Class<? extends TO>,List<Class<? extends TW>>> expectedOuterToWrappedTypes, LuceneTestCase.ThrowingRunnable runnable)` Checks that one of the specified wrapped and outer exception classes are thrown by the given runnable, and returns the outer exception.
`static <T extends Throwable> T` `expectThrowsAnyOf(List<Class<? extends T>> expectedTypes, LuceneTestCase.ThrowingRunnable runnable)` Checks a specific exception class is thrown by the given runnable, and returns it.
`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 MergePolicy` `newMergePolicy(Random r, boolean includeMockMP)`
`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, assertArrayEquals, assertArrayEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotEquals, assertNotEquals, assertNotEquals, assertNotEquals, assertNotEquals, assertNotEquals, assertNotEquals, assertNotEquals, 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_MONSTER

    public static final boolean TEST_MONSTER

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

#### TEST_AWAITSFIX

    public static final boolean TEST_AWAITSFIX

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

#### TEST_BADAPPLES

    public static final boolean TEST_BADAPPLES

Whether or not `LuceneTestCase.BadApple` 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 its own line. If iter is null this is logged differently 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(Random r,
                                             boolean includeMockMP)

#### 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`

#### assertTermsEquals

    public void assertTermsEquals(String info,
                                  IndexReader leftReader,
                                  IndexReader rightReader,
                                  boolean deep)
                           throws IOException

Fields api equivalency

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`

#### callStackContains

    public static boolean callStackContains(Class<?> clazz,
                                            String methodName)

Inspects stack trace to figure out if a method of a specific class called us.

#### callStackContainsAnyOf

    public static boolean callStackContainsAnyOf(String... methodNames)

Inspects stack trace to figure out if one of the given method names (no class restriction) called us.

#### callStackContains

    public static boolean callStackContains(Class<?> clazz)

Inspects stack trace if the given class called us.

#### 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 <T extends Throwable> T expectThrows(Class<T> expectedType,
                                                       String noExceptionMessage,
                                                       LuceneTestCase.ThrowingRunnable runnable)

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

#### expectThrowsAnyOf

    public static <T extends Throwable> T expectThrowsAnyOf(List<Class<? extends T>> expectedTypes,
                                                            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.

#### expectThrowsAnyOf

    public static <TO extends Throwable,TW extends Throwable> TO expectThrowsAnyOf(LinkedHashMap<Class<? extends TO>,List<Class<? extends TW>>> expectedOuterToWrappedTypes,
                                                                                   LuceneTestCase.ThrowingRunnable runnable)

Checks that one of the specified wrapped and outer exception classes are thrown by the given runnable, and returns the outer exception. This method accepts outer exceptions with no wrapped exception; an empty list of expected wrapped exception types indicates no 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

#### ensureSaneIWCOnNightly

    protected static IndexWriterConfig ensureSaneIWCOnNightly(IndexWriterConfig conf)

Ensures that the MergePolicy has sane values for tests that test with lots of documents.