diff --git a/docs/users-guide/README.md b/docs/users-guide/README.md index 58ab72d1d..090f2aee9 100644 --- a/docs/users-guide/README.md +++ b/docs/users-guide/README.md @@ -1,11 +1,14 @@ # Morphir Users' Guide -Morphir's core purpose is to collect and store the vital business logic of an application. To fulfull that goal, -Morphir provides tools to write business logic, visualize and interac with it, and use it to generate useful things. + +Morphir's core purpose is to collect and store the vital business logic of an application. To fulfill that goal, +Morphir provides tools to write business logic, visualize and interact with it, and use it to generate useful things. ## Who this Guide Designed For + This guide is for business users, analysts, and developers who want to use Morphir to tap the potential in their business logic. ## Content + 1. [Getting Setup](#) 1. [Installation](installation.md) 1. [Editor Setup](editor_setup.md) diff --git a/docs/users-guide/command_line_tools.md b/docs/users-guide/command_line_tools.md index b11b69910..0793d6ba7 100644 --- a/docs/users-guide/command_line_tools.md +++ b/docs/users-guide/command_line_tools.md @@ -1,17 +1,24 @@ # Morphir Command Line Tools +At the moment, Morphir provides two CLI programs that provide the tools that morphir offers, `morphir-elm` and `morphir`. +`morphir-elm` is the first program created and may be deprecated in the future, so we advise that you use `morphir` whenever possible and only use `morphir-elm` if the feature you intend to use isn't currently available in `morphir`. + ## Compile (Elm) + Morphir revolves around the Intermediate Representation (IR), which is the data format for storing logic. -Morphir users compile their business logic into the IR using morphir's compiler tools. For Elm-authored logic, +Morphir users compile their business logic into the IR using morphir's compiler tools. For Elm-authored logic, is done through the following: ```shell morphir-elm make +moprhir make ``` Options include: + ```shell Usage: morphir-elm make [options] +Usage: morphir make [options] Translate Elm sources to Morphir IR @@ -19,18 +26,20 @@ Options: -p, --project-dir Root directory of the project where morphir.json is located. (default: ".") -o, --output Target file location where the Morphir IR will be saved. (default: "morphir-ir.json") -t, --types-only Only include type information in the IR, no values. (default: false) --f, --fallback-cli Full rebuild. (default: false) +-f, --fallback-cli Full rebuild. Only available for "morphir-elm make" (default: false) -h, --help display help for command ``` ## Visualize -Morphir contains tools to interact with, learn, and test Morphir applications. This can be invoked via: + +Morphir contains tools to interact with, learn, and test Morphir applications. This can be invoked via: ```shell morphir-elm develop ``` Options include: + ```shell Usage: morphir-elm develop [options] @@ -46,15 +55,17 @@ Options: Note that the default http://0.0.0.0:3000 sometimes needs to be replaced with http://localhost:3000 depending on the host environment. - ## Generate + Morphir provides tools to generate useful things from a Morphir IR. ```shell morphir-elm gen + ``` Options include: + ```shell Usage: morphir-elm gen [options] @@ -69,38 +80,62 @@ Options: ``` ### Generate Scala + ```shell morphir-elm gen -t Scala ``` Options include: + +```shell + -e, --target-version Scala language version to Generate. (default: "2.11") + -c, --copy-deps Copy the dependencies used by the generated code to the output path. (default: false) +``` + +```shell +morphir scala-gen +``` + +Options include: + ```shell + -i, --input Source location where the Morphir IR will be loaded from. (default: "morphir-ir.json") + -o, --output Target location where the generated code will be saved. (default: "./dist") -e, --target-version Scala language version to Generate. (default: "2.11") -c, --copy-deps Copy the dependencies used by the generated code to the output path. (default: false) + -m, --limitToModules Limit the set of modules that will be included. (default: '') + -s, --include-codecs Generate the scala codecs as well (default: false) + --generate-test-generic Generate generic test cases from morphir tests that can be used for testing. (default: false) + --generate-test-scalatest Generate runnable scalatest test cases (default: false) ``` ### Generate Json Schema + ```shell morphir-elm gen -t JsonSchema ``` Options include: + ```shell -s, --include-codecs Generate JSON codecs (default: false) -f, --filename Filename of the generated JSON Schema. (default: "") ``` ### Generate TypeScript + ```shell morphir-elm gen -t TypeScript ``` ### Generate Turtle for semantic web technologies + ```shell morphir-elm gen -t semantic ``` ### Generate Cypher for graph databases + ```shell morphir-elm gen -t cypher ``` diff --git a/docs/users-guide/morphir-scala-gen.md b/docs/users-guide/morphir-scala-gen.md new file mode 100644 index 000000000..a90076fd9 --- /dev/null +++ b/docs/users-guide/morphir-scala-gen.md @@ -0,0 +1,104 @@ +# Generating Scala Test Cases + +Morphir offers a way to generate scala test cases from test cases created using the morphir develop UI. + +Test cases can be generated by adding additional flags to the gen command, i.e `morphir scala-gen [test-gen-flag]`. +The gen flags for tests can be mixed together to generate different kinds of test. +Generating tests creates a sub-package called `_morphirtests`, at the package root of the generated scala, containing scala files +matching the selected kind of test(s). + +Here's what the packages look like if your Morphir project is named `**foo**` +```js +- foo/ /* package root */ + - (...) /* other sub packages and files */ + - _morphirtests/ + - [TestKind].scala /* eg: GenericTest.Scala */ +``` + +## Flags for Tests Generation + +This tooling also provides some flags to generate a runnable test suite using scala test +or just generate generic test cases. + +### Using `--generate-test-generic` + +```shell +Usage: + morphir scala-gen --generate-test-generic +``` + +This generates a scala value with a `TestCase` case class. +Example: + +```scala +/* +testInput = + { + input = "Foo", + expectedOutput = "Foo", + description = "foo description" + } +*/ + +object MorphirTests { + case class TestCase(input: Any, expectedOutput: Any, description: String) + + val testCases : List[TestCase] = List( + TestCase( + input = "Foo", + expectedOutput = "Foo", + description = "testInput test1 - foo description" + ) + ) +} + +``` + +#### Using the generated test cases + +You will need to manually write out the tests in scala and import the generated testcases + +**_example:_** + +```scala +test("morphir tests should not fail") { + val suite = MorphirTests.testCases + + suite.foreach((testcase) => { + assertResult(testcase.expectedOutput)(testcase.input) + }) +} +``` + +### Using `--generate-test-scalatest` + +```shell +Usage: + morphir scala-gen --generate-test --test-strategy=ScalaTest +``` + +This generates a complete runnable test suite that just can be run. +To create a test description, it uses + +- the fully qualified function name +- a sequential integer +- and the original description provided. + +**_example:_** + +```scala +/* +testInput = + { + input = "Foo", + expectedOutput = "Foo", + description = "foo description" + } +*/ + +class MorphirTests extends AnyFunSuite { + test("testInput test1 - foo description") { + assertResult("Foo")("Foo") + } +} +```