Add pseudo-integration tests that verify the module content in the output

Author: Marek Suchánek

data/generated/assembly_testing-that-an-assembly-forms-properly.adoc

@@ -0,0 +1,77 @@
+////
+Retains the context of the parent assembly if this assembly is nested within another assembly.
+For more information about nesting assemblies, see: https://redhat-documentation.github.io/modular-docs/#nesting-assemblies
+See also the complementary step on the last line of this file.
+////
+
+ifdef::context[:parent-context-of-assembly_testing-that-an-assembly-forms-properly: {context}]
+
+////
+Base the file name and the ID on the assembly title. For example:
+* file name: assembly-my-user-story.adoc
+* ID: [id="assembly-my-user-story_{context}"]
+* Title: = My user story
+
+The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken. Include {context} in the ID so the assembly can be reused.
+////
+
+ifndef::context[]
+[id="assembly_testing-that-an-assembly-forms-properly"]
+endif::[]
+ifdef::context[]
+[id="assembly_testing-that-an-assembly-forms-properly_{context}"]
+endif::[]
+= Testing that an assembly forms properly
+////
+If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
+////
+
+:context: assembly_testing-that-an-assembly-forms-properly
+
+////
+The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+////
+
+[role="_abstract"]
+This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. The text that immediately follows the `[role="_abstract"]` tag is used for search metadata.
+
+== Prerequisites
+
+* A bulleted list of conditions that must be satisfied before the user starts following this assembly.
+* You can also link to other modules or assemblies the user must follow before starting this assembly.
+* Delete the section title and bullets if the assembly has no prerequisites.
+* X is installed. For information about installing X, see <link>.
+* You can log in to X with administrator privileges.
+
+////
+The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies.
+
+include::modules/TEMPLATE_CONCEPT_explaining_a_concept.adoc[leveloffset=+1]
+////
+
+Include modules here.
+
+////
+[leveloffset=+1] ensures that when a module title is a level 1 heading (= Title), the heading will be interpreted as a level-2 heading (== Title) in the assembly. Use [leveloffset=+2] and [leveloffset=+3] to nest modules in an assembly.
+
+include::modules/TEMPLATE_PROCEDURE_doing_one_procedure.adoc[leveloffset=+2]
+
+include::modules/TEMPLATE_PROCEDURE_reference-material.adoc[leveloffset=2]
+////
+
+[role="_additional-resources"]
+== Additional resources (or Next steps)
+////
+Optional. Delete if not used.
+////
+
+* A bulleted list of links to other material closely related to the contents of the assembly, including xref links to other assemblies in your collection.
+* For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+
+////
+Restore the context to what it was before this assembly.
+////
+ifdef::parent-context-of-assembly_testing-that-an-assembly-forms-properly[:context: {parent-context-of-assembly_testing-that-an-assembly-forms-properly}]
+ifndef::parent-context-of-assembly_testing-that-an-assembly-forms-properly[:!context:]
+

data/generated/con_a-title-that-tests-a-concept.adoc

@@ -0,0 +1,38 @@
+////
+Base the file name and the ID on the module title. For example:
+* file name: con-my-concept-module-a.adoc
+* ID: [id="con-my-concept-module-a_{context}"]
+* Title: = My concept module A
+////
+
+////
+The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
+
+The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+////
+
+[id="con_a-title-that-tests-a-concept_{context}"]
+= A title that tests a concept
+////
+In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly. Do not start the title of concept modules with a verb. See also _Wording of headings_ in _The IBM Style Guide_.
+////
+
+[role="_abstract"]
+Write a short introductory paragraph that provides an overview of the module. The text that immediately follows the `[role="_abstract"]` tag is used for search metadata.
+
+The contents of a concept module give the user descriptions and explanations needed to understand and use a product.
+
+* Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
+* Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.
+* Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.
+
+[role="_additional-resources"]
+.Additional resources
+////
+Optional. Delete if not used.
+////
+* A bulleted list of links to other material closely related to the contents of the concept module.
+* Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
+* For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+

data/generated/proc_testing-a-procedure.adoc

@@ -0,0 +1,58 @@
+////
+Base the file name and the ID on the module title. For example:
+* file name: proc-doing-procedure-a.adoc
+* ID: [id="doing-procedure-a_{context}"]
+* Title: = Doing procedure A
+
+The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
+
+The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
+////
+
+[id="proc_testing-a-procedure_{context}"]
+= Testing a procedure
+////
+Start the title of a procedure module with a verb, such as Creating or Create. See also _Wording of headings_ in _The IBM Style Guide_.
+////
+
+[role="_abstract"]
+Write a short introductory paragraph that provides an overview of the module. Procedure modules should include  the steps that users perform and address user motivation.The text that immediately follows the `[role="_abstract"]` tag is used for search metadata.
+
+.Prerequisites
+
+* A bulleted list of conditions that must be satisfied before the user starts following this module.
+* You can also link to other modules or assemblies the user must follow before starting this module.
+* Delete the section title and bullets if the module has no prerequisites.
+
+.Procedure
+
+. Start each step with an active verb.
+
+. Include one command or action for each step with the exception of simple follow-step, for example:
+.. Do this thing and then select *Next*.
+.. Do this other thing and then select *Next*.
+
+. Use an unnumbered bullet (*) if the procedure includes only one step.
+
+.Verification
+////
+Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure.
+////
+
+. Start each step with an active verb.
+
+. Include one command or action per step.
+
+. Use an unnumbered bullet (*) if the procedure includes only one step.
+
+
+[role="_additional-resources"]
+.Additional resources
+////
+Optional. Delete if not used.
+////
+* A bulleted list of links to other material closely related to the contents of the procedure module.
+* Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
+* For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+

