Recent changes to Tutorial

Tutorial modified by h-hermsen

h-hermsen — Sun, 08 Aug 2021 16:30:47 -0000

Home modified by h-hermsen

h-hermsen — Sun, 08 Aug 2021 16:22:52 -0000

--- v4
+++ v5
@@ -1,57 +1,68 @@
 [[members limit=20]]

 # Quick Start
-All you need to do is to download & install the library and provide a reference of the CfUnit-library in your project. 
+All you need to do is to download & install the library and provide a reference of the co♻e-library in your project. 
 Now you are ready and you can start to write your test code! Just follow these few simple steps;

-1 `Extend CfUnit.FB_TestSuite`,
+1 `Extend CoUnit.FB_TestSuite`,
 2 Define the inputs, define the expected outputs (result),
-4 Call the CfUnit-assert methods to compare the expected output to the actual output,
+4 Call the CoUnit-assert methods to compare the expected output to the actual output,
 5 Close the test with `TEST_FINISHED()` when finished.

 # Checking test results
 The Unit testing results are viewable via the Device Log;
-Select CfUnit as Logger via the pulldown menu and press refresh, wait a few moments and the contents will be shown.
+Select co♻e as Logger via the pulldown menu and press refresh, wait a few moments and the contents will be shown.

 ![](https://forge.codesys.com/prj/cfunit/code/HEAD/tree/tags/v1.0.0.0/CfUnitVerifier.gif?format=raw)

 # Introduction user guide
-It’s highly recommended to also read unit testing concepts (google is your friend), in order to have a basic understanding of the concepts of unit testing and CfUnit. The framework gives you the possibility to easily write unit tests for your PLC software, and having the results reported in a human-readable format for review. All unit test code is written in the same program/library as the rest of your code, but because it is only used in a separate test-program, it does not affect the production code/executables. With unit test-code provided with the rest of the code, you can see these additions as living documentation of the code. For a more thorough/detailed example please see the simple programming example or the Unit Verifier. 
-
-This guide is a short tutorial in which we will go through the different steps that are necessary to use CfUnit;
-
-1. Download and install the CfUnit framework package,
+It’s highly recommended to also read unit testing concepts (google is your friend), in order to have a basic understanding of the concepts of unit testing and co♻e. 
+The framework gives you the possibility to easily write unit tests for your PLC software, and having the results reported in a human-readable format for review. 
+All unit test code is written in the same program/library as the rest of your code, but because it is only used in a separate test-program, it does not affect the production code/executables. 
+With unit test code provided with the rest of the code, you can see these additions as living documentation of the code. 
+For a more thorough/detailed example please see the simple programming example or the Unit Verifier. 
+
+This guide is a short tutorial in which we will go through the different steps that are necessary to use co♻e;
+
+1. Download and install the co♻e framework package,
 2. Reference the library in your project or library,
 3. Create test suites and run the tests.


-1. Download and install the CfUnit framework package
-
-    * Open the folder where you saved the CfUnit.Package to,
+1. Download and install the co♻e framework package
+
+    * Open the folder where you saved the co♻e.Package to,
     * Now doubleclick it..
     * Follow the instructions..

 2. Reference the library in your project or library,

-    * In order to use CfUnit you need to add a reference to the library in your project. 
+    * In order to use co♻e you need to add a reference to the library in your project. 
     * Open your CODESYS project, and right-click on the References under the PLC-project and click on Add library…
     * Add library reference
-    * Next go to the CfUnit-group, select CfUnit and click OK.
+    * Next go to the co♻e-group, select co♻e and click OK.

 3. Create test suites and run them

     * For every function block (or function) that you have defined, create a test function block counterpart (a test suite), which has the responsibility to:
-    * Instantiate the FB under test,
-    * Define the inputs,
-    * Define the expected outputs (result),
-    * Call the CfUnit-assert methods to compare the expected output to the actual output for every test,
+        * Instantiate the FB under test,
+        * Define the inputs,
+        * Define the expected outputs (result),
+        * Call the co♻e-assert methods to compare the expected output to the actual output for every test,

 It’s entirely up to you, the user, how to organize the different tests, so what follows is a suggestion;
-On the same level as the POUs folder, create a folder called Test. It is in this folder that we will create all our test FBs as well as the program that will run the CfUnit framework.
-
-In this example we have a total of five FBs. For every FB we have created a test-FB, i.e. for `FB_DiagnosticMessageDiagnosticCodeParser` we have `FB_DiagnosticMessageDiagnosticCodeParser_Test`. Note that the framework in no way enforces to use any standard for the naming, this is entirely up to the user. For various reasons you might find it not even be possible to add the test-FBs in the same project (for instance, if this is your main executable), and in this case just put the tests in a separate project and include the main project in the test project as a library. Generally it’s better to structure the code in various library projects each responsible for a certain set of requirements/functionality. It’s important to see the tests as an important part of your code.
-
-The general structure here is that `PRG_TEST` is the program in where the test-FBs (test suites) are instantiated. Each test suite is responsible of testing one FB or function, and can have one or more tests to do so. Let’s assume we want to create the simplest possible FB that takes two unsigned integers and sums them. We can create the header for the FB, but the actual implementation can (and should) wait after we’ve done the unit tests.
+On the same level as the POUs folder, create a folder called Test. It is in this folder that we will create all our test FBs as well as the program that will run the co♻e framework.
+
+In this example we have a total of five FBs. For every FB we have created a test-FB, i.e. for `FB_DiagnosticMessageDiagnosticCodeParser` we have `FB_DiagnosticMessageDiagnosticCodeParser_Test`. 
+Note that the framework in no way enforces to use any standard for the naming, this is entirely up to the user. 
+For various reasons you might find it not even be possible to add the test-FBs in the same project (for instance, if this is your main executable), and in this case just put the tests in a separate project and include the main project in the test project as a library. 
+Generally it’s better to structure the code in various library projects each responsible for a certain set of requirements/functionality. 
+It’s important to see the tests as an important part of your code.
+
+The general structure here is that `PRG_TEST` is the program in where the test-FBs (test suites) are instantiated.
+Each test suite is responsible of testing one FB or function, and can have one or more tests to do so. 
+Let’s assume we want to create the simplest possible FB that takes two unsigned integers and sums them. 
+We can create the header for the FB, but the actual implementation can (and should) wait after we’ve done the unit tests.

 ~~~
 FUNCTION_BLOCK FB_Sum
@@ -65,16 +76,20 @@
 ~~~

 Now let’s create the test suite for this FB (we still do not implement the FB itself!)
-This FB needs to extend `CfUnit.FB_TestSuite`.
-
-~~~
-FUNCTION_BLOCK FB_Sum_Test EXTENDS CfUnit.FB_TestSuite
-VAR
-END_VAR
-~~~
-
-By always adding this code, your test suite gets access to CfUnit and CfUnit will have a handle to your test suites.
-Now it’s time to create our tests. There are many ways to structure your tests, and there are several guidelines for this as well. What we’ll be doing is to create a method for every test, and name it in such a way that it’s clear what the test does. Remember that the unit tests are part of the documentation of your code, and although you might find the code trivial at this moment, there might be other developers reading your code now (or many years in the future). **For them well-named tests are invaluable**. 
+This FB needs to extend `CoUnit.FB_TestSuite`.
+
+~~~
+FUNCTION_BLOCK FB_Sum_Test EXTENDS CoUnit.FB_TestSuite
+VAR
+END_VAR
+~~~
+
+By always adding this code, your test suite gets access to co♻e and co♻e will have a handle to your test suites.
+Now it’s time to create our tests. There are many ways to structure your tests, and there are several guidelines for this as well. 
+What we’ll be doing is to create a method for every test, and name it in such a way that it’s clear what the test does. 
+Remember that the unit tests are part of the documentation of your code, and although you might find the code trivial at this moment, 
+there might be other developers reading your code now (or many years in the future). **For them well-named tests are invaluable**. 
+
 We’ll be creating two tests called `TwoPlusTwoEqualsFour` and `ZeroPlusZeroEqualsZero`.

 ~~~
@@ -96,12 +111,14 @@
 TEST_FINISHED();
 ~~~

-By calling `TEST()` we tell CfUnit that everything that follows is a test. Remember that we did `EXTEND FB_TestSuite` in our test-suite? This gives us access to assert-methods to check for all the data types available in IEC61131-3, including the ANY-type. The Message parameter is optional and is used in case the assertion fails, the text is appended to the error output. We finish the method by calling `TEST_FINISHED()`. 
-**This gives the flexibility to have tests that span over more than one PLC-cycle.** 
+By calling `TEST()` we tell co♻e that everything that follows is a test. Remember that we did `EXTEND FB_TestSuite` in our test-suite? 
+This gives us access to assert-methods to check for all the data types available in IEC61131-3, including the ANY-type. 
+The Message parameter is optional and is used in case the assertion fails, the text is appended to the error output. 
+We finish the method by calling `TEST_FINISHED()`. **This gives the flexibility to have tests that span over more than one PLC-cycle.** 
 An example is provided in the package to demonstrate this.

-
 For `ZeroPlusZeroEqualsZero` it’s more or less the same code.
+
 ~~~
 METHOD ZeroPlusZeroEqualsZero
 VAR
@@ -120,24 +137,28 @@

 TEST_FINISHED();
 ~~~
+
 Next we need to update the body of the test suite (`FB_Sum_Test`) to make sure these two tests are being run.
+
 ~~~
 TwoPlusTwoEqualsFour();
 ZeroPlusZeroEqualsZero();
 ~~~
+
 Last but not least, we need to have a program `PRG_TEST` defined in a task that we can run in our PLC. 

 *Note that this program is only created to run the unit-tests, but should not run on the production target PLC(!)
 Being part of the library project we only want a convenient way to test all the FBs part of our library, and thus need this program to execute the test suites.*

 PRG_TEST needs to instantiate all the test suites, and only execute one line of code. In this case we only have one test suite.
+
 ~~~
 PROGRAM PRG_TEST
 VAR
     fbSum_Test : FB_Sum_Test; // This is our test suite
 END_VAR

-CfUnit.RUN();
+CoUnit.RUN();
 ~~~

 Activating this solution and running it results in the following result:
@@ -151,7 +172,9 @@
 ==========TESTS FINISHED RUNNING==========
 ~~~

-There is one test that has failed, and the reason for this is that we have not written the implementation of the FB yet, but only the header of the function block `FB_Sum`. But what is the reason that we have one test succeeding? As we can see, the test `TwoPlusTwoEqualsFour` failed, which means that the one that succeeded was the other test `ZeroPlusZeroEqualsZero`. The reason this succeeds is that the default return value for an output-parameter is zero, and thus it means that even if we haven’t written the body of `FB_Sum` the test will succeed. 
+There is one test that has failed, and the reason for this is that we have not written the implementation of the FB yet, but only the header of the function block `FB_Sum`. 
+But what is the reason that we have one test succeeding? As we can see, the test `TwoPlusTwoEqualsFour` failed, which means that the one that succeeded was the other test `ZeroPlusZeroEqualsZero`. 
+The reason this succeeds is that the default return value for an output-parameter is zero, and thus it means that even if we haven’t written the body of `FB_Sum` the test will succeed. 
 Let’s finish by implementing the body of `FB_Sum`.

 ~~~
@@ -178,11 +201,12 @@
 ==========TESTS FINISHED RUNNING==========
 ~~~

-Obviously this is a very simple example and the purpose of this was to show how to use the framework itself rather to come up with a real-world example. Simple functionality that does not require any state would be better suited to be implemented as a function, or in this case just using the “+” operator.
-
-Of course the verifier and other examples can provide you with hints on how to write your own tests. Also, we would like to encourage you on sharing your code, unit test and experience with us here on Forge! 
+Obviously this is a very simple example and the purpose of this was to show how to use the framework itself rather to come up with a real-world example.
+Simple functionality that does not require any state would be better suited to be implemented as a function, or in this case just using the “+” operator.
+Of course the verifier and other examples can provide you with hints on how to write your own tests. 
+Also, we would like to encourage you on sharing your code, unit test and experience with us here on Forge! 

 **Good luck and we hope you will enjoy writing good tests and bug free software!** 

-Regards,
+Regards
 [[members limit=20]]

Home modified by h-hermsen

h-hermsen — Sun, 08 Aug 2021 15:48:44 -0000

--- v3
+++ v4
@@ -1,5 +1,5 @@
 [[members limit=20]]
-[[TOC]]
+
 # Quick Start
 All you need to do is to download & install the library and provide a reference of the CfUnit-library in your project. 
 Now you are ready and you can start to write your test code! Just follow these few simple steps;
@@ -184,5 +184,5 @@

 **Good luck and we hope you will enjoy writing good tests and bug free software!** 

+Regards,
 [[members limit=20]]
-[[TOC]]

Home modified by h-hermsen

h-hermsen — Sun, 08 Aug 2021 15:48:06 -0000

--- v2
+++ v3
@@ -1,5 +1,5 @@
 [[members limit=20]]
-[TOC]
+[[TOC]]
 # Quick Start
 All you need to do is to download & install the library and provide a reference of the CfUnit-library in your project. 
 Now you are ready and you can start to write your test code! Just follow these few simple steps;
@@ -182,7 +182,7 @@

 Of course the verifier and other examples can provide you with hints on how to write your own tests. Also, we would like to encourage you on sharing your code, unit test and experience with us here on Forge! 

-## Good luck and we hope you will enjoy writing good tests and bug free software! 
+**Good luck and we hope you will enjoy writing good tests and bug free software!** 

 [[members limit=20]]
-[TOC]
+[[TOC]]

Home modified by h-hermsen

h-hermsen — Sun, 08 Aug 2021 15:47:10 -0000

--- v1
+++ v2
@@ -1,7 +1,188 @@
-Welcome to your wiki!
+[[members limit=20]]
+[TOC]
+# Quick Start
+All you need to do is to download & install the library and provide a reference of the CfUnit-library in your project. 
+Now you are ready and you can start to write your test code! Just follow these few simple steps;

-This is the default page, edit it as you see fit. To add a new page simply reference it within brackets, e.g.: [SamplePage].
+1 `Extend CfUnit.FB_TestSuite`,
+2 Define the inputs, define the expected outputs (result),
+4 Call the CfUnit-assert methods to compare the expected output to the actual output,
+5 Close the test with `TEST_FINISHED()` when finished.

-The wiki uses [Markdown](/lib/counit/tutorial/markdown_syntax/) syntax.
+# Checking test results
+The Unit testing results are viewable via the Device Log;
+Select CfUnit as Logger via the pulldown menu and press refresh, wait a few moments and the contents will be shown.
+
+![](https://forge.codesys.com/prj/cfunit/code/HEAD/tree/tags/v1.0.0.0/CfUnitVerifier.gif?format=raw)
+
+# Introduction user guide
+It’s highly recommended to also read unit testing concepts (google is your friend), in order to have a basic understanding of the concepts of unit testing and CfUnit. The framework gives you the possibility to easily write unit tests for your PLC software, and having the results reported in a human-readable format for review. All unit test code is written in the same program/library as the rest of your code, but because it is only used in a separate test-program, it does not affect the production code/executables. With unit test-code provided with the rest of the code, you can see these additions as living documentation of the code. For a more thorough/detailed example please see the simple programming example or the Unit Verifier. 
+
+This guide is a short tutorial in which we will go through the different steps that are necessary to use CfUnit;
+
+1. Download and install the CfUnit framework package,
+2. Reference the library in your project or library,
+3. Create test suites and run the tests.
+
+
+1. Download and install the CfUnit framework package
+
+    * Open the folder where you saved the CfUnit.Package to,
+    * Now doubleclick it..
+    * Follow the instructions..
+
+2. Reference the library in your project or library,
+
+    * In order to use CfUnit you need to add a reference to the library in your project. 
+    * Open your CODESYS project, and right-click on the References under the PLC-project and click on Add library…
+    * Add library reference
+    * Next go to the CfUnit-group, select CfUnit and click OK.
+
+3. Create test suites and run them
+
+    * For every function block (or function) that you have defined, create a test function block counterpart (a test suite), which has the responsibility to:
+    * Instantiate the FB under test,
+    * Define the inputs,
+    * Define the expected outputs (result),
+    * Call the CfUnit-assert methods to compare the expected output to the actual output for every test,
+
+It’s entirely up to you, the user, how to organize the different tests, so what follows is a suggestion;
+On the same level as the POUs folder, create a folder called Test. It is in this folder that we will create all our test FBs as well as the program that will run the CfUnit framework.
+
+In this example we have a total of five FBs. For every FB we have created a test-FB, i.e. for `FB_DiagnosticMessageDiagnosticCodeParser` we have `FB_DiagnosticMessageDiagnosticCodeParser_Test`. Note that the framework in no way enforces to use any standard for the naming, this is entirely up to the user. For various reasons you might find it not even be possible to add the test-FBs in the same project (for instance, if this is your main executable), and in this case just put the tests in a separate project and include the main project in the test project as a library. Generally it’s better to structure the code in various library projects each responsible for a certain set of requirements/functionality. It’s important to see the tests as an important part of your code.
+
+The general structure here is that `PRG_TEST` is the program in where the test-FBs (test suites) are instantiated. Each test suite is responsible of testing one FB or function, and can have one or more tests to do so. Let’s assume we want to create the simplest possible FB that takes two unsigned integers and sums them. We can create the header for the FB, but the actual implementation can (and should) wait after we’ve done the unit tests.
+
+~~~
+FUNCTION_BLOCK FB_Sum
+VAR_INPUT
+    one : UINT;
+    two : UINT;
+END_VAR
+VAR_OUTPUT
+    result : UINT;
+END_VAR
+~~~
+
+Now let’s create the test suite for this FB (we still do not implement the FB itself!)
+This FB needs to extend `CfUnit.FB_TestSuite`.
+
+~~~
+FUNCTION_BLOCK FB_Sum_Test EXTENDS CfUnit.FB_TestSuite
+VAR
+END_VAR
+~~~
+
+By always adding this code, your test suite gets access to CfUnit and CfUnit will have a handle to your test suites.
+Now it’s time to create our tests. There are many ways to structure your tests, and there are several guidelines for this as well. What we’ll be doing is to create a method for every test, and name it in such a way that it’s clear what the test does. Remember that the unit tests are part of the documentation of your code, and although you might find the code trivial at this moment, there might be other developers reading your code now (or many years in the future). **For them well-named tests are invaluable**. 
+We’ll be creating two tests called `TwoPlusTwoEqualsFour` and `ZeroPlusZeroEqualsZero`.
+
+~~~
+METHOD TwoPlusTwoEqualsFour
+VAR
+    Sum : FB_Sum;
+    Result : UINT;
+    ExpectedSum : UINT := 4;
+END_VAR
+ 
+TEST('TwoPlusTwoEqualsFour');
+ 
+Sum(one := 2, two := 2, result => Result);
+ 
+AssertEquals(Expected := ExpectedSum,
+             Actual := Result,
+             Message := 'The calculation is not correct');
+ 
+TEST_FINISHED();
+~~~
+
+By calling `TEST()` we tell CfUnit that everything that follows is a test. Remember that we did `EXTEND FB_TestSuite` in our test-suite? This gives us access to assert-methods to check for all the data types available in IEC61131-3, including the ANY-type. The Message parameter is optional and is used in case the assertion fails, the text is appended to the error output. We finish the method by calling `TEST_FINISHED()`. 
+**This gives the flexibility to have tests that span over more than one PLC-cycle.** 
+An example is provided in the package to demonstrate this.
+
+
+For `ZeroPlusZeroEqualsZero` it’s more or less the same code.
+~~~
+METHOD ZeroPlusZeroEqualsZero
+VAR
+    Sum : FB_Sum;
+    Result : UINT;
+    ExpectedSum : UINT := 0;
+END_VAR
+ 
+TEST('ZeroPlusZeroEqualsZero');
+ 
+Sum(one := 0, two := 0, result => Result);
+ 
+AssertEquals(Expected := ExpectedSum,
+             Actual := Result,
+             Message := 'The calculation is not correct');
+ 
+TEST_FINISHED();
+~~~
+Next we need to update the body of the test suite (`FB_Sum_Test`) to make sure these two tests are being run.
+~~~
+TwoPlusTwoEqualsFour();
+ZeroPlusZeroEqualsZero();
+~~~
+Last but not least, we need to have a program `PRG_TEST` defined in a task that we can run in our PLC. 
+
+*Note that this program is only created to run the unit-tests, but should not run on the production target PLC(!)
+Being part of the library project we only want a convenient way to test all the FBs part of our library, and thus need this program to execute the test suites.*
+
+PRG_TEST needs to instantiate all the test suites, and only execute one line of code. In this case we only have one test suite.
+~~~
+PROGRAM PRG_TEST
+VAR
+    fbSum_Test : FB_Sum_Test; // This is our test suite
+END_VAR
+ 
+CfUnit.RUN();
+~~~
+
+Activating this solution and running it results in the following result:
+
+~~~
+======================================
+Failed Tests: 1
+Successful tests: 1
+Tests: 2
+Test suites : 1
+==========TESTS FINISHED RUNNING==========
+~~~
+
+There is one test that has failed, and the reason for this is that we have not written the implementation of the FB yet, but only the header of the function block `FB_Sum`. But what is the reason that we have one test succeeding? As we can see, the test `TwoPlusTwoEqualsFour` failed, which means that the one that succeeded was the other test `ZeroPlusZeroEqualsZero`. The reason this succeeds is that the default return value for an output-parameter is zero, and thus it means that even if we haven’t written the body of `FB_Sum` the test will succeed. 
+Let’s finish by implementing the body of `FB_Sum`.
+
+~~~
+FUNCTION_BLOCK FB_Sum
+VAR_INPUT
+    one : UINT;
+    two : UINT;
+END_VAR
+VAR_OUTPUT
+    result : UINT;
+END_VAR
+ 
+result := one + two;
+~~~
+
+Running the tests again we get the expected behavior:
+
+~~~
+======================================
+Failed Tests: 0
+Successful tests: 2
+Tests: 2
+Test suites : 1
+==========TESTS FINISHED RUNNING==========
+~~~
+
+Obviously this is a very simple example and the purpose of this was to show how to use the framework itself rather to come up with a real-world example. Simple functionality that does not require any state would be better suited to be implemented as a function, or in this case just using the “+” operator.
+
+Of course the verifier and other examples can provide you with hints on how to write your own tests. Also, we would like to encourage you on sharing your code, unit test and experience with us here on Forge! 
+
+## Good luck and we hope you will enjoy writing good tests and bug free software! 

 [[members limit=20]]
+[TOC]

Home modified by h-hermsen

h-hermsen — Sun, 08 Aug 2021 15:43:53 -0000

Welcome to your wiki!

This is the default page, edit it as you see fit. To add a new page simply reference it within brackets, e.g.: [SamplePage].

The wiki uses Markdown syntax.

Recent changes to Tutorial

Tutorial modified by h-hermsen

Home modified by h-hermsen

Home modified by h-hermsen

Home modified by h-hermsen

Home modified by h-hermsen

Home modified by h-hermsen

Project Members: