Doctests with PIDs in output from iex

Hey everybody! I’m coming back at Elixir again after maybe a year of not being able to jump into my web development hobby. I wanted to get back into Elixir from the ground floor again so I’ve been relearning this last week. I jumped into this starter project from Jose

https://howistart.org/posts/elixir/1/

And one of the things he mentions is creating docs and doctests. So I have been. I ran into one issue though and can’t find an answer anywhere. And that is when trying to test a function that has a Tuple with an atom and PID as the output. For example with creating an Agent:

iex> {:ok, pid} = Agent.start_link(fn -> [] end)
{:ok, #PID<0.106.0>}

as a part of the document to be tested with doctest. With the function transfer in the example in the introduction I created a doc like so:

  @doc """
  Starts transferring `data` from `left` to `right`.

  ## Parameters

  - `left` - A portal shot with Portal.shoot/1
  - `right` - Another portal shot with Portal.shoot/1
  - `data` - An enumerable type of data

  ## Examples

      iex> Portal.shoot(:red)
      {:ok, pid}
      iex> Portal.shoot(:green)
      {:ok, pid}
      iex> portal = Portal.transfer(:red, :green, [1,2,3])
      #Portal<
             :red <=> :green
        [1, 2, 3] <=> []
      >
      iex> portal
      #Portal<
             :red <=> :green
        [1, 2, 3] <=> []
      >
  """

If I remove the {:ok, pid} for example, it compares the wrong things in the doctest:

  1) doctest Portal.transfer/3 (1) (PortalTest)
     test/portal_test.exs:3
     Doctest failed
     doctest:
       iex> Portal.shoot(:red)
       iex> Portal.shoot(:green)
       iex> portal = Portal.transfer(:red, :green, [1,2,3])
       "#Portal<\n       :red <=> :green\n  [1, 2, 3] <=> []\n>"
     code:  inspect(portal = Portal.transfer(:red, :green, [1, 2, 3])) === "#Portal<\n       :red <=> :green\n  [1, 2, 3] <=> []\n>"
     left:  "#Portal<\n       :red <=> :green\n  [1, 2, 3] <=> []\n>\n"
     right: "#Portal<\n       :red <=> :green\n  [1, 2, 3] <=> []\n>"
     stacktrace:
       lib/portal.ex:19: Portal (module)

Thoughts? Workarounds?

There’s documentation about it: https://hexdocs.pm/ex_unit/ExUnit.DocTest.html#module-opaque-types

I couldn’t find an official “don’t put a newline at the end of your inspect output” in the docs, but note that the examples for Kernel.inspect/2 don’t, even in the case when there are embedded newlines in the result.

1 Like

I did look at that, but it doesn’t seem to help the issue. If anything, it might fall under “when not to use doctest”? Which kind of sucks but perhaps it has to be done.

I don’t think either of those 2 solutions they provide don’t work, since I don’t have a # at the beginning of the output, and the second scenario doesn’t seem to work either…am I missing something?

That’s another thing I was trying to solve…and adding a newline or a \n seems to break the test

Okay, I had a friend help me out. And it was pretty relevant to what @al2o3cr was saying about the newline being added. In the project, you are asked to output to a heredoc to get the output shown. The code was originally this:

    """
    #Portal<
      #{String.pad_leading(left_door, max)} <=> #{right_door}
      #{String.pad_leading(left_data, max)} <=> #{right_data}
    >
    """

And he wrapped it with String.trim which removed the newline escape character. So the change to the code itself was:

    String.trim("""
    #Portal<
      #{String.pad_leading(left_door, max)} <=> #{right_door}
      #{String.pad_leading(left_data, max)} <=> #{right_data}
    >
    """)

And the doctest example being

  ## Examples

      iex> Portal.shoot(:red)
      iex> Portal.shoot(:green)     
      iex> portal = Portal.transfer(:red, :green, [1,2,3])
      #Portal<
             :red <=> :green
        [1, 2, 3] <=> []
      >
      iex> portal
      #Portal<
             :red <=> :green
        [1, 2, 3] <=> []
      >
  """

Noting the removal of {:ok, pid} after the iex prompts that run Portal.shoot(color)