data/generated/ref_the-lines-in-a-reference-module.adoc

@@ -0,0 +1,50 @@
+////
+Base the file name and the ID on the module title. For example:
+* file name: ref-my-reference-a.adoc
+* ID: [id="ref-my-reference-a_{context}"]
+* Title: = My reference A
+
+The ID is an anchor that links to the module. Avoid changing it after the module has been published to ensure existing links are not broken.
+
+The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
+////
+
+[id="ref_the-lines-in-a-reference-module_{context}"]
+= The lines in a reference module
+////
+In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly.
+////
+
+[role="_abstract"]
+Write a short introductory paragraph that provides an overview of the module. The text that immediately follows the `[role="_abstract"]` tag is used for search metadata. A reference module provides data that users might want to look up, but do not need to remember.
+It has a very strict structure, often in the form of a list or a table.
+A well-organized reference module enables users to scan it quickly to find the details they want.
+AsciiDoc markup to consider for reference data:
+
+.Unordered list
+* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles.
+For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+
+.Labeled list
+Term 1:: Definition
+Term 2:: Definition
+
+.Table
+[options="header"]
+|====
+|Column 1|Column 2|Column 3
+|Row 1, column 1|Row 1, column 2|Row 1, column 3
+|Row 2, column 1|Row 2, column 2|Row 2, column 3
+|====
+
+[role="_additional-resources"]
+.Additional resources
+////
+Optional. Delete if not used.
+////
+* A bulleted list of links to other material closely related to the contents of the concept module.
+* Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
+* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+

src/main.rs

@@ -106,3 +106,76 @@ fn process_module_type(
 
     modules_from_type
 }
+
+
+// These tests act as pseudo-integration tests. They let the top-level functions generate
+// each module type and then they compare the generated content with a pre-generated specimen
+// to check that we introduce no changes unknowingly.
+#[cfg(test)]
+mod tests {
+    use crate::module::Module;
+    use crate::module::ModuleType;
+    use crate::Options;
+
+    fn basic_options() -> Options {
+        Options {
+            comments: true,
+            prefixes: true,
+            examples: true,
+            target_dir: ".".to_string(),
+            detect_directory: false,
+        }
+    }
+
+    /// Test that we generate the assembly that we expect.
+    #[test]
+    fn test_assembly() {
+        let mod_type = ModuleType::Assembly;
+        let mod_title = "Testing that an assembly forms properly";
+        let options = basic_options();
+        let assembly = Module::new(mod_type, mod_title, &options);
+
+        let pre_generated = include_str!("../data/generated/assembly_testing-that-an-assembly-forms-properly.adoc");
+
+        assert_eq!(assembly.text, pre_generated);
+    }
+
+    /// Test that we generate the concept module that we expect.
+    #[test]
+    fn test_concept_module() {
+        let mod_type = ModuleType::Concept;
+        let mod_title = "A title that tests a concept";
+        let options = basic_options();
+        let concept = Module::new(mod_type, mod_title, &options);
+
+        let pre_generated = include_str!("../data/generated/con_a-title-that-tests-a-concept.adoc");
+
+        assert_eq!(concept.text, pre_generated);
+    }
+
+    /// Test that we generate the procedure module that we expect.
+    #[test]
+    fn test_procedure_module() {
+        let mod_type = ModuleType::Procedure;
+        let mod_title = "Testing a procedure";
+        let options = basic_options();
+        let procedure = Module::new(mod_type, mod_title, &options);
+
+        let pre_generated = include_str!("../data/generated/proc_testing-a-procedure.adoc");
+
+        assert_eq!(procedure.text, pre_generated);
+    }
+
+    /// Test that we generate the reference module that we expect.
+    #[test]
+    fn test_reference_module() {
+        let mod_type = ModuleType::Reference;
+        let mod_title = "The lines in a reference module";
+        let options = basic_options();
+        let reference = Module::new(mod_type, mod_title, &options);
+
+        let pre_generated = include_str!("../data/generated/ref_the-lines-in-a-reference-module.adoc");
+
+        assert_eq!(reference.text, pre_generated);
+    }
+}