Refine.TestHelpers (Refine v0.3.0)

Copy Markdown

Test-support helpers for applications that use Refine.

These functions are intended for use in test suites only, not in production code.

Refine keeps facet data current using database triggers, which need to see committed data. Tests that exercise incremental updates therefore run the Ecto SQL sandbox in :auto mode, where writes are committed rather than rolled back. Because nothing is rolled back, facets tables and their triggers persist between tests unless explicitly removed, and leftover triggers can fire during unrelated tests. reset_facets_artifacts/1 clears them.

Stability

These helpers discover Refine's artifacts using internal naming conventions. They automatically adapt when those conventions change. However, because they are test support functions rather than part of the core API, they may change with less notice. Any changes affecting them will be documented in the release notes.

Summary

Types

create_facets_table_return()
database_option()
database_options()
facet_config()
facet_configs()
facets_table_config()
join_config()
join_configs()
postgrex_option()
postgrex_options()
repo()

Functions

reset_facets_artifacts(opts \\ [])

Removes every facets table Refine created, along with the triggers and functions it installed on source and joined tables.

Types

create_facets_table_return()

@type create_facets_table_return() ::
  {:ok, String.t()}
  | {:error, :column_not_found, String.t()}
  | {:error, :column_names_not_unique}
  | {:error, :facets_table_exists, String.t()}
  | {:error, :identity_column_already_exists, String.t()}
  | {:error, :identity_column_invalid_type, String.t()}
  | {:error, :identity_column_not_found, String.t()}
  | {:error, :invalid_table_name, String.t()}
  | {:error, :table_names_not_unique}
  | {:error, Exception.t()}

database_option()

@type database_option() :: {:repo, repo()} | postgrex_option()

database_options()

@type database_options() :: [database_option()]

facet_config()

@type facet_config() :: %{
  facet_label: String.t() | nil,
  facet_name: String.t(),
  join_table: String.t() | nil,
  label_column: String.t() | nil,
  label_path: String.t() | nil,
  value_column: String.t() | nil,
  value_path: String.t() | nil,
  width_bucket: [integer() | float()] | nil
}

facet_configs()

@type facet_configs() :: [facet_config()]

facets_table_config()

@type facets_table_config() ::
  %{
    add_identity_column_if_not_exists: boolean() | nil,
    facets_table: String.t(),
    facets: facet_configs(),
    identity_column: String.t(),
    joins: join_configs() | nil,
    roaringbitmap_type: String.t() | nil,
    source_table: String.t()
  }
  | keyword()

join_config()

@type join_config() :: %{
  table: String.t(),
  match: String.t(),
  to: String.t(),
  on: String.t() | nil
}

join_configs()

@type join_configs() :: [join_config()]

postgrex_option()

@type postgrex_option() :: {:timeout, integer() | :infinity} | {:log, boolean()}

postgrex_options()

@type postgrex_options() :: [postgrex_option()]

repo()

@type repo() :: module()

Functions

reset_facets_artifacts(opts \\ [])

@spec reset_facets_artifacts(database_options()) :: :ok

Removes every facets table Refine created, along with the triggers and functions it installed on source and joined tables.

Intended to be called from a setup block so each test starts from a clean state, regardless of whether the previous test cleaned up after itself:

setup do
  Refine.TestHelpers.reset_facets_artifacts(repo: Repo)
  :ok
end

This removes only artifacts Refine created: facets tables, their deltas tables, and the triggers and trigger functions Refine installed.

When cleaning up your own data tables, make sure to reset the auto-incrementing identity sequence. For example:

Repo.query!(~s(
  TRUNCATE articles, categories, article_categories
  RESTART IDENTITY CASCADE
))

Options

  • :repo - the Ecto repo to run against. Defaults to the configured repo.