4 The fuzzy selector uses a tool called `fzf`_. It allows you to filter down all of the task labels
5 from a terminal based UI and an intelligent fuzzy finding algorithm. If the ``fzf`` binary is not
6 installed, you'll be prompted to bootstrap it on first run.
9 Understanding the Interface
10 ---------------------------
12 When you run ``mach try fuzzy`` an interface similar to the one below will open. This is `fzf`_.
16 There's a lot to unpack here, so let's examine each component a bit more closely.
18 A. The set of tasks that match the currently typed-out query. In the above image only tasks that
19 match the query ``'linux64 mochibrochr`` are displayed.
21 B. The set of selected tasks. These are the tasks that will be scheduled once you hit ``Enter``.
22 In other words, if the task you want does not appear here, *it won't be scheduled*.
24 C. Count information of the form ``x/y (z)``, where ``x`` is the number of tasks that match the
25 current query, ``y`` is the total number of tasks and ``z`` is the number of tasks you have
28 D. The input bar for entering queries. As you type you'll notice the list of tasks in ``A``
29 starts to update immediately. In the image above, the query ``'linux64 mochibrochr`` is entered.
30 Correspondingly only tasks matching that query are displayed.
32 In general terms, you first find tasks on the left. Then you move them over to the right by
33 selecting them. Once you are satisfied with your selection, press ``Enter`` to push to try.
39 There are few ways you can select tasks. If you are feeling a bit overwhelmed, it might be best to
40 stick with the mouse to start:
42 1. Enter a query (e.g ``mochitest``) to reduce the task list a little.
43 2. Scroll up and look for the task(s) you want.
44 3. ``Right-Click`` as many tasks as desired to select them.
45 4. Optionally delete your query, go back to step 1) and repeat.
46 5. Press ``Enter`` to push (or ``Esc`` to cancel).
50 Dependencies are automatically filled in, so you can select a test task without needing
51 to select the build it depends on.
53 As you ``Right-Click``, notice that a little arrow appears to the left of the task label. This
54 indicates that the task is selected and exists in the preview pane to the right.
56 Once you are a bit more comfortable with the interface, using the keyboard is much better at quickly
57 selecting tasks. Here are the main shortcuts you'll need:
61 Ctrl-K / Up => Move cursor up
62 Ctrl-J / Down => Move cursor down
63 Tab => Select task + move cursor down
64 Shift-Tab => Select task + move cursor up
65 Ctrl-A => Select all currently filtered tasks
66 Ctrl-T => Toggle select all currently filtered tasks
67 Ctrl-D => De-select all selected tasks (both filtered and not)
68 Alt-Bspace => Clear query from input bar
69 Enter => Accept selection and exit
70 Ctrl-C / Esc => Cancel selection and exit
71 ? => Toggle preview pane
74 The process for selecting tasks is otherwise the same as for a mouse. A particularly fast and
75 powerful way to select tasks is to:
79 Write a precise query => Ctrl-A => Alt-Bspace => Repeat
81 As before, when you are satisfied with your selection press ``Enter`` and all the tasks in the
82 preview pane will be pushed to try. If you change your mind you can press ``Esc`` or ``Ctrl-C`` to
83 exit the interface without pushing anything.
87 Initially ``fzf`` will automatically select whichever task is under your cursor. This is a
88 convenience feature for the case where you are only selecting a single task. This feature will be
89 turned off as soon as you *lock in* a selection with ``Right-Click``, ``Tab`` or ``Ctrl-A``.
95 Queries are built from a series of terms, each separated by a space. Terms are logically joined by
96 the AND operator. For example:
102 This query has two terms, and is the equivalent of saying: Give me all the tasks that match both the
103 term ``'windows'`` and the term ``'mochitest'``. In other words, this query matches all Windows
106 The single quote prefix before each term tells ``fzf`` to use exact substring matches, so only tasks
107 that contain both the literal string ``windows`` AND the literal string ``mochitest`` will be
110 Another thing to note is that the order of the terms makes no difference, so ``'windows 'mochitest``
111 and ``'mochitest 'windows`` are equivalent.
117 If a term is *not* prefixed with a single quote, that makes it a fuzzy term. This means the
118 characters in the term need to show up in order, but not in sequence. E.g the fuzzy term ``max``
119 would match the string ``mozilla firefox`` (as first there is an ``m``, then an ``a`` and finally an
120 ``x``), but not the string ``firefox by mozilla`` (since the ``x`` is now out of order). Here's a
121 less contrived example:
127 Like the query above, this one would also select all Windows mochitest tasks. But it will
132 test-macosx1014-64-shippable/opt-talos-sessionrestore-many-windows-e10s
134 This is because both sequences of letters (``wndws`` and ``mchtst``) independently appear in order
135 somewhere in this string (remember the order of the terms makes no difference).
137 At first fuzzy terms may not seem very useful, but they are actually extremely powerful! Let's use
138 the term from the interface image above, ``'linux64 mochibrochr``, as an example. First, just notice
139 how in the image ``fzf`` highlights the characters that constitute the match in green. Next, notice
140 how typing ``mochibrochr`` can quickly get us all mochitest browser-chrome tasks. The power of fuzzy
141 terms is that you don't need to memorize the exact task labels you are looking for. Just start
142 typing something you think is vaguely correct and chances are you'll see the task you're looking for.
148 The following modifiers can be applied to a search term:
152 'word => exact match (line must contain the literal string "word")
153 ^word => exact prefix match (line must start with literal "word")
154 word$ => exact suffix match (line must end with literal "word")
155 !word => exact negation match (line must not contain literal "word")
156 'a | 'b => OR operator (joins two exact match operators together)
162 ^start 'exact | 'other !ignore fuzzy end$
164 would match the string:
168 starting to bake isn't exactly fun, but pizza is yummy in the end
172 The best way to learn how to write queries is to run ``mach try fuzzy --no-push`` and play
173 around with all of these modifiers!
176 Specifying Queries on the Command Line
177 --------------------------------------
179 Sometimes it's more convenient to skip the interactive interface and specify a query on the command
180 line with ``-q/--query``. This is equivalent to opening the interface then typing:
181 ``<query><ctrl-a><enter>``.
185 .. code-block:: shell
187 # selects all mochitest tasks
188 $ mach try fuzzy --query "mochitest"
190 You can pass in multiple queries at once and the results of each will be joined together:
192 .. code-block:: shell
194 # selects all mochitest and reftest tasks
195 $ mach try fuzzy -q "mochitest" -q "reftest"
197 If instead you want the intersection of queries, you can pass in ``-x/--and``:
199 .. code-block:: shell
201 # selects all windows mochitest tasks
202 $ mach try fuzzy --and -q "mochitest" -q "windows"
208 :doc:`Presets <../presets>` make it easy to run a pre-determined set of tasks. But sometimes you
209 might not want to run that set exactly as is, you may only want to use the preset as a starting
210 point then add or remove tasks as needed. This can be accomplished with ``-q/--query`` or
211 ``-i/--interactive``.
213 Here are some examples of adding tasks to a preset:
215 .. code-block:: shell
217 # selects all perf tasks plus all mochitest-chrome tasks
218 $ mach try fuzzy --preset perf -q "mochitest-chrome"
220 # adds tasks to the perf preset interactively
221 $ mach try fuzzy --preset perf -i
223 Similarly, ``-x/--and`` can be used to filter down a preset by taking the intersection of the two
226 .. code-block:: shell
228 # limits perf tasks to windows only
229 $ mach try fuzzy --preset perf -xq "windows"
231 # limits perf tasks interactively
232 $ mach try fuzzy --preset perf -xi
238 Unfortunately ``fzf``'s query language uses some characters (namely ``'``, ``!`` and ``$``) that can
239 interfere with your shell when using ``-q/--query``. Below are some tips for how to type out a query
242 The ``!`` character is typically used for history expansion. If you don't use this feature, the
243 easiest way to specify queries on the command line is to disable it:
245 .. code-block:: shell
249 $ ./mach try fuzzy -q "'foo !bar"
253 $ ./mach try fuzzy -q "'foo !bar"
255 If using ``bash``, add ``set +H`` to your ``~/.bashrc``, ``~/.bash_profile`` or equivalent. If using
256 ``zsh``, add ``setopt no_banghist`` to your ``~/.zshrc`` or equivalent.
258 If you don't want to disable history expansion, you can escape your queries like this:
260 .. code-block:: shell
263 $ ./mach try fuzzy -q $'\'foo !bar'
266 $ ./mach try fuzzy -q "'foo \!bar"
269 The third option is to use ``-e/--exact`` which reverses the behaviour of the ``'`` character (see
270 :ref:`additional-arguments` for more details). Using this flag means you won't need to escape the
271 ``'`` character as often and allows you to run your queries like this:
273 .. code-block:: shell
276 $ ./mach try fuzzy -eq 'foo !bar'
278 This method is only useful if you find you almost always prefix terms with ``'`` (and rarely use
279 fuzzy terms). Otherwise as soon as you want to use a fuzzy match you'll run into the same problem as
282 .. note:: All the examples in these three approaches will select the same set of tasks.
284 If you use ``fish`` shell, you won't need to escape ``!``, however you will need to escape ``$``:
286 .. code-block:: shell
289 $ ./mach try fuzzy -q "'foo !bar baz\$"
295 One or more paths to a file or directory may be specified as positional arguments. When
296 specifying paths, the list of available tasks to choose from is filtered down such that
297 only suites that have tests in a specified path can be selected. Notably, only the first
298 chunk of each suite/platform appears. When the tasks are scheduled, only tests that live
299 under one of the specified paths will be run.
303 When using paths, be aware that all tests under the specified paths will run in the
304 same chunk. This might produce a different ordering from what gets run on production
305 branches, and may yield different results.
307 For suites that restart the browser between each manifest (like mochitest), this
308 shouldn't be as big of a concern.
310 Paths can be used with the interactive ``fzf`` window, or using the ``-q/--query`` argument.
311 For example, running:
313 .. code-block:: shell
315 $ mach try fuzzy layout/reftests/reftest-sanity -q "!pgo !cov !asan 'linux64"
317 Would produce the following ``try_task_config.json``:
323 "MOZHARNESS_TEST_PATHS":"{\"reftest\":\"layout/reftests/reftest-sanity\"}"
326 "test-linux64-qr/debug-reftest-e10s-1",
327 "test-linux64-qr/opt-reftest-e10s-1",
328 "test-linux64/debug-reftest-e10s-1",
329 "test-linux64/debug-reftest-no-accel-e10s-1",
330 "test-linux64/opt-reftest-e10s-1",
331 "test-linux64/opt-reftest-no-accel-e10s-1",
335 Inside of these tasks, the reftest harness will only run tests that live under
336 ``layout/reftests/reftest-sanity``.
339 .. _additional-arguments:
344 There are a few additional command line arguments you may wish to use:
347 By default, ``fzf`` treats terms as a fuzzy match and prefixing a term with ``'`` turns it into an exact
348 match. If passing in ``--exact``, this behaviour is reversed. Non-prefixed terms become exact, and a
349 ``'`` prefix makes a term fuzzy.
352 By default, only target tasks (e.g tasks that would normally run on mozilla-central)
353 are generated. Passing in ``--full`` allows you to select from all tasks. This is useful for
354 things like nightly or release tasks.
357 Update the bootstrapped ``fzf`` binary to the latest version.
359 For a full list of command line arguments, run:
361 .. code-block:: shell
363 $ mach try fuzzy --help
365 For more information on using ``fzf``, run:
367 .. code-block:: shell
371 .. _fzf: https://github.com/junegunn/fzf