Merge pull request #64 from brainnco/fix/output_file_error

Fix output file error

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.10] - 2021-04-25
+
+### Fixed
+
+- Fix output documentation artifact unavailable crash message
+
 ## [0.7.9] - 2020-11-30
 
 ### Fixed

README.md

@@ -21,7 +21,7 @@ mix.exs
 ```elixir
 def deps do
   [
-    {:xcribe, "~> 0.7.9"}
+    {:xcribe, "~> 0.7.10"}
   ]
 end
 ```

lib/xcribe/cli/output.ex

@@ -32,6 +32,20 @@ defmodule Xcribe.CLI.Output do
     Enum.each(errors, &print_error/1)
   end
 
+  def print_file_errors({file_path, reason}) do
+    print_header_error("[ Xcribe ] Output file errors", @bg_red)
+
+    IO.puts("""
+    #{tab(@red)}
+    #{tab(@red)} [E] → #{@red} Could not write to #{file_path}
+    #{tab(@red)} #{space(6)} #{@red}Error: #{reason}
+    #{tab(@dark_red)}
+    #{tab(@dark_red)} #{@dark_red}The destination path for documentation artifact cannot be accessed.
+    #{tab(@dark_red)} #{@dark_red}Common reasons for this error are missing write permissions or the directory does not exist.
+    #{tab(@dark_red)}
+    """)
+  end
+
   def print_doc_exception(%DocException{
         request_error: %{__meta__: %{call: call}},
         message: msg,

lib/xcribe/formatter.ex

@@ -3,7 +3,7 @@ defmodule Xcribe.Formatter do
   An implementation of ExUnit Formatter.
 
   This module is a `GenServer` that receives ExUnits events from your test suite.
-  It handle the `suite_finished` event and then generates the documentation from
+  It handles the `suite_finished` event and then generates the documentation from
   the collected requests.
 
   You must add `Xcribe.Formatter` in the list of formatters in your `test_helper.exs`.
@@ -12,13 +12,13 @@ defmodule Xcribe.Formatter do
 
   You must keep `ExUnit.CLIFormatter` in the list as well.
 
-  The  document will be generated if the pre-configured env var has a truthy value.
+  The document will be generated if the pre-configured env var has a truthy value.
   Other wise the Formatter will ignore the finished event.
 
   All request documented with macro `document/2` (See `Xcribe`) will be parsed
   by Xcribe. When the test suite finish `Xcribe.Formatter` will check if all
-  colleted requests are valid. If some invalid request is found an error output
-  will apears and documentation will not be generated.
+  colleted requests are valid. If some invalid request is found, an error output
+  will appear and the documentation will not be generated.
   """
   use GenServer
 

lib/xcribe/writter.ex

@@ -1,6 +1,7 @@
 defmodule Xcribe.Writter do
   @moduledoc false
 
+  alias Xcribe.CLI.Output
   alias Xcribe.Config
 
   @doc """
@@ -13,11 +14,19 @@ defmodule Xcribe.Writter do
     |> Path.dirname()
     |> File.mkdir_p!()
 
-    {:ok, file} = File.open(output_file, [:write])
+    case File.open(output_file, [:write]) do
+      {:ok, file} ->
+        IO.binwrite(file, text)
 
-    IO.binwrite(file, text)
-    IO.puts("#{IO.ANSI.cyan()}> Xcribe documentation written in #{output_file}#{IO.ANSI.reset()}")
+        IO.puts(
+          "#{IO.ANSI.cyan()}> Xcribe documentation written in #{output_file}#{IO.ANSI.reset()}"
+        )
 
-    File.close(file)
+        File.close(file)
+
+      {:error, reason} ->
+        Output.print_file_errors({output_file, reason})
+        :error
+    end
   end
 end

mix.exs

@@ -1,7 +1,7 @@
 defmodule Xcribe.MixProject do
   use Mix.Project
 
-  @version "0.7.9"
+  @version "0.7.10"
   @description "A lib to generate API documentation from test specs"
   @links %{"GitHub" => "https://github.com/brainnco/xcribe"}
 

test/xcribe/cli/output_test.exs

@@ -166,6 +166,26 @@ defmodule Xcribe.CLI.OutputTest do
     end
   end
 
+  describe "print_file_errors/1" do
+    test "prints output file erro message" do
+      expected_output = """
+      \e[41m\e[37m  [ Xcribe ] Output file errors                                                                  \e[0m
+      \e[31m┃\e[0m
+      \e[31m┃\e[0m [E] → \e[31m Could not write to /some/file/path
+      \e[31m┃\e[0m        \e[31mError: eacces
+      \e[38;5;88m┃\e[0m
+      \e[38;5;88m┃\e[0m \e[38;5;88mThe destination path for documentation artifact cannot be accessed.
+      \e[38;5;88m┃\e[0m \e[38;5;88mCommon reasons for this error are missing write permissions or the directory does not exist.
+      \e[38;5;88m┃\e[0m
+
+      """
+
+      assert capture_io(fn ->
+               assert Output.print_file_errors({"/some/file/path", :eacces}) == :ok
+             end) == expected_output
+    end
+  end
+
   describe "print_doc_exception/1" do
     test "document excption" do
       message = "An exception was raised. Elixir.FunctionClauseError"

test/xcribe/writter_test.exs

@@ -0,0 +1,37 @@
+defmodule Xcribe.WritterTest do
+  use ExUnit.Case, async: false
+
+  import ExUnit.CaptureIO
+
+  alias Xcribe.Writter
+
+  setup do
+    on_exit(fn ->
+      Application.delete_env(:xcribe, :output)
+    end)
+
+    :ok
+  end
+
+  describe "write/1" do
+    test "writes given text to set output directory" do
+      output_path = "/tmp/xcribe_#{:rand.uniform()}"
+      Application.put_env(:xcribe, :output, output_path)
+
+      assert capture_io(fn ->
+               assert :ok == Writter.write("sample test")
+             end) =~ "Xcribe documentation written in #{output_path}"
+
+      assert File.read!(output_path) == "sample test"
+    end
+
+    test "raises InvalidOutputDestination if output directory cannot be accessed" do
+      invalid_output_path = "/root/null"
+      Application.put_env(:xcribe, :output, invalid_output_path)
+
+      assert capture_io(fn ->
+               assert :error == Writter.write("sample test")
+             end) =~ "Output file errors"
+    end
+  end
+end