# Testing `Masu.Test` reads and queries the grids of a LiveView in `Phoenix.LiveViewTest`, with no browser. ```elixir import Masu.Test test "finds the late orders", %{conn: conn} do {:ok, view, _html} = live(conn, ~p"/orders") assert total(view, "orders") == 120 view |> filter("orders", [{"status", :eq, "late"}]) |> sort("orders", {"total", :desc}) assert [%{"number" => "A-1042", "total" => "250.50"} | _] = rows(view, "orders") end ``` The functions send the events that the browser sends, so the grid applies a sort, a filter or a search as it does for a person: the source sorts, filters and counts (in the database, for an Ecto source), and `rows/3` reads the rows it gives. ## Reading * `rows(view, id, from: 0, count: 100)`: the rows, in order. A row is a map of each column's key to its value as the browser gets it: numbers and booleans as they are, decimals as strings, dates and times in ISO 8601, and for a column of your own HEEx the text of its cell. * `ids(view, id)`: the ids of the rows. * `total(view, id)`: how many rows the query has. * `columns(view, id)`: the labels, in order. * `values(view, id, key, search: nil)`: what the column's filter menu offers, as `{value, count}`, the most frequent first. * `place(view, id, row_id)`: where the row is in the grid's order (from 0), or `nil` when its filters leave it out: what a person who follows someone scrolls to. ## Editing * `edit(view, id, edits, opts \\ [])`: edits cells as a person does, with a list of `{row_id, key, value}` (the value as the browser sends it: a string, or `nil` to empty the cell). Gives `:ok`, `:async` (your `on_update` saves them later), or `{:error, errors}` with `{row_id, key, message}` for each cell that was not saved. An edit `{row_id, key, value, before}` carries the value the person saw, and is refused when the cell changed meanwhile. `origin: :paste` (`:fill`, `:undo`...) is what your `on_update` sees as the write's `origin`; `:test` unless given. ## Querying Each returns the view, so they pipe: * `sort(view, id, sorts)`: a key, `{key, :asc | :desc}`, or a list of them, the first the most important. `[]` takes the order away. * `filter(view, id, filters)`: a list of `{key, op, value}`, which replaces the grid's filters. See `Masu.Filter` for the operators. * `search(view, id, text)`: as the search box. A column of a related row's field is named by its key, the path with dots unless it has its own, and its rows' values are lists for a column of many values: ```elixir view |> sort("orders", {"customer.name", :desc}) |> filter("orders", [{"tags", :all_of, ["gift", "urgent"]}]) assert [%{"customer.name" => "Ana", "tags" => ["gift", "urgent"]} | _] = rows(view, "orders") ``` A query that the grid refuses (a filter on a column that does not filter, a value that is not of the column's type) fails the test with the grid's reason. ## Layout and views * `layout(view, id, changes)`: moves, hides, pins and resizes columns, as the columns menu and the headers do: `order: keys`, `hidden: keys`, `pinned: %{key => :start | :end}`, `widths: %{key => pixels}`. * `view(view, id)`: the grid's view, as its params (`%{}` is the grid's own view; see `Masu.View`). * `apply_view(view, id, params)`: applies a view, as a link or a saved view does; gives the keys of the parts that no longer apply. `columns/2` and `rows/3` read the columns that show, in their order. ## Groups and totals * `group(view, id, keys)`: groups by columns, as the header menu does; `[]` stops. * `groups(view, id, opts)`: the groups' rows, as maps of `:id`, `:key`, `:value`, `:count`, `:level`, `:expanded` and `:totals`. * `totals(view, id)`: the row of totals, by column key. ## Counts and pages * `count(view, id)`: `{:exact, n}`, or `{:at_least, n}` while the grid does not know its count; `total/2` gives `n`. * `ask_count(view, id)`: asks for the count, as Ctrl+End does. * `page(view, id, page)`: goes to a page (from 1) of a grid with `paging={:pages}`, and gives the ids of its rows. An editor of yours that is a form: `open_editor(view, id, row_id, key)` renders it, which `render/1` then has, and `close_editor(view, id)` closes it; `edit/4` saves what it would post (text, or a map of params: `%{"from" => ..., "to" => ...}`). See [Editors of your own](editors.md). ## New and deleted rows * `add_rows(view, id, rows, opts \\ [])`: adds rows as "+ New row" does, each a map of column keys to values; `{:ok, ids}`, or `{:error, results}`. * `delete_rows(view, id, ids_or_selection, opts \\ [])` and `restore_rows(view, id, undo)`: deletes rows (or `:selection`), and brings them back; `:async` when your `on_delete` deletes them later. A write saved later (`Masu.Write.async/1`) waits for its reply: the job your function started calls `Masu.reply/2` (with Oban's testing mode, run it with `perform_job/2`), and `Phoenix.LiveViewTest.assert_push_event/3` sees the grid's `"masu:reply"`. ## Export and selection * `export(view, id, format, opts \\ [])`: exports as the Export menu does, downloads the file through your router's export route, and gives it, `{name, binary}`; `conn:` a conn with what the route's pipeline wants (a signed-in user). * `export_url(view, id, format)`: the link the browser would get, to test the route itself (that it refuses a person who is not signed in). * `select(view, id, ids, on \\ true)`, `select_all(view, id, on \\ true)` and `selection(view, id)`. ## Trees and details * `nodes(view, id, opts)`: the rows of a tree, as maps of `:id`, `:level`, `:children` and `:expanded`. * `expand(view, id, row_id)`, `collapse(view, id, row_id)` and `expand_siblings(view, id, row_id)`: as the arrows and `*`. * `detail(view, id, row_id, open \\ true)`: opens a row's detail, which `render/1` then has; a grid in it is read with its own id. ## History * `history(view, id, row_id, key \\ nil)`: the history of a cell, or of a row, newest first, as maps of `:id`, `:key`, `:op`, `:before`, `:after`, `:user`, `:origin`, `:batch`, `:batch_size` and `:at`. * `restore(view, id, entry_id)`, or `restore(view, id, {:batch, batch})`: brings a value (or a batch) back as Restore and Undo all do; `{:ok, count}` or `{:error, errors}`. See [History](history.md). ## Actions * `actions(view, id, :selection)`: the labels of the actions on the rows selected (none while no row is); `actions(view, id, :row, row_id)`: those a row shows, available or not. * `action(view, id, label)` and `row_action(view, id, label, row_id)`: run one as the browser does, past its question; `:ok`, `{:ok, message}`, `{:error, message}`, `:async`, a link's `{:navigate, path}` or `{:patch, path}`, or `{:error, :refused}` when the server refuses it (not offered, hidden or disabled for the row, no row selected). See [Actions](actions.md). * `activate_row(view, id, row_id)`: opens a row as a click on it or Enter does (`on_row_activate`); `:ok`, the `{:patch, path}` or `{:navigate, path}` the grid follows, or `{:error, :refused}` (no `on_row_activate`, no such row). ## Menus of your own * `actions(view, id, :header | :cell, key)`: the labels of the items the grid offers for a column. * `header_action(view, id, label, key)` and `cell_action(view, id, label, key, row_id, opts)`: run an item, as a click on it does; its panel is then in `render/1`. `close_panel(view, id)` closes it. See [Menus of your own](menus.md). ## Slow sources and controlled grids The helpers wait for a grid's tasks (`load={:async}`), as the browser does, and fail with the grid's error when a read fails: a test reads the same either way. In a controlled grid (`on_query`), a sort or a filter reaches the LiveView, which runs its query: `render_async/1` waits for a query that it runs in a task, before the rows are read. ## What these tests do not cover `Masu.Test` does not run the browser: the drawing of the rows, the keyboard, the selection and the clipboard are tested by Masu's own browser tests.