Merge pull request #319 from jwjacobson/dev

Update tests to reflect search refactoring

docs/source/using/playing.rst

@@ -3,9 +3,9 @@ Playing tunes
 
 You can 'play' tunes by clicking the **play** button on the homepage, or by using the **Play** page, accessed from the navbar.
 
-The **Play** page will recommend a tune to play based on your search results. It will not suggest tunes with a Learning value of "don't know." If you submit an empty search if will use your whole repertoire (except the ones you don't know).
+The **Play** page will recommend a tune to play based on your search results. It will not suggest tunes with a Knowledge value of "don't know." If you submit an empty search if will use your whole repertoire (except the ones you don't know).
 
-Regularly updating your plays is the most useful feature of the app!
+The more consistently you update your plays, the more useful the app will be.
 
 
 

docs/source/using/searching.rst

@@ -5,12 +5,27 @@ Searching your repertoire
 
 The **Home**, **Play**, and **Public** pages all contain a search box that uses the same logic.
 
-By default, every field is searched for your search term. If you enter multiple terms, the search uses AND logic. For example, if you search ``monk`` you will see all tunes with monk in any fields (usually composer). If you search ``monk bud``, you will only see "In Walked Bud" (assuming it's in your repertoire).
+Basic search
+----------------
+
+By default, every field is searched for your search term. If you enter multiple terms, the search uses AND logic to combine them. For example, if you search ``monk`` you will see all tunes with monk in any fields (usually composer). If you search ``monk bud``, you will only see "In Walked Bud" (assuming it's in your repertoire).
 
 Jazz composer names have built-in substitutions using their nicknames or first names, so searching ``miles`` will return Miles Davis tunes, ``bird`` will return Charlie Parker tunes, etc.
 
-Use a ``-`` before a term to exclude it from the search results.
+The default search is often sufficient, since the contents of the fields tend to be discrete: if the search term ``love`` probably only refers to the contents of the Title field, ``Golson`` to the composer field, etc. However, some fields are trickier. If you want to search for the key of Ab using the default search, your query ``Ab`` will also pick up any song forms containing the sequence AB, which is almost all of them. For such cases you can use field-specific search.
+
+Field-specific search
+----------------------
+You can use the format ``field:term`` to search a specific field. Currently supported fields are **title**, **composer**, **key** (the key column, a tune's main key), **keys** (both the Key and Other Keys columns), **form**, **style**, **meter**, **year**, and **tags**.
 
-You can also use the format ``field:term`` to search a specific field. Currently supported fields are **title**, **composer**, **key** (the key column, a tune's main key), **keys** (both the Key and Other Keys columns), **form**, **style**, **meter**, **year**, and **tags**. It is most useful for key, keys, meter, and form.
+.. note:: Field-specific search is most useful for the key, keys, meter, and form fields.
 
+Term exclusion
+---------------
+Use a ``-`` before a term to exclude it from the search results.
+
+Timespan filtering: Haven't Played In
+--------------------------------------
 The **haven't played in** dropdown lets you filter by how long it's been since you've played a tune. This allows you to easily target tunes at the highest risk of being forgotten.
+
+.. note:: Timespan filtering is one of the most useful parts of the app!

tests/test_functions.py

@@ -247,8 +247,9 @@ def test_exclude_term(tune_set):
 
 
 def test_search_field_title(tune_set):
-    search_term = "title:you"
-    result = search_field(tune_set["tunes"], search_term)
+    field = "title"
+    term = "you"
+    result = search_field(tune_set["tunes"], field, term)
     expected_titles = {"All the Things You Are", "I Remember You"}
 
     assert result.count() == 2
@@ -257,8 +258,9 @@ def test_search_field_title(tune_set):
 
 
 def test_search_field_composer(tune_set):
-    search_term = "composer:parker"
-    result = search_field(tune_set["tunes"], search_term)
+    field = "composer"
+    term = "parker"
+    result = search_field(tune_set["tunes"], field, term)
     expected_composer = "Parker"
     expected_titles = {"Confirmation", "Dewey Square"}
 
@@ -269,8 +271,9 @@ def test_search_field_composer(tune_set):
 
 
 def test_search_field_key(tune_set):
-    search_term = "key:f"
-    result = search_field(tune_set["tunes"], search_term)
+    field = "key"
+    term = "f"
+    result = search_field(tune_set["tunes"], field, term)
     expected_key = "F"
     expected_titles = {"Confirmation", "Long Ago and Far Away", "I Remember You"}
 
@@ -281,8 +284,9 @@ def test_search_field_key(tune_set):
 
 
 def test_search_field_keys(tune_set):
-    search_term = "keys:eb"
-    result = search_field(tune_set["tunes"], search_term)
+    field = "keys"
+    term = "eb"
+    result = search_field(tune_set["tunes"], field, term)
     expected_key = "Eb"
     expected_titles = {
         "Dewey Square",
@@ -297,8 +301,9 @@ def test_search_field_keys(tune_set):
 
 
 def test_search_field_form(tune_set):
-    search_term = "form:abac"
-    result = search_field(tune_set["tunes"], search_term)
+    field = "form"
+    term = "abac"
+    result = search_field(tune_set["tunes"], field, term)
     expected_form = "ABAC"
     expected_titles = {
         "Dearly Beloved",
@@ -313,8 +318,9 @@ def test_search_field_form(tune_set):
 
 
 def test_search_field_style(tune_set):
-    search_term = "style:jazz"
-    result = search_field(tune_set["tunes"], search_term)
+    field = "style"
+    term = "jazz"
+    result = search_field(tune_set["tunes"], field, term)
     expected_style = "jazz"
     expected_titles = {
         "Confirmation",
@@ -331,8 +337,9 @@ def test_search_field_style(tune_set):
 
 
 def test_search_field_meter(tune_set):
-    search_term = "meter:3"
-    result = search_field(tune_set["tunes"], search_term)
+    field = "meter"
+    term = "3"
+    result = search_field(tune_set["tunes"], field, term)
     expected_meter = 3
     expected_titles = {"Someday My Prince Will Come"}
 
@@ -343,8 +350,9 @@ def test_search_field_meter(tune_set):
 
 
 def test_search_field_year(tune_set):
-    search_term = "year:1941"
-    result = search_field(tune_set["tunes"], search_term)
+    field = "year"
+    term = "1941"
+    result = search_field(tune_set["tunes"], field, term)
     expected_year = 1941
     expected_titles = {"I Remember You", "A Flower is a Lovesome Thing"}
 
@@ -355,8 +363,9 @@ def test_search_field_year(tune_set):
 
 
 def test_search_field_year_partial(tune_set):
-    search_term = "year:195"
-    result = search_field(tune_set["tunes"], search_term)
+    field = "year"
+    term = "195"
+    result = search_field(tune_set["tunes"], field, term)
     expected_years = {1950, 1951, 1952, 1953, 1954, 1955, 1956, 1957, 1958, 1959}
     expected_titles = {"Kary's Trance", "Coming on the Hudson"}