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