org.apache.lucene.search

## Class CheckHits

- java.lang.Object
- - org.apache.lucene.search.CheckHits

-     public class CheckHits
      extends Object

  Utility class for asserting expected hits in tests.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `CheckHits.ExplanationAsserter` Asserts that the score explanation for every document matching a query corresponds with the true score.
    `static class` | `CheckHits.ExplanationAssertingSearcher` an IndexSearcher that implicitly checks hte explanation of every match whenever it executes a search.
    `static class` | `CheckHits.MatchesAsserter` Asserts that the `Matches` from a query is non-null whenever the document its created for is a hit.
    `static class` | `CheckHits.SetCollector` Just collects document ids into a set.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static float` | `EXPLAIN_SCORE_TOLERANCE_DELTA` Some explains methods calculate their values though a slightly different order of operations from the actual scoring method ...
    `static float` | `EXPLAIN_SCORE_TOLERANCE_MINIMUM` In general we use a relative epsilon, but some tests do crazy things like boost documents with 0, creating tiny tiny scores where the relative difference is large but the absolute difference is tiny.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CheckHits()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `checkDocIds(String mes, int[] results, ScoreDoc[] hits)` Tests that a Hits has an expected order of documents
    `static void` | `checkEqual(Query query, ScoreDoc[] hits1, ScoreDoc[] hits2)`
    `static void` | `checkExplanations(Query query, String defaultFieldName, IndexSearcher searcher)` Asserts that the explanation value for every document matching a query corresponds with the true score.
    `static void` | `checkExplanations(Query query, String defaultFieldName, IndexSearcher searcher, boolean deep)` Asserts that the explanation value for every document matching a query corresponds with the true score.
    `static void` | `checkHitCollector(Random random, Query query, String defaultFieldName, IndexSearcher searcher, int[] results)` Tests that a query matches the an expected set of documents using a HitCollector.
    `static void` | `checkHits(Random random, Query query, String defaultFieldName, IndexSearcher searcher, int[] results)` Tests that a query matches the an expected set of documents using Hits.
    `static void` | `checkHitsQuery(Query query, ScoreDoc[] hits1, ScoreDoc[] hits2, int[] results)` Tests that two queries have an expected order of documents, and that the two queries have the same score values.
    `static void` | `checkMatches(Query query, IndexSearcher searcher)` Asserts that the result of calling `Weight.matches(LeafReaderContext, int)` for every document matching a query returns a non-null `Matches`
    `static void` | `checkNoMatchExplanations(Query q, String defaultFieldName, IndexSearcher searcher, int[] results)` Tests that all documents up to maxDoc which are *not* in the expected result set, have an explanation which indicates that the document does not match
    `static float` | `explainToleranceDelta(float f1, float f2)` returns a reasonable epsilon for comparing two floats, where minor differences are acceptable such as score vs.
    `static String` | `hits2str(ScoreDoc[] hits1, ScoreDoc[] hits2, int start, int end)`
    `static String` | `topdocsString(TopDocs docs, int start, int end)`
    `static void` | `verifyExplanation(String q, int doc, float score, boolean deep, Explanation expl)` Assert that an explanation has the expected score, and optionally that its sub-details max/sum/factor match to that score.

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

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

- - ### Field Detail

    - #### EXPLAIN_SCORE_TOLERANCE_DELTA

          public static float EXPLAIN_SCORE_TOLERANCE_DELTA

      Some explains methods calculate their values though a slightly different order of operations from the actual scoring method ... this allows for a small amount of relative variation

    - #### EXPLAIN_SCORE_TOLERANCE_MINIMUM

          public static float EXPLAIN_SCORE_TOLERANCE_MINIMUM

      In general we use a relative epsilon, but some tests do crazy things like boost documents with 0, creating tiny tiny scores where the relative difference is large but the absolute difference is tiny. we ensure the the epsilon is always at least this big.

  - ### Constructor Detail

    - #### CheckHits

          public CheckHits()

  - ### Method Detail

    - #### checkNoMatchExplanations

          public static void checkNoMatchExplanations(Query q,
                                                      String defaultFieldName,
                                                      IndexSearcher searcher,
                                                      int[] results)
                                               throws IOException

      Tests that all documents up to maxDoc which are *not* in the expected result set, have an explanation which indicates that the document does not match
      Throws:
        `IOException`

    - #### checkHitCollector

          public static void checkHitCollector(Random random,
                                               Query query,
                                               String defaultFieldName,
                                               IndexSearcher searcher,
                                               int[] results)
                                        throws IOException

      Tests that a query matches the an expected set of documents using a HitCollector.

      Note that when using the HitCollector API, documents will be collected if they "match" regardless of what their score is.

      Parameters:
        `query` - the query to test
        `searcher` - the searcher to test the query against
        `defaultFieldName` - used for displaying the query in assertion messages
        `results` - a list of documentIds that must match the query
      Throws:
        `IOException`
      See Also:
        `checkHits(java.util.Random, org.apache.lucene.search.Query, java.lang.String, org.apache.lucene.search.IndexSearcher, int[])`

    - #### checkHits

          public static void checkHits(Random random,
                                       Query query,
                                       String defaultFieldName,
                                       IndexSearcher searcher,
                                       int[] results)
                                throws IOException

      Tests that a query matches the an expected set of documents using Hits.

      Note that when using the Hits API, documents will only be returned if they have a positive normalized score.

      Parameters:
        `query` - the query to test
        `searcher` - the searcher to test the query against
        `defaultFieldName` - used for displaing the query in assertion messages
        `results` - a list of documentIds that must match the query
      Throws:
        `IOException`
      See Also:
        `checkHitCollector(java.util.Random, org.apache.lucene.search.Query, java.lang.String, org.apache.lucene.search.IndexSearcher, int[])`

    - #### checkDocIds

          public static void checkDocIds(String mes,
                                         int[] results,
                                         ScoreDoc[] hits)

      Tests that a Hits has an expected order of documents

    - #### checkHitsQuery

          public static void checkHitsQuery(Query query,
                                            ScoreDoc[] hits1,
                                            ScoreDoc[] hits2,
                                            int[] results)

      Tests that two queries have an expected order of documents, and that the two queries have the same score values.

    - #### checkEqual

          public static void checkEqual(Query query,
                                        ScoreDoc[] hits1,
                                        ScoreDoc[] hits2)

    - #### hits2str

          public static String hits2str(ScoreDoc[] hits1,
                                        ScoreDoc[] hits2,
                                        int start,
                                        int end)

    - #### topdocsString

          public static String topdocsString(TopDocs docs,
                                             int start,
                                             int end)

    - #### checkExplanations

          public static void checkExplanations(Query query,
                                               String defaultFieldName,
                                               IndexSearcher searcher)
                                        throws IOException

      Asserts that the explanation value for every document matching a query corresponds with the true score.
      Parameters:
        `query` - the query to test
        `searcher` - the searcher to test the query against
        `defaultFieldName` - used for displaing the query in assertion messages
      Throws:
        `IOException`
      See Also:
        `CheckHits.ExplanationAsserter`, `for a "deep" testing of the explanation details.`

    - #### checkExplanations

          public static void checkExplanations(Query query,
                                               String defaultFieldName,
                                               IndexSearcher searcher,
                                               boolean deep)
                                        throws IOException

      Asserts that the explanation value for every document matching a query corresponds with the true score. Optionally does "deep" testing of the explanation details.
      Parameters:
        `query` - the query to test
        `searcher` - the searcher to test the query against
        `defaultFieldName` - used for displaing the query in assertion messages
        `deep` - indicates whether a deep comparison of sub-Explanation details should be executed
      Throws:
        `IOException`
      See Also:
        `CheckHits.ExplanationAsserter`

    - #### explainToleranceDelta

          public static float explainToleranceDelta(float f1,
                                                    float f2)

      returns a reasonable epsilon for comparing two floats, where minor differences are acceptable such as score vs. explain

    - #### checkMatches

          public static void checkMatches(Query query,
                                          IndexSearcher searcher)
                                   throws IOException

      Asserts that the result of calling `Weight.matches(LeafReaderContext, int)` for every document matching a query returns a non-null `Matches`
      Parameters:
        `query` - the query to test
        `searcher` - the search to test against
      Throws:
        `IOException`

    - #### verifyExplanation

          public static void verifyExplanation(String q,
                                               int doc,
                                               float score,
                                               boolean deep,
                                               Explanation expl)

      Assert that an explanation has the expected score, and optionally that its sub-details max/sum/factor match to that score.
      Parameters:
        `q` - String representation of the query for assertion messages
        `doc` - Document ID for assertion messages
        `score` - Real score value of doc with query q
        `deep` - indicates whether a deep comparison of sub-Explanation details should be executed
        `expl` - The Explanation to match against score

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