You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2017/06/30 01:43:04 UTC
[mynewt-site] branch asf-site updated: Updated the test suite PR
#209
This is an automated email from the ASF dual-hosted git repository.
aditi pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/mynewt-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new d3a5a61 Updated the test suite PR #209
d3a5a61 is described below
commit d3a5a613cc8b635c8a42b5bc8333bc665b5a882c
Author: aditihilbert <ad...@runtime.io>
AuthorDate: Thu Jun 29 18:42:49 2017 -0700
Updated the test suite PR #209
---
develop/mkdocs/search_index.json | 47 ++--
develop/os/tutorials/unit_test/index.html | 378 ++++++++++++++++++++----------
index.html | 4 +-
latest/mkdocs/search_index.json | 47 ++--
latest/os/tutorials/unit_test/index.html | 378 ++++++++++++++++++++----------
5 files changed, 556 insertions(+), 298 deletions(-)
diff --git a/develop/mkdocs/search_index.json b/develop/mkdocs/search_index.json
index e5126aa..60a763b 100644
--- a/develop/mkdocs/search_index.json
+++ b/develop/mkdocs/search_index.json
@@ -1577,63 +1577,58 @@
},
{
"location": "/os/tutorials/unit_test/",
- "text": "Write a Test Suite for a Package\n\n\nThis document presents a tutorial which guides the reader through writing\na test suite for a Mynewt package (new or existing).\n\n\nIntroduction\n\n\nWriting a test suite involves using the \nlibs/testutil\n\n package within Mynewt core os. The \ntestutil\n library provides the interface to \nthe \nnewt\n command tool and also provides the compile time hooks to include\ntest suites into your code. Review the \n[\ntestutil\n int [...]
+ "text": "Write a Test Suite for a Package\n\n\nThis document guides the reader through creating a test suite for a Mynewt package.\n\n\nIntroduction\n\n\nWriting a test suite involves using the\n\ntest/testutil\n package. The testutil\nlibrary provides the functionality needed to define test suites and test cases.\n\n\nChoose Your Package Under Test\n\n\nChoose the package you want to write a test suite for. In this tutorial, we\nwill use the \ntime/datetime\n in the apache [...]
"title": "Write a Test Suite for a Package"
},
{
"location": "/os/tutorials/unit_test/#write-a-test-suite-for-a-package",
- "text": "This document presents a tutorial which guides the reader through writing\na test suite for a Mynewt package (new or existing).",
+ "text": "This document guides the reader through creating a test suite for a Mynewt package.",
"title": "Write a Test Suite for a Package"
},
{
"location": "/os/tutorials/unit_test/#introduction",
- "text": "Writing a test suite involves using the libs/testutil \n package within Mynewt core os. The testutil library provides the interface to \nthe newt command tool and also provides the compile time hooks to include\ntest suites into your code. Review the \n[ testutil introduction page ] (../modules/testutil/testutil.md)\nto learn about how the library works.",
+ "text": "Writing a test suite involves using the test/testutil package. The testutil\nlibrary provides the functionality needed to define test suites and test cases.",
"title": "Introduction"
},
{
- "location": "/os/tutorials/unit_test/#identify-your-package",
- "text": "Identify the package for which you are writing a test suite. For this example\nwe will use libs/json . To create a new package, see this Tutorial .",
- "title": "Identify Your Package"
+ "location": "/os/tutorials/unit_test/#choose-your-package-under-test",
+ "text": "Choose the package you want to write a test suite for. In this tutorial, we\nwill use the time/datetime in the apache-mynewt-core repo. Throughout this\ntutorial, we will be inside the apache-mynewt-core repo directory, unlike most\ntutorials which operate from the top-level project directory.",
+ "title": "Choose Your Package Under Test"
},
{
- "location": "/os/tutorials/unit_test/#modify-pkgyml",
- "text": "Edit the package ( pkg.yml ) file for your package and add the test dependency\nfor the Mynewt core OS libs/testutil . pkg . deps . TEST :\n - libs/testutil",
- "title": "Modify Pkg.yml"
- },
- {
- "location": "/os/tutorials/unit_test/#create-your-test-suite-template",
- "text": "Create a subdirectory test under your package main directory. \nCreate a file pair for your test code and header files within the test \ndirectory created above. Below shows the libs/json directory within the \nMynewt core, including the test directory. In this example, we used the \nconvention test_xxx.c/h (in this case test_json ). \u251c\u2500\u2500 MSJSON_COPYING \u251c\u2500\u2500 include \u2502\u00a0\u00a0 \u2514\u2500\u2500 json \u2502\u00 [...]
- "title": "Create Your Test Suite Template"
+ "location": "/os/tutorials/unit_test/#create-a-test-package",
+ "text": "Typically, a library has only one test package. The convention is name the\ntest package by appending /test to the host library name. For example, the\ntest package for encoding/json is encoding/json/test . The directory\nstructure of the json package is shown below: encoding/json \u251c\u2500\u2500 include \u2502\u00a0\u00a0 \u2514\u2500\u2500 json \u2502\u00a0\u00a0 \u2514\u2500\u2500 json . h \u251c\u2500\u2500 pkg . yml \u251c\u2500\ [...]
+ "title": "Create A Test Package"
},
{
"location": "/os/tutorials/unit_test/#create-your-test-suite-code",
- "text": "Edit the test_json.c file and add your test suite definition. NOTE that \nthe test suite code requires #include testutil/testutil.h to get the \nMynewt testutil definitions. Your test suite test_json.c file contains at a minimum two functions: A test Suite which is empty for now, but will contain calls to your test\ncases. A main function which must be #ifdef 'd using MYNEWT_SELFTEST to ensure\nthat is does not get compiled in when this test suite is [...]
+ "text": "We will be adding a test suite to the main.c file. The test suite will be empty for now. We also need to invoke the test suite from main() . Our main.c file now looks like this: #include sysinit/sysinit.h #include testutil/testutil.h TEST_SUITE ( test_datetime_suite ) {\n /* Empty for now; add test cases later. */ \n} #if MYNEWT_VAL(SELFTEST) int main ( int argc , char **argv )\n{\n /* Initialize all packages. */ \n sysinit ();\n\n [...]
"title": "Create Your Test Suite Code"
},
{
"location": "/os/tutorials/unit_test/#try-it-out",
- "text": "At this point, you have a working test suite with no tests. \nThis will by default pass the test. Your output will look\nsomething like this. You can use the newt test command to run the unit tests for any package. \nJust include the package name. These unit tests run via the project unittest which is a native project automatically included in the core\nos package. Below shows some of the test output of this command. $ newt test libs/json Archiving [...]
+ "text": "We now have a working test suite with no tests. Let's make sure we get a passing result when we run newt test : $ newt test time/datetime build output \nExecuting test: /home/me/mynewt-core/bin/targets/unittest/time_datetime_test/app/time/datetime/test/time_datetime_test.elf\nPassed tests: [time/datetime/test]\nAll tests passed",
"title": "Try It Out"
},
{
"location": "/os/tutorials/unit_test/#create-a-test",
- "text": "To create a test within your test suite, there are two things to do. Add the functions to your test suite Implement the function using the testutil macros For this tutorial we will create two functions: one to test a simple json\nencode and one to test the decode of this simple message to ensure its \ncoherent. Follow These steps; 1. Create function prototypes in test_json.h for your test functions. \nA macro in testutil.h hides the actual prototype, but [...]
+ "text": "To create a test within your test suite, there are two things to do. Implement the test case function using the testutil macros. Call the test case function from within the test suite. For this tutorial we will create a test case to verify the datetime_parse() \nfunction. The datetime_parse() function is declared as follows: /** * Parses an RFC 3339 datetime string. Some examples of valid datetime strings * are: * 2016-03-02T22:44:00 [...]
"title": "Create a Test"
},
{
- "location": "/os/tutorials/unit_test/#add-contents-to-your-tests",
- "text": "At this point, you can add contents to your test and verify that \nthe test suites pass. For now, lets just add a simple failure to show\nwhat it would look like when running from Newt. Edit test_json_simple.c and add a TEST_ASSERT to a test function. The\ntest assert will fail if its argument is false . TEST_CASE ( test_json_simple_encode ) {\n TEST_ASSERT ( 0 );\n} When running newt, you will see the test suite fails with something like\nthe message [...]
- "title": "Add Contents to your Tests"
+ "location": "/os/tutorials/unit_test/#asserting",
+ "text": "The test/testutil package provides two tools for verifying the correctness of a package: TEST_ASSERT TEST_ASSERT_FATAL Both of these macros check if the supplied condition is true. They differ in\nhow they behave when the condition is not true. On failure, TEST_ASSERT \nreports the error and proceeds with the remainder of the test case. TEST_ASSERT_FATAL , on the other hand, aborts the test case on failure. The general rule is to only use TEST_ASSERT_FATA [...]
+ "title": "Asserting"
},
{
- "location": "/os/tutorials/unit_test/#congratulations",
- "text": "Now you can begin the work of adding your test cases and test.",
- "title": "Congratulations"
+ "location": "/os/tutorials/unit_test/#scaling-up",
+ "text": "The above example is small and self contained, so it is reasonable to put\neverything in a single C file. A typical package will need a lot more test\ncode, and it helps to follow some conventions to maintain organization. Let's\ntake a look at a more realistic example. Here is the directory structure of\nthe fs/nffs/test package: fs/nffs/test\n\u251c\u2500\u2500 pkg.yml\n\u2514\u2500\u2500 src\n \u251c\u2500\u2500 nffs_test.c\n \u251c\u2500\u2500 nffs_te [...]
+ "title": "Scaling Up"
},
{
- "location": "/os/tutorials/unit_test/#testing-on-your-target",
- "text": "",
- "title": "Testing on your target"
+ "location": "/os/tutorials/unit_test/#congratulations",
+ "text": "Now you can begin the work of validating your packages.",
+ "title": "Congratulations"
},
{
"location": "/os/tutorials/event_queue/",
diff --git a/develop/os/tutorials/unit_test/index.html b/develop/os/tutorials/unit_test/index.html
index f660b15..4ed1c3e 100644
--- a/develop/os/tutorials/unit_test/index.html
+++ b/develop/os/tutorials/unit_test/index.html
@@ -499,174 +499,308 @@
<h1 id="write-a-test-suite-for-a-package">Write a Test Suite for a Package</h1>
-<p>This document presents a tutorial which guides the reader through writing
-a test suite for a Mynewt package (new or existing).</p>
+<p>This document guides the reader through creating a test suite for a Mynewt package.</p>
<h2 id="introduction">Introduction</h2>
-<p>Writing a test suite involves using the <a href="../../modules/testutil/testutil/"><code>libs/testutil</code></a>
- package within Mynewt core os. The <code>testutil</code> library provides the interface to
-the <code>newt</code> command tool and also provides the compile time hooks to include
-test suites into your code. Review the
-[<code>testutil</code> introduction page ] (../modules/testutil/testutil.md)
-to learn about how the library works.</p>
-<h3 id="identify-your-package">Identify Your Package</h3>
-<p>Identify the package for which you are writing a test suite. For this example
-we will use <code>libs/json</code>. To create a new package, see <a href="">this Tutorial</a>.</p>
-<h3 id="modify-pkgyml">Modify Pkg.yml</h3>
-<p>Edit the package (<code>pkg.yml</code>) file for your package and add the test dependency
-for the Mynewt core OS <code>libs/testutil</code>.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">pkg</span>.<span style="color: #000000">deps</span>.<span style="color: #000000">TEST</span>:
- <span style="color: #000000">-</span> <span style="color: #000000">libs/testutil</span>
-</pre></div>
-
-
-<h3 id="create-your-test-suite-template">Create Your Test Suite Template</h3>
-<p>Create a subdirectory <code>test</code> under your package main directory.
-Create a file pair for your test code and header files within the <code>test</code>
-directory created above. Below shows the <code>libs/json</code> directory within the
-Mynewt core, including the test directory. In this example, we used the
-convention <code>test_xxx.c/h</code> (in this case <code>test_json</code>).</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">├──</span> <span style="color: #000000">MSJSON_COPYING</span>
+<p>Writing a test suite involves using the
+<a href="../../modules/testutil/testutil/"><code>test/testutil</code></a> package. The testutil
+library provides the functionality needed to define test suites and test cases.</p>
+<h2 id="choose-your-package-under-test">Choose Your Package Under Test</h2>
+<p>Choose the package you want to write a test suite for. In this tutorial, we
+will use the <code>time/datetime</code> in the apache-mynewt-core repo. Throughout this
+tutorial, we will be inside the apache-mynewt-core repo directory, unlike most
+tutorials which operate from the top-level project directory.</p>
+<h2 id="create-a-test-package">Create A Test Package</h2>
+<p>Typically, a library has only one test package. The convention is name the
+test package by appending <code>/test</code> to the host library name. For example, the
+test package for <code>encoding/json</code> is <code>encoding/json/test</code>. The directory
+structure of the json package is shown below:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">encoding/json</span>
<span style="color: #000000">├──</span> <span style="color: #000000">include</span>
<span style="color: #000000">│ </span> <span style="color: #000000">└──</span> <span style="color: #000000">json</span>
<span style="color: #000000">│ </span> <span style="color: #000000">└──</span> <span style="color: #000000">json</span>.<span style="color: #000000">h</span>
<span style="color: #000000">├──</span> <span style="color: #000000">pkg</span>.<span style="color: #000000">yml</span>
-<span style="color: #000000">└──</span> <span style="color: #000000">src</span>
- <span style="color: #000000">├──</span> <span style="color: #000000">json_decode</span>.<span style="color: #000000">c</span>
- <span style="color: #000000">├──</span> <span style="color: #000000">json_encode</span>.<span style="color: #000000">c</span>
- <span style="color: #000000">└──</span> <span style="color: #000000">test</span>
+<span style="color: #000000">├──</span> <span style="color: #000000">src</span>
+<span style="color: #000000">│ </span> <span style="color: #000000">├──</span> <span style="color: #000000">json_decode</span>.<span style="color: #000000">c</span>
+<span style="color: #000000">│ </span> <span style="color: #000000">└──</span> <span style="color: #000000">json_encode</span>.<span style="color: #000000">c</span>
+<span style="color: #000000">└──</span> <span style="color: #000000">test</span>
+ <span style="color: #000000">├──</span> <span style="color: #000000">pkg</span>.<span style="color: #000000">yml</span>
+ <span style="color: #000000">└──</span> <span style="color: #000000">src</span>
<span style="color: #000000">├──</span> <span style="color: #000000">test_json</span>.<span style="color: #000000">c</span>
- <span style="color: #000000">└──</span> <span style="color: #000000">test_json</span>.<span style="color: #000000">h</span>
+ <span style="color: #000000">├──</span> <span style="color: #000000">test_json</span>.<span style="color: #000000">h</span>
+ <span style="color: #000000">├──</span> <span style="color: #000000">test_json_utils</span>.<span style="color: #000000">c</span>
+ <span style="color: #000000">└──</span> <span style="color: #000000">testcases</span>
+ <span style="color: #000000">├──</span> <span style="color: #000000">json_simple_decode</span>.<span style="color: #000000">c</span>
+ <span style="color: #000000">└──</span> <span style="color: #000000">json_simple_encode</span>.<span style="color: #000000">c</span>
</pre></div>
-<h3 id="create-your-test-suite-code">Create Your Test Suite Code</h3>
-<p>Edit the <code>test_json.c</code> file and add your test suite definition. NOTE that
-the test suite code requires <code>#include <testutil/testutil.h></code> to get the
-Mynewt testutil definitions.</p>
-<p>Your test suite <code>test_json.c</code> file contains at a minimum two functions:</p>
-<ol>
-<li>A test Suite which is empty for now, but will contain calls to your test
-cases. </li>
-<li>A main function which must be <code>#ifdef</code>'d using <code>MYNEWT_SELFTEST</code> to ensure
-that is does not get compiled in when this test suite is run with
-test suites from other packages </li>
-</ol>
-<p>Below shows the contents of the <code>test_json.c</code> file.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#include <testutil/testutil.h></span>
+<p>The top-level <code>test</code> directory contains the json test package. To create a
+test package for the datetime package, we need to create a similar package
+called <code>time/datetime/test</code>.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ newt pkg new time/datetime/test -t unittest
+Download package template for package type pkg.
+Package successfuly installed into /home/me/mynewt-core/time/datetime/test.
+</pre></div>
+
+
+<p>We now have a test package inside <code>time/datetime</code>:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">time/datetime
+├── include
+│ └── datetime
+│ └── datetime.h
+├── pkg.yml
+├── src
+│ └── datetime.c
+└── test
+ ├── README.md
+ ├── pkg.yml
+ ├── src
+ │ └── main.c
+ └── syscfg.yml
+</pre></div>
-<span style="color: #000000">TEST_SUITE</span>(<span style="color: #000000">test_json_suite</span>) {
- <span style="color: #177500">/* empty for now, add test cases later */</span>
+
+<p>There is one modification we need to make to the new package before we can
+start writing unit test code. A test package needs access to the code it will
+be testing, so we need to add a dependency on
+<code>@apache-mynewt-core/time/datetime</code> to our <code>pkg.yml</code> file:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">pkg.name: "time/datetime/test"
+pkg.type: unittest
+pkg.description: "Description of your package"
+pkg.author: "You <you@you.org>"
+pkg.homepage: "http://your-url.org/"
+pkg.keywords:
+
+pkg.deps:
+ - '@apache-mynewt-core/test/testutil'
+<span style="background-color: #ffffcc"> - '@apache-mynewt-core/time/datetime'
+</span>
+pkg.deps.SELFTEST:
+ - '@apache-mynewt-core/sys/console/stub'
+</pre></div>
+
+
+<p>While we have the <code>pkg.yml</code> file open, let's take a look at what newt filled in automatically:</p>
+<ul>
+<li><code>pkg.type: unittest</code> designates this as a test package. A <em>test package</em> is
+ special in that it can be built and executed using the <code>newt test</code> command.</li>
+<li>A test package always depends on <code>@apache-mynewt-core/test/testutil</code>. The
+ testutil library provides the tools necessary for verifying package behavior, </li>
+<li>The <code>SELFTEST</code> suffix indicates that a setting should only be applied when the <code>newt test</code> command is used.</li>
+</ul>
+<p>Regarding the conditional dependency on <code>sys/console/stub</code>, the datetime
+package requires some form of console to function. In a regular application,
+the console dependency would be supplied by a higher order package. Because
+<code>newt test</code> runs the test package without an application present, the test
+package needs to supply all unresolved dependencies itself when run in
+self-test mode.</p>
+<h2 id="create-your-test-suite-code">Create Your Test Suite Code</h2>
+<p>We will be adding a <em>test suite</em> to the <code>main.c</code> file. The test suite will be empty for now. We also need to invoke the test suite from <code>main()</code>.</p>
+<p>Our <code>main.c</code> file now looks like this:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#include "sysinit/sysinit.h"</span>
+<span style="color: #633820">#include "testutil/testutil.h"</span>
+
+<span style="color: #000000">TEST_SUITE</span>(<span style="color: #000000">test_datetime_suite</span>) {
+ <span style="color: #177500">/* Empty for now; add test cases later. */</span>
}
-<span style="color: #633820">#ifdef MYNEWT_SELFTEST</span>
+<span style="color: #633820">#if MYNEWT_VAL(SELFTEST)</span>
<span style="color: #A90D91">int</span>
<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**argv</span>)
{
- <span style="color: #000000">tu_config</span>.<span style="color: #000000">tc_print_results</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">1</span>;
- <span style="color: #000000">tu_init</span>();
- <span style="color: #000000">test_json_suite</span>();
+ <span style="color: #177500">/* Initialize all packages. */</span>
+ <span style="color: #000000">sysinit</span>();
+
+ <span style="color: #000000">test_datetime_suite</span>();
+
+ <span style="color: #177500">/* Indicate whether all test cases passed. */</span>
<span style="color: #A90D91">return</span> <span style="color: #000000">tu_any_failed</span>;
}
<span style="color: #633820">#endif</span>
</pre></div>
-<h3 id="try-it-out">Try It Out</h3>
-<p>At this point, you have a working test suite with <strong>no</strong> tests.<br />
-This will by default pass the test. Your output will look
-something like this.</p>
-<p>You can use the <code>newt test</code> command to run the unit tests for any package.<br />
-Just include the package name. These unit tests run via the project
-<code>unittest</code> which is a native project automatically included in the core
-os package. Below shows some of the test output of this command.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">$</span> <span style="color: #000000">newt</span> <span style="color: #000000">test</span> <span style="color: #000000">libs/json</span>
-<span style="color: #000000">Archiving</span> <span style="color: #000000">util</span>.<span style="color: #000000">a</span>
-<span style="color: #000000">Linking</span> <span style="color: #000000">test_json</span>
-<span style="color: #000000">Testing</span> <span style="color: #000000">package</span> <span style="color: #000000">libs/json</span>
-<span style="color: #000000">Test</span> ...<span style="color: #000000">/bin/unittest/libs/json/test_json</span> <span style="color: #000000">ok!</span>
+<h2 id="try-it-out">Try It Out</h2>
+<p>We now have a working test suite with no tests. Let's make sure we get a passing result when we run <code>newt test</code>:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ newt test time/datetime
+<build output>
+Executing test: /home/me/mynewt-core/bin/targets/unittest/time_datetime_test/app/time/datetime/test/time_datetime_test.elf
+Passed tests: [time/datetime/test]
+All tests passed
</pre></div>
-<h3 id="create-a-test">Create a Test</h3>
+<h2 id="create-a-test">Create a Test</h2>
<p>To create a test within your test suite, there are two things to do.</p>
<ol>
-<li>Add the functions to your test suite</li>
-<li>Implement the function using the <code>testutil</code> macros</li>
+<li>Implement the test case function using the <code>testutil</code> macros.</li>
+<li>Call the test case function from within the test suite.</li>
</ol>
-<p>For this tutorial we will create two functions: one to test a simple json
-encode and one to test the decode of this simple message to ensure its
-coherent.</p>
-<p>Follow These steps;</p>
-<p>1. Create function prototypes in <code>test_json.h</code> for your test functions.
-A macro in <code>testutil.h</code> hides the actual prototype, but as of this writing
-the prototype is <code>int test_func(void);</code>. </p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#ifndef TEST_JSON_H</span>
-<span style="color: #633820">#define TEST_JSON_H</span>
-
-<span style="color: #000000">TEST_CASE_DECL</span>(<span style="color: #000000">test_json_simple_encode</span>);
-<span style="color: #000000">TEST_CASE_DECL</span>(<span style="color: #000000">test_json_simple_decode</span>);
-
-<span style="color: #633820">#endif /* TEST_JSON_H </span>
+<p>For this tutorial we will create a test case to verify the <code>datetime_parse()</code>
+function. The <code>datetime_parse()</code> function is declared as follows:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/**</span>
+<span style="color: #177500"> * Parses an RFC 3339 datetime string. Some examples of valid datetime strings</span>
+<span style="color: #177500"> * are:</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00 UTC time (implicit)</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00Z UTC time (explicit)</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00-08:00 PST timezone</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00.1 fractional seconds</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00.101+05:30 fractional seconds with timezone</span>
+<span style="color: #177500"> *</span>
+<span style="color: #177500"> * On success, the two output parameters are filled in (tv and tz).</span>
+<span style="color: #177500"> *</span>
+<span style="color: #177500"> * @return 0 on success;</span>
+<span style="color: #177500"> * nonzero on parse error.</span>
+<span style="color: #177500"> */</span>
+<span style="color: #A90D91">int</span>
+<span style="color: #000000">datetime_parse</span>(<span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*input</span>, <span style="color: #A90D91">struct</span> <span style="color: #000000">os_timeval</span> <span style="color: #000000">*tv</span>, <span style="color: #A90D91">struct</span> <span style="color: #000000">os_timezone</span> <span style="color: #000000">*tz</span>)
</pre></div>
-<p>2. create a new file <code>test_json_simple.c</code> to define these two functions. For
-now you can stub these functions. Below shows the contents of this file.
-The functions are defined using macros which reference back to the
-<code>testutil</code> library so the test can be enumerated and recorded automatically.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#include "testutil/testutil.h"</span>
-<span style="color: #633820">#include "test_json.h"</span>
+<p>Our test case should make sure this function rejects invalid input, and that it
+parses valid input correctly. The updated <code>main.c</code> file looks like this:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#include "sysinit/sysinit.h"</span>
+<span style="color: #633820">#include "testutil/testutil.h"</span>
+<span style="color: #633820">#include "os/os_time.h"</span>
+<span style="color: #633820">#include "datetime/datetime.h"</span>
-<span style="color: #000000">TEST_CASE</span>(<span style="color: #000000">test_json_simple_encode</span>) {
+<span style="color: #000000">TEST_SUITE</span>(<span style="color: #000000">test_datetime_suite</span>)
+{
+ <span style="color: #000000">test_datetime_parse_simple</span>();
}
-<span style="color: #000000">TEST_CASE</span>(<span style="color: #000000">test_json_simple_decode</span>) {
+<span style="color: #000000">TEST_CASE</span>(<span style="color: #000000">test_datetime_parse_simple</span>)
+{
+ <span style="color: #A90D91">struct</span> <span style="color: #000000">os_timezone</span> <span style="color: #000000">tz</span>;
+ <span style="color: #A90D91">struct</span> <span style="color: #000000">os_timeval</span> <span style="color: #000000">tv</span>;
+ <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
+
+ <span style="color: #177500">/*** Valid input. */</span>
+
+ <span style="color: #177500">/* No timezone; UTC implied. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2017-06-28T22:37:59"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT_FATAL</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tv</span>.<span style="color: #000000">tv_sec</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">1498689479</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tv</span>.<span style="color: #000000">tv_usec</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tz</span>.<span style="color: #000000">tz_minuteswest</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tz</span>.<span style="color: #000000">tz_dsttime</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/* PDT timezone. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2013-12-05T02:43:07-07:00"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT_FATAL</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tv</span>.<span style="color: #000000">tv_sec</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">1386236587</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tv</span>.<span style="color: #000000">tv_usec</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tz</span>.<span style="color: #000000">tz_minuteswest</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">420</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tz</span>.<span style="color: #000000">tz_dsttime</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/*** Invalid input. */</span>
+
+ <span style="color: #177500">/* Nonsense. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"abc"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/* Date-only. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2017-01-02"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/* Zero month. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2017-00-28T22:37:59"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/* 13 month. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2017-13-28T22:37:59"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
}
-<span style="color: #633820">#endif /* TEST_JSON_H </span>
-</pre></div>
+<span style="color: #633820">#if MYNEWT_VAL(SELFTEST)</span>
+<span style="color: #A90D91">int</span>
+<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**argv</span>)
+{
+ <span style="color: #177500">/* Initialize all packages. */</span>
+ <span style="color: #000000">sysinit</span>();
-<p>3. Add the tests to your test suite in <code>test_json.c</code> as shown below.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">TEST_SUITE</span>(<span style="color: #000000">test_json_suite</span>) {
- <span style="color: #000000">test_json_simple_encode</span>();
- <span style="color: #000000">test_json_simple_decode</span>();
-}
-</pre></div>
-
+ <span style="color: #000000">test_datetime_suite</span>();
-<p>Your test suite should still pass as shown below</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">$newt</span> <span style="color: #000000">test</span> <span style="color: #000000">libs/json</span>
-<span style="color: #000000">Testing</span> <span style="color: #000000">package</span> <span style="color: #000000">libs/json</span>
-<span style="color: #000000">Test</span> ...<span style="color: #000000">/bin/unittest/libs/json/test_json</span> <span style="color: #000000">ok!</span>
+ <span style="color: #177500">/* Indicate whether all test cases passed. */</span>
+ <span style="color: #A90D91">return</span> <span style="color: #000000">tu_any_failed</span>;
+}
+<span style="color: #633820">#endif</span>
</pre></div>
-<h2 id="add-contents-to-your-tests">Add Contents to your Tests</h2>
-<p>At this point, you can add contents to your test and verify that
-the test suites pass. For now, lets just add a simple failure to show
-what it would look like when running from Newt.</p>
+<p>Take a few minutes to review the above code. Then keep reading for some
+specifics.</p>
+<h3 id="asserting">Asserting</h3>
+<p>The <code>test/testutil</code> package provides two tools for verifying the correctness of a package:</p>
<ul>
-<li>Edit <code>test_json_simple.c</code> and add a <code>TEST_ASSERT</code> to a test function. The
-test assert will fail if its argument is <code>false</code>.</li>
+<li><code>TEST_ASSERT</code></li>
+<li><code>TEST_ASSERT_FATAL</code></li>
</ul>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">TEST_CASE</span>(<span style="color: #000000">test_json_simple_encode</span>) {
- <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #1C01CE">0</span>);
-}
-</pre></div>
-
-
-<p>When running newt, you will see the test suite fails with something like
-the message shown below.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">Testing</span> <span style="color: #000000">package</span> <span style="color: #000000">libs/json</span>
-[<span style="color: #000000">FAIL</span>] <span style="color: #000000">test_json_suite/</span>(<span style="color: #000000">null</span>) <span style="color: #000000">|test_json_simple</span>.<span style="color: #000000">c</span>:<span style="color: #1C01CE">24</span><span style="color: #000000">|</span> <span style="color: #000000">failed</span> <span style="color: #000000">assertion</span>: <span style="color: #1C01CE">0</span>
-<span style="color: #000000">Error</span>: <span style="color: #000000">Test</span> <span style="color: #000000">crashed</span>: ..<span style="color: #000000">/bin/unittest/libs/json/test_json</span>
-<span style="color: #000000">exit</span> <span style="color: #000000">status</span> <span style="color: #1C01CE">1</span>
+<p>Both of these macros check if the supplied condition is true. They differ in
+how they behave when the condition is not true. On failure, <code>TEST_ASSERT</code>
+reports the error and proceeds with the remainder of the test case.
+<code>TEST_ASSERT_FATAL</code>, on the other hand, aborts the test case on failure.</p>
+<p>The general rule is to only use <code>TEST_ASSERT_FATAL</code> when subsequent assertions
+depend on the condition being checked. For example, when <code>datetime_parse()</code> is
+expected to succeed, the return code is checked with <code>TEST_ASSERT_FATAL</code>. If
+<code>datetime_parse()</code> unexpectedly failed, the contents of the <code>tv</code> and <code>tz</code>
+objects would be indeterminate, so it is desirable to abort the test instead of
+checking them and reporting spurious failures.</p>
+<h3 id="scaling-up">Scaling Up</h3>
+<p>The above example is small and self contained, so it is reasonable to put
+everything in a single C file. A typical package will need a lot more test
+code, and it helps to follow some conventions to maintain organization. Let's
+take a look at a more realistic example. Here is the directory structure of
+the <code>fs/nffs/test</code> package:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">fs/nffs/test
+├── pkg.yml
+└── src
+ ├── nffs_test.c
+ ├── nffs_test.h
+ ├── nffs_test_debug.c
+ ├── nffs_test_priv.h
+ ├── nffs_test_system_01.c
+ ├── nffs_test_utils.c
+ ├── nffs_test_utils.h
+ └── testcases
+ ├── append_test.c
+ ├── cache_large_file_test.c
+ ├── corrupt_block_test.c
+ ├── corrupt_scratch_test.c
+ ├── gc_on_oom_test.c
+ ├── gc_test.c
+ ├── incomplete_block_test.c
+ ├── large_system_test.c
+ ├── large_unlink_test.c
+ ├── large_write_test.c
+ ├── long_filename_test.c
+ ├── lost_found_test.c
+ ├── many_children_test.c
+ ├── mkdir_test.c
+ ├── open_test.c
+ ├── overwrite_many_test.c
+ ├── overwrite_one_test.c
+ ├── overwrite_three_test.c
+ ├── overwrite_two_test.c
+ ├── read_test.c
+ ├── readdir_test.c
+ ├── rename_test.c
+ ├── split_file_test.c
+ ├── truncate_test.c
+ ├── unlink_test.c
+ └── wear_level_test.c
</pre></div>
+<p>The <code>fs/nffs/test</code> package follows these conventions:</p>
+<ol>
+<li>A maximum of one test case per C file.</li>
+<li>Each test case file goes in the <code>testcases</code> subdirectory.</li>
+<li>Test suites and utility functions go directly in the <code>src</code> directory.</li>
+</ol>
+<p>Test packages contributed to the Mynewt project should follow these conventions.</p>
<h2 id="congratulations">Congratulations</h2>
-<p>Now you can begin the work of adding your test cases and test.</p>
-<h2 id="testing-on-your-target">Testing on your target</h2>
+<p>Now you can begin the work of validating your packages.</p>
<div class="row">
diff --git a/index.html b/index.html
index dc7807b..a8839ea 100644
--- a/index.html
+++ b/index.html
@@ -10,7 +10,7 @@
<link rel="canonical" href="http://mynewt.apache.org/"> -->
<link rel="shortcut icon" href="./img/favicon.ico">
- <title>Apache Mynewt </title>
+ <title>Apache Mynewt</title>
<link href="./css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="./css/highlight.css">
@@ -329,4 +329,4 @@
<script src="./js/custom.js"></script>
</body>
-</html>
+</html>
\ No newline at end of file
diff --git a/latest/mkdocs/search_index.json b/latest/mkdocs/search_index.json
index e5126aa..60a763b 100644
--- a/latest/mkdocs/search_index.json
+++ b/latest/mkdocs/search_index.json
@@ -1577,63 +1577,58 @@
},
{
"location": "/os/tutorials/unit_test/",
- "text": "Write a Test Suite for a Package\n\n\nThis document presents a tutorial which guides the reader through writing\na test suite for a Mynewt package (new or existing).\n\n\nIntroduction\n\n\nWriting a test suite involves using the \nlibs/testutil\n\n package within Mynewt core os. The \ntestutil\n library provides the interface to \nthe \nnewt\n command tool and also provides the compile time hooks to include\ntest suites into your code. Review the \n[\ntestutil\n int [...]
+ "text": "Write a Test Suite for a Package\n\n\nThis document guides the reader through creating a test suite for a Mynewt package.\n\n\nIntroduction\n\n\nWriting a test suite involves using the\n\ntest/testutil\n package. The testutil\nlibrary provides the functionality needed to define test suites and test cases.\n\n\nChoose Your Package Under Test\n\n\nChoose the package you want to write a test suite for. In this tutorial, we\nwill use the \ntime/datetime\n in the apache [...]
"title": "Write a Test Suite for a Package"
},
{
"location": "/os/tutorials/unit_test/#write-a-test-suite-for-a-package",
- "text": "This document presents a tutorial which guides the reader through writing\na test suite for a Mynewt package (new or existing).",
+ "text": "This document guides the reader through creating a test suite for a Mynewt package.",
"title": "Write a Test Suite for a Package"
},
{
"location": "/os/tutorials/unit_test/#introduction",
- "text": "Writing a test suite involves using the libs/testutil \n package within Mynewt core os. The testutil library provides the interface to \nthe newt command tool and also provides the compile time hooks to include\ntest suites into your code. Review the \n[ testutil introduction page ] (../modules/testutil/testutil.md)\nto learn about how the library works.",
+ "text": "Writing a test suite involves using the test/testutil package. The testutil\nlibrary provides the functionality needed to define test suites and test cases.",
"title": "Introduction"
},
{
- "location": "/os/tutorials/unit_test/#identify-your-package",
- "text": "Identify the package for which you are writing a test suite. For this example\nwe will use libs/json . To create a new package, see this Tutorial .",
- "title": "Identify Your Package"
+ "location": "/os/tutorials/unit_test/#choose-your-package-under-test",
+ "text": "Choose the package you want to write a test suite for. In this tutorial, we\nwill use the time/datetime in the apache-mynewt-core repo. Throughout this\ntutorial, we will be inside the apache-mynewt-core repo directory, unlike most\ntutorials which operate from the top-level project directory.",
+ "title": "Choose Your Package Under Test"
},
{
- "location": "/os/tutorials/unit_test/#modify-pkgyml",
- "text": "Edit the package ( pkg.yml ) file for your package and add the test dependency\nfor the Mynewt core OS libs/testutil . pkg . deps . TEST :\n - libs/testutil",
- "title": "Modify Pkg.yml"
- },
- {
- "location": "/os/tutorials/unit_test/#create-your-test-suite-template",
- "text": "Create a subdirectory test under your package main directory. \nCreate a file pair for your test code and header files within the test \ndirectory created above. Below shows the libs/json directory within the \nMynewt core, including the test directory. In this example, we used the \nconvention test_xxx.c/h (in this case test_json ). \u251c\u2500\u2500 MSJSON_COPYING \u251c\u2500\u2500 include \u2502\u00a0\u00a0 \u2514\u2500\u2500 json \u2502\u00 [...]
- "title": "Create Your Test Suite Template"
+ "location": "/os/tutorials/unit_test/#create-a-test-package",
+ "text": "Typically, a library has only one test package. The convention is name the\ntest package by appending /test to the host library name. For example, the\ntest package for encoding/json is encoding/json/test . The directory\nstructure of the json package is shown below: encoding/json \u251c\u2500\u2500 include \u2502\u00a0\u00a0 \u2514\u2500\u2500 json \u2502\u00a0\u00a0 \u2514\u2500\u2500 json . h \u251c\u2500\u2500 pkg . yml \u251c\u2500\ [...]
+ "title": "Create A Test Package"
},
{
"location": "/os/tutorials/unit_test/#create-your-test-suite-code",
- "text": "Edit the test_json.c file and add your test suite definition. NOTE that \nthe test suite code requires #include testutil/testutil.h to get the \nMynewt testutil definitions. Your test suite test_json.c file contains at a minimum two functions: A test Suite which is empty for now, but will contain calls to your test\ncases. A main function which must be #ifdef 'd using MYNEWT_SELFTEST to ensure\nthat is does not get compiled in when this test suite is [...]
+ "text": "We will be adding a test suite to the main.c file. The test suite will be empty for now. We also need to invoke the test suite from main() . Our main.c file now looks like this: #include sysinit/sysinit.h #include testutil/testutil.h TEST_SUITE ( test_datetime_suite ) {\n /* Empty for now; add test cases later. */ \n} #if MYNEWT_VAL(SELFTEST) int main ( int argc , char **argv )\n{\n /* Initialize all packages. */ \n sysinit ();\n\n [...]
"title": "Create Your Test Suite Code"
},
{
"location": "/os/tutorials/unit_test/#try-it-out",
- "text": "At this point, you have a working test suite with no tests. \nThis will by default pass the test. Your output will look\nsomething like this. You can use the newt test command to run the unit tests for any package. \nJust include the package name. These unit tests run via the project unittest which is a native project automatically included in the core\nos package. Below shows some of the test output of this command. $ newt test libs/json Archiving [...]
+ "text": "We now have a working test suite with no tests. Let's make sure we get a passing result when we run newt test : $ newt test time/datetime build output \nExecuting test: /home/me/mynewt-core/bin/targets/unittest/time_datetime_test/app/time/datetime/test/time_datetime_test.elf\nPassed tests: [time/datetime/test]\nAll tests passed",
"title": "Try It Out"
},
{
"location": "/os/tutorials/unit_test/#create-a-test",
- "text": "To create a test within your test suite, there are two things to do. Add the functions to your test suite Implement the function using the testutil macros For this tutorial we will create two functions: one to test a simple json\nencode and one to test the decode of this simple message to ensure its \ncoherent. Follow These steps; 1. Create function prototypes in test_json.h for your test functions. \nA macro in testutil.h hides the actual prototype, but [...]
+ "text": "To create a test within your test suite, there are two things to do. Implement the test case function using the testutil macros. Call the test case function from within the test suite. For this tutorial we will create a test case to verify the datetime_parse() \nfunction. The datetime_parse() function is declared as follows: /** * Parses an RFC 3339 datetime string. Some examples of valid datetime strings * are: * 2016-03-02T22:44:00 [...]
"title": "Create a Test"
},
{
- "location": "/os/tutorials/unit_test/#add-contents-to-your-tests",
- "text": "At this point, you can add contents to your test and verify that \nthe test suites pass. For now, lets just add a simple failure to show\nwhat it would look like when running from Newt. Edit test_json_simple.c and add a TEST_ASSERT to a test function. The\ntest assert will fail if its argument is false . TEST_CASE ( test_json_simple_encode ) {\n TEST_ASSERT ( 0 );\n} When running newt, you will see the test suite fails with something like\nthe message [...]
- "title": "Add Contents to your Tests"
+ "location": "/os/tutorials/unit_test/#asserting",
+ "text": "The test/testutil package provides two tools for verifying the correctness of a package: TEST_ASSERT TEST_ASSERT_FATAL Both of these macros check if the supplied condition is true. They differ in\nhow they behave when the condition is not true. On failure, TEST_ASSERT \nreports the error and proceeds with the remainder of the test case. TEST_ASSERT_FATAL , on the other hand, aborts the test case on failure. The general rule is to only use TEST_ASSERT_FATA [...]
+ "title": "Asserting"
},
{
- "location": "/os/tutorials/unit_test/#congratulations",
- "text": "Now you can begin the work of adding your test cases and test.",
- "title": "Congratulations"
+ "location": "/os/tutorials/unit_test/#scaling-up",
+ "text": "The above example is small and self contained, so it is reasonable to put\neverything in a single C file. A typical package will need a lot more test\ncode, and it helps to follow some conventions to maintain organization. Let's\ntake a look at a more realistic example. Here is the directory structure of\nthe fs/nffs/test package: fs/nffs/test\n\u251c\u2500\u2500 pkg.yml\n\u2514\u2500\u2500 src\n \u251c\u2500\u2500 nffs_test.c\n \u251c\u2500\u2500 nffs_te [...]
+ "title": "Scaling Up"
},
{
- "location": "/os/tutorials/unit_test/#testing-on-your-target",
- "text": "",
- "title": "Testing on your target"
+ "location": "/os/tutorials/unit_test/#congratulations",
+ "text": "Now you can begin the work of validating your packages.",
+ "title": "Congratulations"
},
{
"location": "/os/tutorials/event_queue/",
diff --git a/latest/os/tutorials/unit_test/index.html b/latest/os/tutorials/unit_test/index.html
index 1558eb7..f2742bc 100644
--- a/latest/os/tutorials/unit_test/index.html
+++ b/latest/os/tutorials/unit_test/index.html
@@ -499,174 +499,308 @@
<h1 id="write-a-test-suite-for-a-package">Write a Test Suite for a Package</h1>
-<p>This document presents a tutorial which guides the reader through writing
-a test suite for a Mynewt package (new or existing).</p>
+<p>This document guides the reader through creating a test suite for a Mynewt package.</p>
<h2 id="introduction">Introduction</h2>
-<p>Writing a test suite involves using the <a href="../../modules/testutil/testutil/"><code>libs/testutil</code></a>
- package within Mynewt core os. The <code>testutil</code> library provides the interface to
-the <code>newt</code> command tool and also provides the compile time hooks to include
-test suites into your code. Review the
-[<code>testutil</code> introduction page ] (../modules/testutil/testutil.md)
-to learn about how the library works.</p>
-<h3 id="identify-your-package">Identify Your Package</h3>
-<p>Identify the package for which you are writing a test suite. For this example
-we will use <code>libs/json</code>. To create a new package, see <a href="">this Tutorial</a>.</p>
-<h3 id="modify-pkgyml">Modify Pkg.yml</h3>
-<p>Edit the package (<code>pkg.yml</code>) file for your package and add the test dependency
-for the Mynewt core OS <code>libs/testutil</code>.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">pkg</span>.<span style="color: #000000">deps</span>.<span style="color: #000000">TEST</span>:
- <span style="color: #000000">-</span> <span style="color: #000000">libs/testutil</span>
-</pre></div>
-
-
-<h3 id="create-your-test-suite-template">Create Your Test Suite Template</h3>
-<p>Create a subdirectory <code>test</code> under your package main directory.
-Create a file pair for your test code and header files within the <code>test</code>
-directory created above. Below shows the <code>libs/json</code> directory within the
-Mynewt core, including the test directory. In this example, we used the
-convention <code>test_xxx.c/h</code> (in this case <code>test_json</code>).</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">├──</span> <span style="color: #000000">MSJSON_COPYING</span>
+<p>Writing a test suite involves using the
+<a href="../../modules/testutil/testutil/"><code>test/testutil</code></a> package. The testutil
+library provides the functionality needed to define test suites and test cases.</p>
+<h2 id="choose-your-package-under-test">Choose Your Package Under Test</h2>
+<p>Choose the package you want to write a test suite for. In this tutorial, we
+will use the <code>time/datetime</code> in the apache-mynewt-core repo. Throughout this
+tutorial, we will be inside the apache-mynewt-core repo directory, unlike most
+tutorials which operate from the top-level project directory.</p>
+<h2 id="create-a-test-package">Create A Test Package</h2>
+<p>Typically, a library has only one test package. The convention is name the
+test package by appending <code>/test</code> to the host library name. For example, the
+test package for <code>encoding/json</code> is <code>encoding/json/test</code>. The directory
+structure of the json package is shown below:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">encoding/json</span>
<span style="color: #000000">├──</span> <span style="color: #000000">include</span>
<span style="color: #000000">│ </span> <span style="color: #000000">└──</span> <span style="color: #000000">json</span>
<span style="color: #000000">│ </span> <span style="color: #000000">└──</span> <span style="color: #000000">json</span>.<span style="color: #000000">h</span>
<span style="color: #000000">├──</span> <span style="color: #000000">pkg</span>.<span style="color: #000000">yml</span>
-<span style="color: #000000">└──</span> <span style="color: #000000">src</span>
- <span style="color: #000000">├──</span> <span style="color: #000000">json_decode</span>.<span style="color: #000000">c</span>
- <span style="color: #000000">├──</span> <span style="color: #000000">json_encode</span>.<span style="color: #000000">c</span>
- <span style="color: #000000">└──</span> <span style="color: #000000">test</span>
+<span style="color: #000000">├──</span> <span style="color: #000000">src</span>
+<span style="color: #000000">│ </span> <span style="color: #000000">├──</span> <span style="color: #000000">json_decode</span>.<span style="color: #000000">c</span>
+<span style="color: #000000">│ </span> <span style="color: #000000">└──</span> <span style="color: #000000">json_encode</span>.<span style="color: #000000">c</span>
+<span style="color: #000000">└──</span> <span style="color: #000000">test</span>
+ <span style="color: #000000">├──</span> <span style="color: #000000">pkg</span>.<span style="color: #000000">yml</span>
+ <span style="color: #000000">└──</span> <span style="color: #000000">src</span>
<span style="color: #000000">├──</span> <span style="color: #000000">test_json</span>.<span style="color: #000000">c</span>
- <span style="color: #000000">└──</span> <span style="color: #000000">test_json</span>.<span style="color: #000000">h</span>
+ <span style="color: #000000">├──</span> <span style="color: #000000">test_json</span>.<span style="color: #000000">h</span>
+ <span style="color: #000000">├──</span> <span style="color: #000000">test_json_utils</span>.<span style="color: #000000">c</span>
+ <span style="color: #000000">└──</span> <span style="color: #000000">testcases</span>
+ <span style="color: #000000">├──</span> <span style="color: #000000">json_simple_decode</span>.<span style="color: #000000">c</span>
+ <span style="color: #000000">└──</span> <span style="color: #000000">json_simple_encode</span>.<span style="color: #000000">c</span>
</pre></div>
-<h3 id="create-your-test-suite-code">Create Your Test Suite Code</h3>
-<p>Edit the <code>test_json.c</code> file and add your test suite definition. NOTE that
-the test suite code requires <code>#include <testutil/testutil.h></code> to get the
-Mynewt testutil definitions.</p>
-<p>Your test suite <code>test_json.c</code> file contains at a minimum two functions:</p>
-<ol>
-<li>A test Suite which is empty for now, but will contain calls to your test
-cases. </li>
-<li>A main function which must be <code>#ifdef</code>'d using <code>MYNEWT_SELFTEST</code> to ensure
-that is does not get compiled in when this test suite is run with
-test suites from other packages </li>
-</ol>
-<p>Below shows the contents of the <code>test_json.c</code> file.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#include <testutil/testutil.h></span>
+<p>The top-level <code>test</code> directory contains the json test package. To create a
+test package for the datetime package, we need to create a similar package
+called <code>time/datetime/test</code>.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ newt pkg new time/datetime/test -t unittest
+Download package template for package type pkg.
+Package successfuly installed into /home/me/mynewt-core/time/datetime/test.
+</pre></div>
+
+
+<p>We now have a test package inside <code>time/datetime</code>:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">time/datetime
+├── include
+│ └── datetime
+│ └── datetime.h
+├── pkg.yml
+├── src
+│ └── datetime.c
+└── test
+ ├── README.md
+ ├── pkg.yml
+ ├── src
+ │ └── main.c
+ └── syscfg.yml
+</pre></div>
-<span style="color: #000000">TEST_SUITE</span>(<span style="color: #000000">test_json_suite</span>) {
- <span style="color: #177500">/* empty for now, add test cases later */</span>
+
+<p>There is one modification we need to make to the new package before we can
+start writing unit test code. A test package needs access to the code it will
+be testing, so we need to add a dependency on
+<code>@apache-mynewt-core/time/datetime</code> to our <code>pkg.yml</code> file:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">pkg.name: "time/datetime/test"
+pkg.type: unittest
+pkg.description: "Description of your package"
+pkg.author: "You <you@you.org>"
+pkg.homepage: "http://your-url.org/"
+pkg.keywords:
+
+pkg.deps:
+ - '@apache-mynewt-core/test/testutil'
+<span style="background-color: #ffffcc"> - '@apache-mynewt-core/time/datetime'
+</span>
+pkg.deps.SELFTEST:
+ - '@apache-mynewt-core/sys/console/stub'
+</pre></div>
+
+
+<p>While we have the <code>pkg.yml</code> file open, let's take a look at what newt filled in automatically:</p>
+<ul>
+<li><code>pkg.type: unittest</code> designates this as a test package. A <em>test package</em> is
+ special in that it can be built and executed using the <code>newt test</code> command.</li>
+<li>A test package always depends on <code>@apache-mynewt-core/test/testutil</code>. The
+ testutil library provides the tools necessary for verifying package behavior, </li>
+<li>The <code>SELFTEST</code> suffix indicates that a setting should only be applied when the <code>newt test</code> command is used.</li>
+</ul>
+<p>Regarding the conditional dependency on <code>sys/console/stub</code>, the datetime
+package requires some form of console to function. In a regular application,
+the console dependency would be supplied by a higher order package. Because
+<code>newt test</code> runs the test package without an application present, the test
+package needs to supply all unresolved dependencies itself when run in
+self-test mode.</p>
+<h2 id="create-your-test-suite-code">Create Your Test Suite Code</h2>
+<p>We will be adding a <em>test suite</em> to the <code>main.c</code> file. The test suite will be empty for now. We also need to invoke the test suite from <code>main()</code>.</p>
+<p>Our <code>main.c</code> file now looks like this:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#include "sysinit/sysinit.h"</span>
+<span style="color: #633820">#include "testutil/testutil.h"</span>
+
+<span style="color: #000000">TEST_SUITE</span>(<span style="color: #000000">test_datetime_suite</span>) {
+ <span style="color: #177500">/* Empty for now; add test cases later. */</span>
}
-<span style="color: #633820">#ifdef MYNEWT_SELFTEST</span>
+<span style="color: #633820">#if MYNEWT_VAL(SELFTEST)</span>
<span style="color: #A90D91">int</span>
<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**argv</span>)
{
- <span style="color: #000000">tu_config</span>.<span style="color: #000000">tc_print_results</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">1</span>;
- <span style="color: #000000">tu_init</span>();
- <span style="color: #000000">test_json_suite</span>();
+ <span style="color: #177500">/* Initialize all packages. */</span>
+ <span style="color: #000000">sysinit</span>();
+
+ <span style="color: #000000">test_datetime_suite</span>();
+
+ <span style="color: #177500">/* Indicate whether all test cases passed. */</span>
<span style="color: #A90D91">return</span> <span style="color: #000000">tu_any_failed</span>;
}
<span style="color: #633820">#endif</span>
</pre></div>
-<h3 id="try-it-out">Try It Out</h3>
-<p>At this point, you have a working test suite with <strong>no</strong> tests.<br />
-This will by default pass the test. Your output will look
-something like this.</p>
-<p>You can use the <code>newt test</code> command to run the unit tests for any package.<br />
-Just include the package name. These unit tests run via the project
-<code>unittest</code> which is a native project automatically included in the core
-os package. Below shows some of the test output of this command.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">$</span> <span style="color: #000000">newt</span> <span style="color: #000000">test</span> <span style="color: #000000">libs/json</span>
-<span style="color: #000000">Archiving</span> <span style="color: #000000">util</span>.<span style="color: #000000">a</span>
-<span style="color: #000000">Linking</span> <span style="color: #000000">test_json</span>
-<span style="color: #000000">Testing</span> <span style="color: #000000">package</span> <span style="color: #000000">libs/json</span>
-<span style="color: #000000">Test</span> ...<span style="color: #000000">/bin/unittest/libs/json/test_json</span> <span style="color: #000000">ok!</span>
+<h2 id="try-it-out">Try It Out</h2>
+<p>We now have a working test suite with no tests. Let's make sure we get a passing result when we run <code>newt test</code>:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ newt test time/datetime
+<build output>
+Executing test: /home/me/mynewt-core/bin/targets/unittest/time_datetime_test/app/time/datetime/test/time_datetime_test.elf
+Passed tests: [time/datetime/test]
+All tests passed
</pre></div>
-<h3 id="create-a-test">Create a Test</h3>
+<h2 id="create-a-test">Create a Test</h2>
<p>To create a test within your test suite, there are two things to do.</p>
<ol>
-<li>Add the functions to your test suite</li>
-<li>Implement the function using the <code>testutil</code> macros</li>
+<li>Implement the test case function using the <code>testutil</code> macros.</li>
+<li>Call the test case function from within the test suite.</li>
</ol>
-<p>For this tutorial we will create two functions: one to test a simple json
-encode and one to test the decode of this simple message to ensure its
-coherent.</p>
-<p>Follow These steps;</p>
-<p>1. Create function prototypes in <code>test_json.h</code> for your test functions.
-A macro in <code>testutil.h</code> hides the actual prototype, but as of this writing
-the prototype is <code>int test_func(void);</code>. </p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#ifndef TEST_JSON_H</span>
-<span style="color: #633820">#define TEST_JSON_H</span>
-
-<span style="color: #000000">TEST_CASE_DECL</span>(<span style="color: #000000">test_json_simple_encode</span>);
-<span style="color: #000000">TEST_CASE_DECL</span>(<span style="color: #000000">test_json_simple_decode</span>);
-
-<span style="color: #633820">#endif /* TEST_JSON_H </span>
+<p>For this tutorial we will create a test case to verify the <code>datetime_parse()</code>
+function. The <code>datetime_parse()</code> function is declared as follows:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/**</span>
+<span style="color: #177500"> * Parses an RFC 3339 datetime string. Some examples of valid datetime strings</span>
+<span style="color: #177500"> * are:</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00 UTC time (implicit)</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00Z UTC time (explicit)</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00-08:00 PST timezone</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00.1 fractional seconds</span>
+<span style="color: #177500"> * 2016-03-02T22:44:00.101+05:30 fractional seconds with timezone</span>
+<span style="color: #177500"> *</span>
+<span style="color: #177500"> * On success, the two output parameters are filled in (tv and tz).</span>
+<span style="color: #177500"> *</span>
+<span style="color: #177500"> * @return 0 on success;</span>
+<span style="color: #177500"> * nonzero on parse error.</span>
+<span style="color: #177500"> */</span>
+<span style="color: #A90D91">int</span>
+<span style="color: #000000">datetime_parse</span>(<span style="color: #A90D91">const</span> <span style="color: #A90D91">char</span> <span style="color: #000000">*input</span>, <span style="color: #A90D91">struct</span> <span style="color: #000000">os_timeval</span> <span style="color: #000000">*tv</span>, <span style="color: #A90D91">struct</span> <span style="color: #000000">os_timezone</span> <span style="color: #000000">*tz</span>)
</pre></div>
-<p>2. create a new file <code>test_json_simple.c</code> to define these two functions. For
-now you can stub these functions. Below shows the contents of this file.
-The functions are defined using macros which reference back to the
-<code>testutil</code> library so the test can be enumerated and recorded automatically.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#include "testutil/testutil.h"</span>
-<span style="color: #633820">#include "test_json.h"</span>
+<p>Our test case should make sure this function rejects invalid input, and that it
+parses valid input correctly. The updated <code>main.c</code> file looks like this:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#include "sysinit/sysinit.h"</span>
+<span style="color: #633820">#include "testutil/testutil.h"</span>
+<span style="color: #633820">#include "os/os_time.h"</span>
+<span style="color: #633820">#include "datetime/datetime.h"</span>
-<span style="color: #000000">TEST_CASE</span>(<span style="color: #000000">test_json_simple_encode</span>) {
+<span style="color: #000000">TEST_SUITE</span>(<span style="color: #000000">test_datetime_suite</span>)
+{
+ <span style="color: #000000">test_datetime_parse_simple</span>();
}
-<span style="color: #000000">TEST_CASE</span>(<span style="color: #000000">test_json_simple_decode</span>) {
+<span style="color: #000000">TEST_CASE</span>(<span style="color: #000000">test_datetime_parse_simple</span>)
+{
+ <span style="color: #A90D91">struct</span> <span style="color: #000000">os_timezone</span> <span style="color: #000000">tz</span>;
+ <span style="color: #A90D91">struct</span> <span style="color: #000000">os_timeval</span> <span style="color: #000000">tv</span>;
+ <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
+
+ <span style="color: #177500">/*** Valid input. */</span>
+
+ <span style="color: #177500">/* No timezone; UTC implied. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2017-06-28T22:37:59"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT_FATAL</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tv</span>.<span style="color: #000000">tv_sec</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">1498689479</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tv</span>.<span style="color: #000000">tv_usec</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tz</span>.<span style="color: #000000">tz_minuteswest</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tz</span>.<span style="color: #000000">tz_dsttime</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/* PDT timezone. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2013-12-05T02:43:07-07:00"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT_FATAL</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tv</span>.<span style="color: #000000">tv_sec</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">1386236587</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tv</span>.<span style="color: #000000">tv_usec</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tz</span>.<span style="color: #000000">tz_minuteswest</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">420</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">tz</span>.<span style="color: #000000">tz_dsttime</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/*** Invalid input. */</span>
+
+ <span style="color: #177500">/* Nonsense. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"abc"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/* Date-only. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2017-01-02"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/* Zero month. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2017-00-28T22:37:59"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
+
+ <span style="color: #177500">/* 13 month. */</span>
+ <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">datetime_parse</span>(<span style="color: #C41A16">"2017-13-28T22:37:59"</span>, <span style="color: #000000">&tv</span>, <span style="color: #000000">&tz</span>);
+ <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>);
}
-<span style="color: #633820">#endif /* TEST_JSON_H </span>
-</pre></div>
+<span style="color: #633820">#if MYNEWT_VAL(SELFTEST)</span>
+<span style="color: #A90D91">int</span>
+<span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span> <span style="color: #000000">**argv</span>)
+{
+ <span style="color: #177500">/* Initialize all packages. */</span>
+ <span style="color: #000000">sysinit</span>();
-<p>3. Add the tests to your test suite in <code>test_json.c</code> as shown below.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">TEST_SUITE</span>(<span style="color: #000000">test_json_suite</span>) {
- <span style="color: #000000">test_json_simple_encode</span>();
- <span style="color: #000000">test_json_simple_decode</span>();
-}
-</pre></div>
-
+ <span style="color: #000000">test_datetime_suite</span>();
-<p>Your test suite should still pass as shown below</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">$newt</span> <span style="color: #000000">test</span> <span style="color: #000000">libs/json</span>
-<span style="color: #000000">Testing</span> <span style="color: #000000">package</span> <span style="color: #000000">libs/json</span>
-<span style="color: #000000">Test</span> ...<span style="color: #000000">/bin/unittest/libs/json/test_json</span> <span style="color: #000000">ok!</span>
+ <span style="color: #177500">/* Indicate whether all test cases passed. */</span>
+ <span style="color: #A90D91">return</span> <span style="color: #000000">tu_any_failed</span>;
+}
+<span style="color: #633820">#endif</span>
</pre></div>
-<h2 id="add-contents-to-your-tests">Add Contents to your Tests</h2>
-<p>At this point, you can add contents to your test and verify that
-the test suites pass. For now, lets just add a simple failure to show
-what it would look like when running from Newt.</p>
+<p>Take a few minutes to review the above code. Then keep reading for some
+specifics.</p>
+<h3 id="asserting">Asserting</h3>
+<p>The <code>test/testutil</code> package provides two tools for verifying the correctness of a package:</p>
<ul>
-<li>Edit <code>test_json_simple.c</code> and add a <code>TEST_ASSERT</code> to a test function. The
-test assert will fail if its argument is <code>false</code>.</li>
+<li><code>TEST_ASSERT</code></li>
+<li><code>TEST_ASSERT_FATAL</code></li>
</ul>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">TEST_CASE</span>(<span style="color: #000000">test_json_simple_encode</span>) {
- <span style="color: #000000">TEST_ASSERT</span>(<span style="color: #1C01CE">0</span>);
-}
-</pre></div>
-
-
-<p>When running newt, you will see the test suite fails with something like
-the message shown below.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #000000">Testing</span> <span style="color: #000000">package</span> <span style="color: #000000">libs/json</span>
-[<span style="color: #000000">FAIL</span>] <span style="color: #000000">test_json_suite/</span>(<span style="color: #000000">null</span>) <span style="color: #000000">|test_json_simple</span>.<span style="color: #000000">c</span>:<span style="color: #1C01CE">24</span><span style="color: #000000">|</span> <span style="color: #000000">failed</span> <span style="color: #000000">assertion</span>: <span style="color: #1C01CE">0</span>
-<span style="color: #000000">Error</span>: <span style="color: #000000">Test</span> <span style="color: #000000">crashed</span>: ..<span style="color: #000000">/bin/unittest/libs/json/test_json</span>
-<span style="color: #000000">exit</span> <span style="color: #000000">status</span> <span style="color: #1C01CE">1</span>
+<p>Both of these macros check if the supplied condition is true. They differ in
+how they behave when the condition is not true. On failure, <code>TEST_ASSERT</code>
+reports the error and proceeds with the remainder of the test case.
+<code>TEST_ASSERT_FATAL</code>, on the other hand, aborts the test case on failure.</p>
+<p>The general rule is to only use <code>TEST_ASSERT_FATAL</code> when subsequent assertions
+depend on the condition being checked. For example, when <code>datetime_parse()</code> is
+expected to succeed, the return code is checked with <code>TEST_ASSERT_FATAL</code>. If
+<code>datetime_parse()</code> unexpectedly failed, the contents of the <code>tv</code> and <code>tz</code>
+objects would be indeterminate, so it is desirable to abort the test instead of
+checking them and reporting spurious failures.</p>
+<h3 id="scaling-up">Scaling Up</h3>
+<p>The above example is small and self contained, so it is reasonable to put
+everything in a single C file. A typical package will need a lot more test
+code, and it helps to follow some conventions to maintain organization. Let's
+take a look at a more realistic example. Here is the directory structure of
+the <code>fs/nffs/test</code> package:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">fs/nffs/test
+├── pkg.yml
+└── src
+ ├── nffs_test.c
+ ├── nffs_test.h
+ ├── nffs_test_debug.c
+ ├── nffs_test_priv.h
+ ├── nffs_test_system_01.c
+ ├── nffs_test_utils.c
+ ├── nffs_test_utils.h
+ └── testcases
+ ├── append_test.c
+ ├── cache_large_file_test.c
+ ├── corrupt_block_test.c
+ ├── corrupt_scratch_test.c
+ ├── gc_on_oom_test.c
+ ├── gc_test.c
+ ├── incomplete_block_test.c
+ ├── large_system_test.c
+ ├── large_unlink_test.c
+ ├── large_write_test.c
+ ├── long_filename_test.c
+ ├── lost_found_test.c
+ ├── many_children_test.c
+ ├── mkdir_test.c
+ ├── open_test.c
+ ├── overwrite_many_test.c
+ ├── overwrite_one_test.c
+ ├── overwrite_three_test.c
+ ├── overwrite_two_test.c
+ ├── read_test.c
+ ├── readdir_test.c
+ ├── rename_test.c
+ ├── split_file_test.c
+ ├── truncate_test.c
+ ├── unlink_test.c
+ └── wear_level_test.c
</pre></div>
+<p>The <code>fs/nffs/test</code> package follows these conventions:</p>
+<ol>
+<li>A maximum of one test case per C file.</li>
+<li>Each test case file goes in the <code>testcases</code> subdirectory.</li>
+<li>Test suites and utility functions go directly in the <code>src</code> directory.</li>
+</ol>
+<p>Test packages contributed to the Mynewt project should follow these conventions.</p>
<h2 id="congratulations">Congratulations</h2>
-<p>Now you can begin the work of adding your test cases and test.</p>
-<h2 id="testing-on-your-target">Testing on your target</h2>
+<p>Now you can begin the work of validating your packages.</p>
<div class="row">
--
To stop receiving notification emails like this one, please contact
['"commits@mynewt.apache.org" <co...@mynewt.apache.org>'].