diff --git a/.gitignore b/.gitignore
index bc15ad2666..769ab22172 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,5 @@ nosetests.xml
 
 *~
 *.swp
+
+doc/_build
diff --git a/Makefile b/Makefile
index ad93ff037b..534cd0f086 100644
--- a/Makefile
+++ b/Makefile
@@ -6,3 +6,6 @@ notcompute.yaml: $(NOTCOMPUTE)
 overcloud.yaml: overcloud-source.yaml nova-compute-instance.yaml
 	python merge.py $< > $@.tmp
 	mv $@.tmp $@
+
+test:
+	@bash test_merge.bash
diff --git a/README.md b/README.md
index 20135527b4..97cc384e56 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,10 @@
 templates
 =========
 
-Generic templates to describe multi-host infrastructure, consumable by OpenStack Heat, Crowbar, others.
\ No newline at end of file
+Generic templates to describe multi-host infrastructure, consumable by OpenStack Heat, Crowbar, others.
+
+
+merge.py
+========
+
+The Makefile contains several targets for generated templates, see its contents for all of them. To run functional tests for merge.py, run 'make test'.
diff --git a/examples/lib.yaml b/examples/lib.yaml
new file mode 100644
index 0000000000..e527d83f3c
--- /dev/null
+++ b/examples/lib.yaml
@@ -0,0 +1,11 @@
+Parameters:
+  ImportantValue:
+  Default: a_default
+  Type: String
+Resources:
+  GenericB:
+    Type: OS::Nova::Server
+    Properties:
+      image: {Ref: BImage}
+    Metadata:
+      my_meta: {Ref: ImportantValue}
diff --git a/examples/source.yaml b/examples/source.yaml
new file mode 100644
index 0000000000..89707a7b30
--- /dev/null
+++ b/examples/source.yaml
@@ -0,0 +1,15 @@
+Parameters:
+  SourceImage:
+  Type: String
+  Default: my_image
+Resources:
+  A:
+    Type: OS::Nova::Server
+    Properties:
+      image: {Ref: SourceImage}
+  B:
+    Type: FileInclude
+    Path: examples/lib.yaml
+    SubKey: Resources.GenericB
+    Parameters:
+      ImportantValue: {'Fn::Join': [ '', ['one', 'two', 'three']]}
diff --git a/examples/source_lib_result.yaml b/examples/source_lib_result.yaml
new file mode 100644
index 0000000000..a165cabfd7
--- /dev/null
+++ b/examples/source_lib_result.yaml
@@ -0,0 +1,24 @@
+Description: examples/source.yaml
+HeatTemplateFormatVersion: '2012-12-12'
+Parameters:
+  AImage: null
+  Default: my_image
+  Type: String
+Resources:
+  A:
+    Properties:
+      image:
+        Ref: AImage
+    Type: OS::Nova::Server
+  B:
+    Metadata:
+      my_meta:
+        Fn::Join:
+        - ''
+        - - one
+          - two
+          - three
+    Properties:
+      image:
+        Ref: BImage
+    Type: OS::Nova::Server
diff --git a/test_merge.bash b/test_merge.bash
new file mode 100644
index 0000000000..35390aaaec
--- /dev/null
+++ b/test_merge.bash
@@ -0,0 +1,24 @@
+#!/bin/bash
+set -ue
+result=""
+cleanup() {
+    if [ -n "$result" ] ; then
+        rm -f $result
+    fi
+}
+trap cleanup EXIT
+result=$(mktemp /tmp/test_merge.XXXXXX)
+fail=0
+python merge.py examples/source.yaml > $result
+if ! cmp $result examples/source_lib_result.yaml ; then
+    diff -u $result examples/source_lib_result.yaml
+    echo
+    echo FAIL - merge of source.yaml result does not match expected output
+    echo
+    fail=1
+else
+    echo
+    echo PASS - merge of source.yaml result matches expected output
+    echo
+fi
+exit $fail