diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua
index f37aefd70..a10fbf7e7 100644
--- a/lib/beautiful/init.lua
+++ b/lib/beautiful/init.lua
@@ -180,28 +180,57 @@ function beautiful.get_font_height(name)
     return load_font(name).height
 end
 
---- Init function, should be run at the beginning of configuration file.
+--- Function that initializes the theme settings. Should be run at the
+-- beginning of the awesome configuration file (normally rc.lua).
+--
+-- Example usages:
+--
+--    -- Using a table
+--    beautiful.init({font = 'Monospace Bold 10'})
+--
+--    -- From a config file
+--    beautiful.init("<path>/theme.lua")
+--
+-- Example "<path>/theme.lua" (see `05-awesomerc.md:Variable_definitions`):
+--
+--    theme = {}
+--        theme.font = 'Monospace Bold 10'
+--    return theme
+--
+-- Example using the return value:
+--
+--    local beautiful = require("beautiful")
+--    if not beautiful.init("<path>/theme.lua") then
+--        beautiful.init("<path>/.last.theme.lua") -- a known good fallback
+--    end
+--
 -- @tparam string|table config The theme to load. It can be either the path to
---   the theme file (returning a table) or directly the table
+--   the theme file (which should return a table) or directly a table
 --   containing all the theme values.
+-- @treturn true|nil True if successful, nil in case of error.
 function beautiful.init(config)
     if config then
+        local state, t_theme = nil, nil
         local homedir = os.getenv("HOME")
 
         -- If `config` is the path to a theme file, run this file,
         -- otherwise if it is a theme table, save it.
-        if type(config) == 'string' then
+        local t_config = type(config)
+        if t_config == 'string' then
             -- Expand the '~' $HOME shortcut
             config = config:gsub("^~/", homedir .. "/")
             local dir = Gio.File.new_for_path(config):get_parent()
             rawset(beautiful, "theme_path", dir and (dir:get_path().."/") or nil)
             theme = protected_call(dofile, config)
-        elseif type(config) == 'table' then
+            t_theme = type(theme)
+            state = t_theme == 'table' and next(theme)
+        elseif t_config == 'table' then
             rawset(beautiful, "theme_path", nil)
             theme = config
+            state = next(theme)
         end
 
-        if theme then
+        if state then
             -- expand '~'
             if homedir then
                 for k, v in pairs(theme) do
@@ -210,9 +239,16 @@ function beautiful.init(config)
             end
 
             if theme.font then set_font(theme.font) end
+            return true
         else
+            rawset(beautiful, "theme_path", nil)
             theme = {}
-            return gears_debug.print_error("beautiful: error loading theme file " .. config)
+            local file = t_config == 'string' and (" from: " .. config)
+            local err = (file and t_theme == 'table' and "got an empty table" .. file)
+                     or (file and t_theme ~= 'table' and "got a " .. t_theme .. file)
+                     or (t_config == 'table' and "got an empty table")
+                     or ("got a " .. t_config)
+            return gears_debug.print_error("beautiful: error loading theme: " .. err)
         end
     else
         return gears_debug.print_error("beautiful: error loading theme: no theme specified")
