* Licensed to the Apache Software Foundation (ASF) under one or more

* contributor license agreements.  See the NOTICE file distributed with

* this work for additional information regarding copyright ownership.

* The ASF licenses this file to You under the Apache License, Version 2.0

* (the "License"); you may not use this file except in compliance with

* the License.  You may obtain a copy of the License at

*

*     http://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

* See the License for the specific language governing permissions and

* limitations under the License.

*/

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

*

* <h3>Class and instance setup.</h3>

*

* <p>

* The preferred way to specify class (suite-level) setup/cleanup is to use

* static methods annotated with {@link BeforeClass} and {@link AfterClass}. Any

* code in these methods is executed within the test framework's control and

* ensure proper setup has been made. <b>Try not to use static initializers

* (including complex final field initializers).</b> Static initializers are

* executed before any setup rules are fired and may cause you (or somebody

* else) headaches.

*

* <p>

* For instance-level setup, use {@link Before} and {@link After} annotated

* methods. If you override either {@link #setUp()} or {@link #tearDown()} in

* your subclass, make sure you call <code>super.setUp()</code> and

* <code>super.tearDown()</code>. This is detected and enforced.

*

* <h3>Specifying test cases</h3>

*

* <p>

* Any test method with a <code>testXXX</code> prefix is considered a test case.

* Any test method annotated with {@link Test} is considered a test case.

*

* <h3>Randomized execution and test facilities</h3>

*

* <p>

* {@link LuceneTestCase} uses {@link RandomizedRunner} to execute test cases.

* {@link RandomizedRunner} has built-in support for tests randomization

* including access to a repeatable {@link Random} instance. See

* {@link #random()} method. Any test using {@link Random} acquired from

* {@link #random()} should be fully reproducible (assuming no race conditions

* between threads etc.). The initial seed for a test case is reported in many

* ways:

* <ul>

*   <li>as part of any exception thrown from its body (inserted as a dummy stack

*   trace entry),</li>

*   <li>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),</li>

*   <li>the master seed can also be accessed manually by getting the current

*   context ({@link RandomizedContext#current()}) and then calling

*   {@link RandomizedContext#getRunnerSeedAsString()}.</li>

* </ul>

*/

  LuceneJUnit3MethodProvider.class,

  JUnit4MethodProvider.class

  RunListenerPrintReproduceInfo.class,

  FailureMarker.class

    QuickPatchThreadsFilter.class

  // --------------------------------------------------------------------

  // Test groups, system properties and other annotations modifying tests

  // --------------------------------------------------------------------

  public static final String SYSPROP_NIGHTLY = "tests.nightly";

  public static final String SYSPROP_WEEKLY = "tests.weekly";

  public static final String SYSPROP_MONSTER = "tests.monster";

  public static final String SYSPROP_AWAITSFIX = "tests.awaitsfix";

  public static final String SYSPROP_SLOW = "tests.slow";

  public static final String SYSPROP_BADAPPLES = "tests.badapples";

  /** @see #ignoreAfterMaxFailures*/

  public static final String SYSPROP_MAXFAILURES = "tests.maxfailures";

  /** @see #ignoreAfterMaxFailures*/

  public static final String SYSPROP_FAILFAST = "tests.failfast";

  /**

   * Annotation for tests that should only be run during nightly builds.

   */

  @Documented

  @Inherited

  @Retention(RetentionPolicy.RUNTIME)

  @TestGroup(enabled = false, sysProperty = SYSPROP_NIGHTLY)

  public @interface Nightly {}

  /**

   * Annotation for tests that should only be run during weekly builds

   */

  @Documented

  @Inherited

  @Retention(RetentionPolicy.RUNTIME)

  @TestGroup(enabled = false, sysProperty = SYSPROP_WEEKLY)

  public @interface Weekly {}

 

  /**

   * Annotation for monster tests that require special setup (e.g. use tons of disk and RAM)

   */

  @Documented

  @Inherited

  @Retention(RetentionPolicy.RUNTIME)

  @TestGroup(enabled = false, sysProperty = SYSPROP_MONSTER)

  public @interface Monster {

    String value();

  }

  /**

   * Annotation for tests which exhibit a known issue and are temporarily disabled.

   */

  @Documented

  @Inherited

  @Retention(RetentionPolicy.RUNTIME)

  @TestGroup(enabled = false, sysProperty = SYSPROP_AWAITSFIX)

  public @interface AwaitsFix {

    /** Point to JIRA entry. */

    public String bugUrl();

  }

  /**

   * Annotation for tests that are slow. Slow tests do run by default but can be

   * disabled if a quick run is needed.

   */

  @Documented

  @Inherited

  @Retention(RetentionPolicy.RUNTIME)

  @TestGroup(enabled = true, sysProperty = SYSPROP_SLOW)

  public @interface Slow {}

  /**

   * Annotation for tests that fail frequently and should

   * be moved to a <a href="https://builds.apache.org/job/Lucene-BadApples-trunk-java7/">"vault" plan in Jenkins</a>.

   *

   * Tests annotated with this will be turned off by default. If you want to enable

   * them, set:

   * <pre>

   * -Dtests.badapples=true

   * </pre>

   */

  @Documented

  @Inherited

  @Retention(RetentionPolicy.RUNTIME)

  @TestGroup(enabled = false, sysProperty = SYSPROP_BADAPPLES)

  public @interface BadApple {

    /** Point to JIRA entry. */

    public String bugUrl();

  }

  /**

   * Annotation for test classes that should avoid certain codec types

   * (because they are expensive, for example).

   */

  @Documented

  @Inherited

  @Retention(RetentionPolicy.RUNTIME)

  @Target(ElementType.TYPE)

  public @interface SuppressCodecs {

    String[] value();

  }

 

  /**

   * Marks any suites which are known not to close all the temporary

   * files. This may prevent temp. files and folders from being cleaned

   * up after the suite is completed.

   *

   * @see LuceneTestCase#createTempDir()

   * @see LuceneTestCase#createTempFile(String, String)

   */

  @Documented

  @Inherited

  @Retention(RetentionPolicy.RUNTIME)

  @Target(ElementType.TYPE)

  public @interface SuppressTempFileChecks {

    /** Point to JIRA entry. */

    public String bugUrl() default "None";

  }

  /**

   * Ignore {@link TestRuleLimitSysouts} for any suite which is known to print

   * over the default limit of bytes to {@link System#out} or {@link System#err}.

   *

   * @see TestRuleLimitSysouts

   */

  @Documented

  @Inherited

  @Retention(RetentionPolicy.RUNTIME)

  @Target(ElementType.TYPE)

  public @interface SuppressSysoutChecks {

    /** Point to JIRA entry. */

    public String bugUrl();

  }

  // -----------------------------------------------------------------

  // Truly immutable fields and constants, initialized once and valid

  // for all suites ever since.

  // -----------------------------------------------------------------

  // :Post-Release-Update-Version.LUCENE_XY:

  /**

   * Use this constant when creating Analyzers and any other version-dependent stuff.

   * <p><b>NOTE:</b> Change this when development starts for new Lucene version:

   */

  public static final Version TEST_VERSION_CURRENT = Version.LUCENE_4_9;

  /**

   * 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 {@link TestRuleLimitSysouts}.

   */

  public static final boolean VERBOSE = systemPropertyAsBoolean("tests.verbose", false);

  /**

   * Enables or disables dumping of {@link InfoStream} messages.

   */

  public static final boolean INFOSTREAM = systemPropertyAsBoolean("tests.infostream", VERBOSE);

  /**

   * 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).

   */

  public static final int RANDOM_MULTIPLIER = systemPropertyAsInt("tests.multiplier", 1);

  /** TODO: javadoc? */

  public static final String DEFAULT_LINE_DOCS_FILE = "europarl.lines.txt.gz";

  /** TODO: javadoc? */

  public static final String JENKINS_LARGE_LINE_DOCS_FILE = "enwiki.random.lines.txt";

  /** Gets the codec to run tests with. */

  public static final String TEST_CODEC = System.getProperty("tests.codec", "random");

  /** Gets the postingsFormat to run tests with. */

  public static final String TEST_POSTINGSFORMAT = System.getProperty("tests.postingsformat", "random");

 

  /** Gets the docValuesFormat to run tests with */

  public static final String TEST_DOCVALUESFORMAT = System.getProperty("tests.docvaluesformat", "random");

  /** Gets the directory to run tests with */

  public static final String TEST_DIRECTORY = System.getProperty("tests.directory", "random");

  /** the line file used by LineFileDocs */

  public static final String TEST_LINE_DOCS_FILE = System.getProperty("tests.linedocsfile", DEFAULT_LINE_DOCS_FILE);

  /** Whether or not {@link Nightly} tests should run. */

  public static final boolean TEST_NIGHTLY = systemPropertyAsBoolean(SYSPROP_NIGHTLY, false);

  /** Whether or not {@link Weekly} tests should run. */

  public static final boolean TEST_WEEKLY = systemPropertyAsBoolean(SYSPROP_WEEKLY, false);

 

  /** Whether or not {@link AwaitsFix} tests should run. */

  public static final boolean TEST_AWAITSFIX = systemPropertyAsBoolean(SYSPROP_AWAITSFIX, false);

  /** Whether or not {@link Slow} tests should run. */

  public static final boolean TEST_SLOW = systemPropertyAsBoolean(SYSPROP_SLOW, false);

  /** Throttling, see {@link MockDirectoryWrapper#setThrottling(Throttling)}. */

  public static final Throttling TEST_THROTTLING = TEST_NIGHTLY ? Throttling.SOMETIMES : Throttling.NEVER;

  /** Leave temporary files on disk, even on successful runs. */

  public static final boolean LEAVE_TEMPORARY;

  static {

    boolean defaultValue = false;

    for (String property : Arrays.asList(

        "tests.leaveTemporary" /* ANT tasks's (junit4) flag. */,

        "tests.leavetemporary" /* lowercase */,

        "tests.leavetmpdir" /* default */,

        "solr.test.leavetmpdir" /* Solr's legacy */)) {

      defaultValue |= systemPropertyAsBoolean(property, false);

    }

    LEAVE_TEMPORARY = defaultValue;

  }

  /**

   * These property keys will be ignored in verification of altered properties.

   * @see SystemPropertiesInvariantRule

   * @see #ruleChain

   * @see #classRules

   */

  private static final String [] IGNORED_INVARIANT_PROPERTIES = {

    "user.timezone", "java.rmi.server.randomIDs"

  };

  /** Filesystem-based {@link Directory} implementations. */

  private static final List<String> FS_DIRECTORIES = Arrays.asList(

    "SimpleFSDirectory",

    "NIOFSDirectory",

    "MMapDirectory"

  );

  /** All {@link Directory} implementations. */

  private static final List<String> CORE_DIRECTORIES;

  static {

    CORE_DIRECTORIES = new ArrayList<>(FS_DIRECTORIES);

    CORE_DIRECTORIES.add("RAMDirectory");

  };

 

  protected static final Set<String> doesntSupportOffsets = new HashSet<>(Arrays.asList(

    "Lucene3x",

    "MockFixedIntBlock",

    "MockVariableIntBlock",

    "MockSep",

    "MockRandom"

  ));

 

  // -----------------------------------------------------------------

  // Fields initialized in class or instance rules.

  // -----------------------------------------------------------------

  /**

   * When {@code true}, Codecs for old Lucene version will support writing

   * indexes in that format. Defaults to {@code false}, can be disabled by

   * specific tests on demand.

   *

   * @lucene.internal

   */

  public static boolean OLD_FORMAT_IMPERSONATION_IS_ACTIVE = false;

  // -----------------------------------------------------------------

  // Class level (suite) rules.

  // -----------------------------------------------------------------

 

  /**

   * Stores the currently class under test.

   */

  private static final TestRuleStoreClassName classNameRule;

  /**

   * Class environment setup rule.

   */

  static final TestRuleSetupAndRestoreClassEnv classEnvRule;

  /**

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

   */

  private static TestRuleMarkFailure suiteFailureMarker;

  /**

   * Ignore tests after hitting a designated number of initial failures. This

   * is truly a "static" global singleton since it needs to span the lifetime of all

   * test classes running inside this JVM (it cannot be part of a class rule).

   *

   * <p>This poses some problems for the test framework's tests because these sometimes

   * trigger intentional failures which add up to the global count. This field contains

   * a (possibly) changing reference to {@link TestRuleIgnoreAfterMaxFailures} and we

   * dispatch to its current value from the {@link #classRules} chain using {@link TestRuleDelegate}. 

   */

  private static final AtomicReference<TestRuleIgnoreAfterMaxFailures> ignoreAfterMaxFailuresDelegate;

  private static final TestRule ignoreAfterMaxFailures;

  static {

    int maxFailures = systemPropertyAsInt(SYSPROP_MAXFAILURES, Integer.MAX_VALUE);

    boolean failFast = systemPropertyAsBoolean(SYSPROP_FAILFAST, false);

    if (failFast) {

      if (maxFailures == Integer.MAX_VALUE) {

        maxFailures = 1;

      } else {

        Logger.getLogger(LuceneTestCase.class.getSimpleName()).warning(

            "Property '" + SYSPROP_MAXFAILURES + "'=" + maxFailures + ", 'failfast' is" +

            " ignored.");

      }

    }

    ignoreAfterMaxFailuresDelegate =

        new AtomicReference<>(

            new TestRuleIgnoreAfterMaxFailures(maxFailures));

    ignoreAfterMaxFailures = TestRuleDelegate.of(ignoreAfterMaxFailuresDelegate);

  }

 

  /**

   * Try to capture streams early so that other classes don't have a chance to steal references

   * to them (as is the case with ju.logging handlers).

   */

  static {

    TestRuleLimitSysouts.checkCaptureStreams();

    Logger.getGlobal().getHandlers();

  }

  /**

   * Temporarily substitute the global {@link TestRuleIgnoreAfterMaxFailures}. See

   * {@link #ignoreAfterMaxFailuresDelegate} for some explanation why this method

   * is needed.

   */

  public static TestRuleIgnoreAfterMaxFailures replaceMaxFailureRule(TestRuleIgnoreAfterMaxFailures newValue) {

    return ignoreAfterMaxFailuresDelegate.getAndSet(newValue);

  }

  /**

   * Max 10mb of static data stored in a test suite class after the suite is complete.

   * Prevents static data structures leaking and causing OOMs in subsequent tests.

   */

  private final static long STATIC_LEAK_THRESHOLD = 10 * 1024 * 1024;

  /** By-name list of ignored types like loggers etc. */

  private final static Set<String> STATIC_LEAK_IGNORED_TYPES =

      Collections.unmodifiableSet(new HashSet<>(Arrays.asList(

      "org.slf4j.Logger",

      "org.apache.solr.SolrLogFormatter",

      EnumSet.class.getName())));

  /**

   * This controls how suite-level rules are nested. It is important that _all_ rules declared

   * in {@link LuceneTestCase} are executed in proper order if they depend on each

   * other.

   */

  @ClassRule

  public static TestRule classRules = RuleChain

    .outerRule(new TestRuleIgnoreTestSuites())

    .around(ignoreAfterMaxFailures)

    .around(suiteFailureMarker = new TestRuleMarkFailure())

    .around(new TestRuleAssertionsRequired())

    .around(new TestRuleLimitSysouts(suiteFailureMarker))

    .around(new TemporaryFilesCleanupRule())

    .around(new StaticFieldsInvariantRule(STATIC_LEAK_THRESHOLD, true) {

      @Override

      protected boolean accept(java.lang.reflect.Field field) {

        // Don't count known classes that consume memory once.

        if (STATIC_LEAK_IGNORED_TYPES.contains(field.getType().getName())) {

          return false;

        }

        // Don't count references from ourselves, we're top-level.

        if (field.getDeclaringClass() == LuceneTestCase.class) {

          return false;

        }

        return super.accept(field);

      }

    })

    .around(new NoClassHooksShadowingRule())

    .around(new NoInstanceHooksOverridesRule() {

      @Override

      protected boolean verify(Method key) {

        String name = key.getName();

        return !(name.equals("setUp") || name.equals("tearDown"));

      }

    })

    .around(new SystemPropertiesInvariantRule(IGNORED_INVARIANT_PROPERTIES))

    .around(classNameRule = new TestRuleStoreClassName())

    .around(classEnvRule = new TestRuleSetupAndRestoreClassEnv());

  // -----------------------------------------------------------------

  // Test level rules.

  // -----------------------------------------------------------------

  /** Enforces {@link #setUp()} and {@link #tearDown()} calls are chained. */

  private TestRuleSetupTeardownChained parentChainCallRule = new TestRuleSetupTeardownChained();

  /** Save test thread and name. */

  private TestRuleThreadAndTestName threadAndTestNameRule = new TestRuleThreadAndTestName();

  /** Taint suite result with individual test failures. */

  private TestRuleMarkFailure testFailureMarker = new TestRuleMarkFailure(suiteFailureMarker);

 

  /**

   * This controls how individual test rules are nested. It is important that

   * _all_ rules declared in {@link LuceneTestCase} are executed in proper order

   * if they depend on each other.

   */

  @Rule

  public final TestRule ruleChain = RuleChain

    .outerRule(testFailureMarker)

    .around(ignoreAfterMaxFailures)

    .around(threadAndTestNameRule)

    .around(new SystemPropertiesInvariantRule(IGNORED_INVARIANT_PROPERTIES))

    .around(new TestRuleSetupAndRestoreInstanceEnv())

    .around(new TestRuleFieldCacheSanity())

    .around(parentChainCallRule);

  private static final Map<String,FieldType> fieldToType = new HashMap<String,FieldType>();

  enum LiveIWCFlushMode {BY_RAM, BY_DOCS, EITHER};

  /** Set by TestRuleSetupAndRestoreClassEnv */

  static LiveIWCFlushMode liveIWCFlushMode;

  static void setLiveIWCFlushMode(LiveIWCFlushMode flushMode) {

    liveIWCFlushMode = flushMode;

  }

  // -----------------------------------------------------------------

  // Suite and test case setup/ cleanup.

  // -----------------------------------------------------------------

  /**

   * For subclasses to override. Overrides must call {@code super.setUp()}.

   */

  @Before

  public void setUp() throws Exception {

    parentChainCallRule.setupCalled = true;

  }

  /**

   * For subclasses to override. Overrides must call {@code super.tearDown()}.

   */

  @After

  public void tearDown() throws Exception {

    parentChainCallRule.teardownCalled = true;

    fieldToType.clear();

  }

  // -----------------------------------------------------------------

  // Test facilities and facades for subclasses.

  // -----------------------------------------------------------------

  /**

   * Access to the current {@link 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 {@link Random} instance will be

   * <b>different</b> when this method is called inside a {@link BeforeClass} hook (static

   * suite scope) and within {@link Before}/ {@link After} hooks or test methods.

   *

   * <p>The returned instance must not be shared with other threads or cross a single scope's

   * boundary. For example, a {@link Random} acquired within a test method shouldn't be reused

   * for another test case.

   *

   * <p>There is an overhead connected with getting the {@link Random} for a particular context

   * and thread. It is better to cache the {@link Random} locally if tight loops with multiple

   * invocations are present or create a derivative local {@link Random} for millions of calls

   * like this:

   * <pre>

   * Random random = new Random(random().nextLong());

   * // tight loop with many invocations.

   * </pre>

   */

  public static Random random() {

    return RandomizedContext.current().getRandom();

  }

  /**

   * Registers a {@link Closeable} resource that should be closed after the test

   * completes.

   *

   * @return <code>resource</code> (for call chaining).

   */

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

    return RandomizedContext.current().closeAtEnd(resource, LifecycleScope.TEST);

  }

  /**

   * Registers a {@link Closeable} resource that should be closed after the suite

   * completes.

   *

   * @return <code>resource</code> (for call chaining).

   */

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

    return RandomizedContext.current().closeAtEnd(resource, LifecycleScope.SUITE);

  }

  /**

   * Return the current class being tested.

   */

  public static Class<?> getTestClass() {

    return classNameRule.getTestClass();

  }

  /**

   * Return the name of the currently executing test case.

   */

  public String getTestName() {

    return threadAndTestNameRule.testMethodName;

  }

  /**

   * 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.

   */

  public static SegmentReader getOnlySegmentReader(DirectoryReader reader) {

    List<AtomicReaderContext> subReaders = reader.leaves();

    if (subReaders.size() != 1)

      throw new IllegalArgumentException(reader + " has " + subReaders.size() + " segments instead of exactly one");

    final AtomicReader r = subReaders.get(0).reader();

    assertTrue(r instanceof SegmentReader);

    return (SegmentReader) r;

  }

  /**

   * Returns true if and only if the calling thread is the primary thread

   * executing the test case.

   */

  protected boolean isTestThread() {

    assertNotNull("Test case thread not set?", threadAndTestNameRule.testCaseThread);

    return Thread.currentThread() == threadAndTestNameRule.testCaseThread;

  }

  /**

   * Asserts that FieldCacheSanityChecker does not detect any

   * problems with FieldCache.DEFAULT.

   * <p>

   * If any problems are found, they are logged to System.err

   * (allong with the msg) when the Assertion is thrown.

   * </p>

   * <p>

   * This method is called by tearDown after every test method,

   * however IndexReaders scoped inside test methods may be garbage

   * collected prior to this method being called, causing errors to

   * be overlooked. Tests are encouraged to keep their IndexReaders

   * scoped at the class level, or to explicitly call this method

   * directly in the same scope as the IndexReader.

   * </p>

   *

   * @see org.apache.lucene.util.FieldCacheSanityChecker

   */

  protected static void assertSaneFieldCaches(final String msg) {

    final CacheEntry[] entries = FieldCache.DEFAULT.getCacheEntries();

    Insanity[] insanity = null;

    try {

      try {

        insanity = FieldCacheSanityChecker.checkSanity(entries);

      } catch (RuntimeException e) {

        dumpArray(msg + ": FieldCache", entries, System.err);

        throw e;

      }

      assertEquals(msg + ": Insane FieldCache usage(s) found",

                   0, insanity.length);

      insanity = null;

    } finally {

      // report this in the event of any exception/failure

      // if no failure, then insanity will be null anyway

      if (null != insanity) {

        dumpArray(msg + ": Insane FieldCache usage(s)", insanity, System.err);

      }

    }

  }

  /**

   * Returns a number of at least <code>i</code>

   * <p>

   * The actual number returned will be influenced by whether {@link #TEST_NIGHTLY}

   * is active and {@link #RANDOM_MULTIPLIER}, but also with some random fudge.

   */

  public static int atLeast(Random random, int i) {

    int min = (TEST_NIGHTLY ? 2*i : i) * RANDOM_MULTIPLIER;

    int max = min+(min/2);

    return TestUtil.nextInt(random, min, max);

  }

 

  public static int atLeast(int i) {

    return atLeast(random(), i);

  }

 

  /**

   * Returns true if something should happen rarely,

   * <p>

   * The actual number returned will be influenced by whether {@link #TEST_NIGHTLY}

   * is active and {@link #RANDOM_MULTIPLIER}.

   */

  public static boolean rarely(Random random) {

    int p = TEST_NIGHTLY ? 10 : 1;

    p += (p * Math.log(RANDOM_MULTIPLIER));

    int min = 100 - Math.min(p, 50); // never more than 50

    return random.nextInt(100) >= min;

  }

 

  public static boolean rarely() {

    return rarely(random());

  }

 

  public static boolean usually(Random random) {

    return !rarely(random);

  }

 

  public static boolean usually() {

    return usually(random());

  }

  public static void assumeTrue(String msg, boolean condition) {

    RandomizedTest.assumeTrue(msg, condition);

  }

  public static void assumeFalse(String msg, boolean condition) {

    RandomizedTest.assumeFalse(msg, condition);

  }

  public static void assumeNoException(String msg, Exception e) {