Artem (Artem v1.1.0) View Source

Library to help testing Absinthe graphql queries.

It has several features to aid in testing:

precompile queries during compile time
use sigils for less verbose syntax
generates functions for named graphql operations

Installation

The package can be installed by adding artem to your list of dependencies in mix.exs:

def deps do
  [
    {:artem, "~> 1.0.0"}
  ]
end

Usage

Add the Artem module with the use clause. You'll need to supply the schema: option with the Absinthe schema under test.

defmodule ArtemTest do
  use ExUnit.Case

  use Artem, schema: Your.Absinthe.Schema
end

Now you get access to the macros supplied by Artem. There are a couple of ways to use them

Sigils

The first approach is using sigils

defmodule ArtemTest do
  #...
  @version_query ~q"
    query {
      version
    }
  "
  test "run query" do
    assert {:ok, %{data: %{"version" => "201008"}}} == Artem.run(@version_query)
  end

This precompiles the document into the @version_query module attribute. If you run this document multiple times in your tests you'll only have to run the static parts (parsing/some validation) of the document once. This can also be used outside of testing, if your app relies on internal graphql queries for example.

Generated functions

The second approach builds on this but when your graphql operations are named they are compiled into functions you can call.

defmodule ArtemTest do
  #...
  ~q"
    query MyTest($format: String{
      datetime(format: $format)
    }
  "

  test "run query" do
    assert {:ok, %{data: %{"datetime" => "201008"}}} ==
            my_test(variables: %{format: "YYMMDD"}, context: %{current_user_id: 1})
  end

You can pass in the variables/context into the function.

Note that the name of the function is snake_cased from the camelized name of the operation.

precompile/2

The third way is using the precompile/2 macro

defmodule ArtemTest do
  #...
  @query precompile("
    query {
      version
    }
  ")

  test "run query" do
    assert {:ok, %{data: %{"version" => "201008"}}} == Artem.run(@query)
  end

The sigil is syntactic sugar for calling the precompile macro. You can use this for more direct control over this process, allowing easier composability.

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/artem.

Link to this section Summary

Functions

assign_context(doc, context)

Assign a context to the current query, e.g. set a current_user_id

assign_vars(doc, variables)

Assign variables to the current query, to pass them to the graphql query

default_pipeline(schema, pipeline_opts)

Default pipeline called for the schema

precompile(doc, options \\ [])

precompile/2 works the same as the sigil syntax, only slightly more verbose.

precompile(doc, schema, opts)

Macroless version of precompile/2

run(doc, options \\ [])

Run a document against the schema.

sigil_q(doc, list)

The q sigil can be used to precompile queries used in tests. It is a dynamic sigil in the sense that the resulting graphql query is run against the declared schema.

Link to this section Functions

assign_context(doc, context)

Specs

assign_context(Artem.Document.t(), map()) :: Artem.Document.t()

Assign a context to the current query, e.g. set a current_user_id

Examples

defmodule SomeTest do
  use Artem, schema: Your.Schema

  @query ~q|
    query {
      version
    }
  |

  test "runs precompiled query" do
    @query
    |> Artem.assign_context(%{current_user_id: 1})
    |> Artem.run()
  end
end

assign_vars(doc, variables)

Specs

assign_vars(Artem.Document.t(), map()) :: Artem.Document.t()

Assign variables to the current query, to pass them to the graphql query

Examples

defmodule SomeTest do
  use Artem, schema: Your.Schema

  @query ~q|
    query($format: String{
      datetime(format: $format)
    }
  |

  test "runs precompiled query" do
    @query
    |> Artem.assign_variables(%{format: "YYMMDD})
    |> Artem.run()
  end
end

default_pipeline(schema, pipeline_opts)

Specs

default_pipeline(Absinthe.Schema.t(), Keyword.t()) :: Absinthe.Pipeline.t()

Default pipeline called for the schema

Can be overridden by supplying a {module, function} tuple

  ## Examples
    defmodule SomeTest do
      use Artem, schema: Your.Schema, pipeline: {Your.Schema, :your_pipeline}

precompile(doc, options \\ [])

(macro)

precompile/2 works the same as the sigil syntax, only slightly more verbose.

Pass precompile: false to not precompile the query during compilation.
Pass generate_function: false to not create a function named after the operation name.

Examples

defmodule SomeTest do
  use Artem, schema: Your.Schema

  @query Artem.precompile("
    query {
      version
    }
  ")
end

precompile(doc, schema, opts)

Specs

precompile(any(), any(), maybe_improper_list() | %{precompile: boolean()}) ::
  Artem.Document.t()

Macroless version of precompile/2

Pass in the schema as the second argument

Examples

    defmodule SomeTest do
      @query Artem.precompile("
        query {
          version
        }
      ", Your.Schema)
    end

run(doc, options \\ [])

Specs

run(Artem.Document.t(), keyword()) :: {:error, binary()} | {:ok, any()}

Run a document against the schema.

Examples

defmodule SomeTest do
  use Artem, schema: Your.Schema

  @query ~q|
    query($format: String{
      datetime(format: $format)
    }
  |

  test "with assigned variables and context" do
    @query
    |> Artem.assign_variables(%{"format" => "YYMMDD"})
    |> Artem.assign_context(%{current_user_id: 1})
    |> Artem.run()
  end

  test "with passed in variables and context" do
    Artem.run(@query, variables: %{"format" => "YYMMDD}, context: %{current_user_id: 1})
  end
end

sigil_q(doc, list)

(macro)

The q sigil can be used to precompile queries used in tests. It is a dynamic sigil in the sense that the resulting graphql query is run against the declared schema.

Pass in the r modifier at the end of the sigil block to not precompile the query and use its 'raw' form. This will only parse the query when it is run in the tests.

Examples

defmodule SomeTest do
  use Artem, schema: Your.Schema

  @query ~q|
    query {
      version
    }
  |

  test "runs precompiled query" do
    Artem.run(@query)
  end

  @raw_query ~q|
    query {
      version
    }
  |r

  test "runs raw query" do
    Artem.run(@raw_query)
  end
end