diff --git a/spec/beautiful/init_spec.lua b/spec/beautiful/init_spec.lua
new file mode 100644
index 000000000..e8693f4b2
--- /dev/null
+++ b/spec/beautiful/init_spec.lua
@@ -0,0 +1,80 @@
+---------------------------------------------------------------------------
+-- @author
+-- @copyright 2019
+---------------------------------------------------------------------------
+
+local beautiful = require("beautiful")
+local gdebug = require("gears.debug")
+
+describe("beautiful init", function()
+    local dir = (os.getenv("SOURCE_DIRECTORY") or '.') .. "/spec/beautiful/tests/"
+    local shim
+
+    -- Check beautiful.get_font and get_merged_font
+    it('Check beautiful.get_font', function()
+        assert.is_same(beautiful.get_font("Monospace Bold 12"),
+            beautiful.get_merged_font("Monospace 12", "Bold"))
+    end)
+
+    -- Check beautiful.get_font_height
+    it('Check beautiful.get_font_height', function()
+        -- TODO: Will requires lgi-dpi
+    end)
+
+    -- Check beautiful.init
+    it('Check beautiful.init', function()
+        -- Check the error messages (needs a shim)
+        shim = gdebug.print_error
+        gdebug.print_error = function(message) error(message) end
+
+        assert.has_error(function() beautiful.init({}) end,
+            "beautiful: error loading theme: got an empty table")
+        assert.has_error(function() beautiful.init(dir .. "Bad_1.lua") end,
+            "beautiful: error loading theme: got an empty table from: " .. dir .. "Bad_1.lua")
+        assert.has_error(function() beautiful.init(dir .. "Bad_2.lua") end,
+            "beautiful: error loading theme: got a function from: " .. dir .. "Bad_2.lua")
+        assert.has_error(function() beautiful.init(dir .. "Bad_3.lua") end,
+            "beautiful: error loading theme: got a number from: " .. dir .. "Bad_3.lua")
+        assert.has_error(function() beautiful.init(dir .. "Bad_4.lua") end,
+            "beautiful: error loading theme: got a nil from: " .. dir .. "Bad_4.lua")
+        assert.has_error(function() beautiful.init(dir .. "Bad_5.lua") end,
+            "beautiful: error loading theme: got a nil from: " .. dir .. "Bad_5.lua")
+        assert.has_error(function() beautiful.init(dir .. "NO_FILE") end,
+            "beautiful: error loading theme: got a nil from: " .. dir .. "NO_FILE")
+
+        assert.has_no_error(function() beautiful.init({ font = "Monospace Bold 12" }) end, "")
+        assert.has_no_error(function() beautiful.init(dir .. "Good.lua") end, "")
+
+        -- Check the return values (remove the shim)
+        gdebug.print_error = shim
+
+        assert.is_nil(beautiful.init({}))
+        assert.is_nil(beautiful.init(dir .. "Bad_1.lua"))
+        assert.is_nil(beautiful.init(dir .. "Bad_2.lua"))
+        assert.is_nil(beautiful.init(dir .. "Bad_3.lua"))
+        assert.is_nil(beautiful.init(dir .. "Bad_4.lua"))
+        assert.is_nil(beautiful.init(dir .. "Bad_5.lua"))
+        assert.is_nil(beautiful.init(dir .. "NO_FILE"))
+
+        assert.is_true(beautiful.init({ font = "Monospace Bold 12" }))
+        assert.is_true(beautiful.init(dir .. "Good.lua"))
+    end)
+
+    -- Check beautiful.get
+    it('Check beautiful.get', function()
+        assert.is_same(beautiful.get(), { font = "Monospace Bold 12" })
+    end)
+
+    -- Check getting a beautiful.value
+    it('Check getting a beautiful.value', function()
+        assert.is_same(beautiful.font, "Monospace Bold 12")
+    end)
+
+    -- Check setting a beautiful.value
+    it('Check setting a beautiful.value', function()
+        beautiful.font = "Monospace Bold 10"
+        assert.is_same(beautiful.font, "Monospace Bold 10")
+    end)
+end)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/spec/beautiful/tests/Bad_1.lua b/spec/beautiful/tests/Bad_1.lua
new file mode 100644
index 000000000..99a91bf51
--- /dev/null
+++ b/spec/beautiful/tests/Bad_1.lua
@@ -0,0 +1,2 @@
+local me = {}
+return me
diff --git a/spec/beautiful/tests/Bad_2.lua b/spec/beautiful/tests/Bad_2.lua
new file mode 100644
index 000000000..bf91e6304
--- /dev/null
+++ b/spec/beautiful/tests/Bad_2.lua
@@ -0,0 +1,2 @@
+local me = function() end
+return me
diff --git a/spec/beautiful/tests/Bad_3.lua b/spec/beautiful/tests/Bad_3.lua
new file mode 100644
index 000000000..304bb6f51
--- /dev/null
+++ b/spec/beautiful/tests/Bad_3.lua
@@ -0,0 +1,2 @@
+local me = 9
+return me
diff --git a/spec/beautiful/tests/Bad_4.lua b/spec/beautiful/tests/Bad_4.lua
new file mode 100644
index 000000000..5ff5129dd
--- /dev/null
+++ b/spec/beautiful/tests/Bad_4.lua
@@ -0,0 +1,2 @@
+local me = nil
+return me
diff --git a/spec/beautiful/tests/Bad_5.lua b/spec/beautiful/tests/Bad_5.lua
new file mode 100644
index 000000000..bd50202fd
--- /dev/null
+++ b/spec/beautiful/tests/Bad_5.lua
@@ -0,0 +1,2 @@
+local var = nil
+print( var.bad )
diff --git a/spec/beautiful/tests/Good.lua b/spec/beautiful/tests/Good.lua
new file mode 100644
index 000000000..dd8f20492
--- /dev/null
+++ b/spec/beautiful/tests/Good.lua
@@ -0,0 +1,2 @@
+local me = { font = "Monospace Bold 12" }
+return me
diff --git a/spec/preload.lua b/spec/preload.lua
index 864e38bdd..dc635ee30 100644
--- a/spec/preload.lua
+++ b/spec/preload.lua
@@ -7,6 +7,6 @@ require("lgi")
 _G.awesome = {version = "v9999"}
 
 -- "fix" some intentional beautiful breakage done by .travis.yml
-require("beautiful").init{}
+require("beautiful").init{a_key="a_value"}
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80