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 <[email protected]>
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 <[email protected]>"
+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 <[email protected]>"
+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
['"[email protected]" <[email protected]>'].
