Skip to content

Commit 8ce76e1

Browse files
author
Paul Sexton
committed
docs(2016b compatibility): add section about 2016b changes
* New documentation file about changes needed for 2016b+ * Example code referenced from documentation * HTML version * Referenced in TOC and front page
1 parent 699bcc2 commit 8ce76e1

8 files changed

+297
-0
lines changed

‎doc/compatibilityWith2016b.m

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
%% <../index.html MATLAB xUnit Test Framework>: Compatibility with R2016b
2+
% Significant changes were made to MATLAB in R2016b that affect how xUnit
3+
% works. If you wrote tests using version 4.0.0 or earlier, you may need
4+
% to make slight changes to your tests to make them work on 2016b and
5+
% subsequent releases.
6+
%
7+
% An incredible amount of effort was expended trying to find a solution that
8+
% would allow all existing tests to continue to run on 2016b and on previous versions,
9+
% with no changes, but we don't believe that to be possible. (Although you
10+
% are welcome to try, and submit a pull request if you succeed.)
11+
%
12+
% Listed below are the different scenarios you may be in, and what to do
13+
% about it.
14+
15+
%% I use class-based tests
16+
% My tests start like this:
17+
18+
dbtype examples_2016b_compatibility/TestUsingClasses.m 1
19+
20+
%%
21+
% Five points for using classes! You can stop reading now. You're not affected.
22+
23+
%% I use function-based tests
24+
% My tests start like this:
25+
26+
dbtype examples_2016b_compatibility/testUsingFunctionsDeprecated.m 1:2
27+
28+
%%
29+
% The way this worked is that |inittestsuite| was actually a script, called
30+
% from within the scope of your test function. And as a result of that, it
31+
% had access to all the subfunctions that were your actual tests, and was
32+
% able to build a test suite that way. Starting with 2016b, scripts called
33+
% from functions no longer have access to the caller's scope, and this
34+
% strategy will not (can not) work.
35+
%
36+
% The replacement is to construct a test suite out of function handles,
37+
% while still in the scope of |testUsingFunctionsDeprecated|. In 2014b and
38+
% newer, the built-in function |localfunctions| can be used. In 2013b and
39+
% 2014a, |localfunctions| is not able to see functions inside of packages,
40+
% and is somewhat broken for our purposes. In 2013a and older releases,
41+
% |localfunctions| doesn't exist.
42+
%
43+
% This gisves us the following three situations you may be in.
44+
45+
%% I use function-based tests (and I only care about 2016a or older)
46+
% You _technically_ don't need to change anything. Your tests will continue
47+
% to work. However, |inittestsuite| is now deprecated, and you will receive
48+
% warnings when your tests run. This functionality will be removed in a
49+
% future major release.
50+
51+
%% I use function-based tests (and I only care about 2013b or newer)
52+
% The replacement for |inittestsuite| is |buildFunctionHandleTestSuite|,
53+
% and you will pipe the cell array from |localfunctions| into it.
54+
55+
dbtype examples_2016b_compatibility/testUsingFunctions.m 1:2
56+
57+
%% I use function-based tests (and I don't fall into either prior category)
58+
% If you have function-based tests that you want or need to run against
59+
% *both* 2016b or newer *and* 2013a or older, then you have additional work
60+
% to do. You will have to first create the cell array of function handles,
61+
% using some seriously fugly syntax. Then you can call
62+
% |buildFunctionHandleTestSuite| with the cell array you created.
63+
64+
dbtype examples_2016b_compatibility/testUsingFunctionsAndSubFunHandles.m 1:4
65+
66+
%%
67+
% Unfortunately, there is no other way to handle all test suite types
68+
% across that many releases.
69+
70+
%%
71+
% <../index.html Back to MATLAB xUnit Test Framework>

‎doc/examples_2016b_compatibility/TestUsingClasses.m

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
classdef TestUsingClasses < TestCase
2+
3+
properties
4+
fh
5+
end
6+
7+
methods
8+
function self = TestUsingClasses(name)
9+
self = self@TestCase(name);
10+
end
11+
12+
function setUp(self)
13+
self.fh = figure;
14+
end
15+
16+
function tearDown(self)
17+
delete(self.fh);
18+
end
19+
20+
function testColormapColumns(self)
21+
assertEqual(size(get(self.fh, 'Colormap'), 2), 3);
22+
end
23+
24+
function testPointer(self)
25+
assertEqual(get(self.fh, 'Pointer'), 'arrow');
26+
end
27+
end
28+
end

‎doc/examples_2016b_compatibility/testUsingFunctions.m

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
function testSuite = testUsingFunctions
2+
testSuite = buildFunctionHandleTestSuite(localfunctions);
3+
4+
function testFliplrMatrix
5+
in = magic(3);
6+
assertEqual(fliplr(in), in(:, [3 2 1]));
7+
8+
function testFliplrVector
9+
assertEqual(fliplr([1 4 10]), [10 4 1]);
10+

‎doc/examples_2016b_compatibility/testUsingFunctionsAndSubFunHandles.m

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
function testSuite = testUsingFunctionsAndSubFunHandles
2+
localFunctionHandles = cellfun(@str2func, ...
3+
which('-subfun', mfilename('fullpath')), 'UniformOutput', false);
4+
testSuite = buildFunctionHandleTestSuite(localFunctionHandles);
5+
6+
function testFliplrMatrix
7+
in = magic(3);
8+
assertEqual(fliplr(in), in(:, [3 2 1]));
9+
10+
function testFliplrVector
11+
assertEqual(fliplr([1 4 10]), [10 4 1]);

‎doc/examples_2016b_compatibility/testUsingFunctionsDeprecated.m

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
function testSuite = testUsingFunctionsDeprecated
2+
inittestsuite
3+
4+
function testFliplrMatrix
5+
in = magic(3);
6+
assertEqual(fliplr(in), in(:, [3 2 1]));
7+
8+
function testFliplrVector
9+
assertEqual(fliplr([1 4 10]), [10 4 1]);
10+

‎doc/helptoc.xml

+3
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,9 @@
3636
<tocitem target="html/exTestCaseSearching.html">
3737
How xUnit Searches for Test Cases
3838
</tocitem>
39+
<tocitem target="html/compatibilityWith2016b.html">
40+
How to Alter Your Tests for 2016b
41+
</tocitem>
3942
<tocitem target="http://psexton.github.io/matlab-xunit/" image="$toolbox/matlab/icons/webicon.gif">
4043
Latest Version
4144
</tocitem>

‎doc/html/compatibilityWith2016b.html

+160
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
2+
<!DOCTYPE html
3+
PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4+
<html><head>
5+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6+
<!--
7+
This HTML was auto-generated from MATLAB code.
8+
To make changes, update the MATLAB code and republish this document.
9+
--><title>MATLAB xUnit Test Framework: Compatibility with R2016b</title><meta name="generator" content="MATLAB 9.0"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="DC.date" content="2016-12-23"><meta name="DC.source" content="compatibilityWith2016b.m"><style type="text/css">
10+
html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;vertical-align:baseline;background:transparent}body{line-height:1}ol,ul{list-style:none}blockquote,q{quotes:none}blockquote:before,blockquote:after,q:before,q:after{content:'';content:none}:focus{outine:0}ins{text-decoration:none}del{text-decoration:line-through}table{border-collapse:collapse;border-spacing:0}
11+
12+
html { min-height:100%; margin-bottom:1px; }
13+
html body { height:100%; margin:0px; font-family:Arial, Helvetica, sans-serif; font-size:10px; color:#000; line-height:140%; background:#fff none; overflow-y:scroll; }
14+
html body td { vertical-align:top; text-align:left; }
15+
16+
h1 { padding:0px; margin:0px 0px 25px; font-family:Arial, Helvetica, sans-serif; font-size:1.5em; color:#d55000; line-height:100%; font-weight:normal; }
17+
h2 { padding:0px; margin:0px 0px 8px; font-family:Arial, Helvetica, sans-serif; font-size:1.2em; color:#000; font-weight:bold; line-height:140%; border-bottom:1px solid #d6d4d4; display:block; }
18+
h3 { padding:0px; margin:0px 0px 5px; font-family:Arial, Helvetica, sans-serif; font-size:1.1em; color:#000; font-weight:bold; line-height:140%; }
19+
20+
a { color:#005fce; text-decoration:none; }
21+
a:hover { color:#005fce; text-decoration:underline; }
22+
a:visited { color:#004aa0; text-decoration:none; }
23+
24+
p { padding:0px; margin:0px 0px 20px; }
25+
img { padding:0px; margin:0px 0px 20px; border:none; }
26+
p img, pre img, tt img, li img, h1 img, h2 img { margin-bottom:0px; }
27+
28+
ul { padding:0px; margin:0px 0px 20px 23px; list-style:square; }
29+
ul li { padding:0px; margin:0px 0px 7px 0px; }
30+
ul li ul { padding:5px 0px 0px; margin:0px 0px 7px 23px; }
31+
ul li ol li { list-style:decimal; }
32+
ol { padding:0px; margin:0px 0px 20px 0px; list-style:decimal; }
33+
ol li { padding:0px; margin:0px 0px 7px 23px; list-style-type:decimal; }
34+
ol li ol { padding:5px 0px 0px; margin:0px 0px 7px 0px; }
35+
ol li ol li { list-style-type:lower-alpha; }
36+
ol li ul { padding-top:7px; }
37+
ol li ul li { list-style:square; }
38+
39+
.content { font-size:1.2em; line-height:140%; padding: 20px; }
40+
41+
pre, code { font-size:12px; }
42+
tt { font-size: 1.2em; }
43+
pre { margin:0px 0px 20px; }
44+
pre.codeinput { padding:10px; border:1px solid #d3d3d3; background:#f7f7f7; }
45+
pre.codeoutput { padding:10px 11px; margin:0px 0px 20px; color:#4c4c4c; }
46+
pre.error { color:red; }
47+
48+
@media print { pre.codeinput, pre.codeoutput { word-wrap:break-word; width:100%; } }
49+
50+
span.keyword { color:#0000FF }
51+
span.comment { color:#228B22 }
52+
span.string { color:#A020F0 }
53+
span.untermstring { color:#B20000 }
54+
span.syscmd { color:#B28C00 }
55+
56+
.footer { width:auto; padding:10px 0px; margin:25px 0px 0px; border-top:1px dotted #878787; font-size:0.8em; line-height:140%; font-style:italic; color:#878787; text-align:left; float:none; }
57+
.footer p { margin:0px; }
58+
.footer a { color:#878787; }
59+
.footer a:hover { color:#878787; text-decoration:underline; }
60+
.footer a:visited { color:#878787; }
61+
62+
table th { padding:7px 5px; text-align:left; vertical-align:middle; border: 1px solid #d6d4d4; font-weight:bold; }
63+
table td { padding:7px 5px; text-align:left; vertical-align:top; border:1px solid #d6d4d4; }
64+
65+
66+
67+
68+
69+
</style></head><body><div class="content"><h1><a href="../index.html">MATLAB xUnit Test Framework</a>: Compatibility with R2016b</h1><!--introduction--><p>Significant changes were made to MATLAB in R2016b that affect how xUnit works. If you wrote tests using version 4.0.0 or earlier, you may need to make slight changes to your tests to make them work on 2016b and subsequent releases.</p><p>An incredible amount of effort was expended trying to find a solution that would allow all existing tests to continue to run on 2016b and on previous versions, with no changes, but we don't believe that to be possible. (Although you are welcome to try, and submit a pull request if you succeed.)</p><p>Listed below are the different scenarios you may be in, and what to do about it.</p><!--/introduction--><h2>Contents</h2><div><ul><li><a href="#1">I use class-based tests</a></li><li><a href="#3">I use function-based tests</a></li><li><a href="#5">I use function-based tests (and I only care about 2016a or older)</a></li><li><a href="#6">I use function-based tests (and I only care about 2013b or newer)</a></li><li><a href="#7">I use function-based tests (and I don't fall into either prior category)</a></li></ul></div><h2>I use class-based tests<a name="1"></a></h2><p>My tests start like this:</p><pre class="codeinput">dbtype <span class="string">examples_2016b_compatibility/TestUsingClasses.m</span> <span class="string">1</span>
70+
</pre><pre class="codeoutput">
71+
1 classdef TestUsingClasses &lt; TestCase
72+
</pre><p>Five points for using classes! You can stop reading now. You're not affected.</p><h2>I use function-based tests<a name="3"></a></h2><p>My tests start like this:</p><pre class="codeinput">dbtype <span class="string">examples_2016b_compatibility/testUsingFunctionsDeprecated.m</span> <span class="string">1:2</span>
73+
</pre><pre class="codeoutput">
74+
1 function testSuite = testUsingFunctionsDeprecated
75+
2 inittestsuite
76+
</pre><p>The way this worked is that <tt>inittestsuite</tt> was actually a script, called from within the scope of your test function. And as a result of that, it had access to all the subfunctions that were your actual tests, and was able to build a test suite that way. Starting with 2016b, scripts called from functions no longer have access to the caller's scope, and this strategy will not (can not) work.</p><p>The replacement is to construct a test suite out of function handles, while still in the scope of <tt>testUsingFunctionsDeprecated</tt>. In 2014b and newer, the built-in function <tt>localfunctions</tt> can be used. In 2013b and 2014a, <tt>localfunctions</tt> is not able to see functions inside of packages, and is somewhat broken for our purposes. In 2013a and older releases, <tt>localfunctions</tt> doesn't exist.</p><p>This gisves us the following three situations you may be in.</p><h2>I use function-based tests (and I only care about 2016a or older)<a name="5"></a></h2><p>You <i>technically</i> don't need to change anything. Your tests will continue to work. However, <tt>inittestsuite</tt> is now deprecated, and you will receive warnings when your tests run. This functionality will be removed in a future major release.</p><h2>I use function-based tests (and I only care about 2013b or newer)<a name="6"></a></h2><p>The replacement for <tt>inittestsuite</tt> is <tt>buildFunctionHandleTestSuite</tt>, and you will pipe the cell array from <tt>localfunctions</tt> into it.</p><pre class="codeinput">dbtype <span class="string">examples_2016b_compatibility/testUsingFunctions.m</span> <span class="string">1:2</span>
77+
</pre><pre class="codeoutput">
78+
1 function testSuite = testUsingFunctions
79+
2 testSuite = buildFunctionHandleTestSuite(localfunctions);
80+
</pre><h2>I use function-based tests (and I don't fall into either prior category)<a name="7"></a></h2><p>If you have function-based tests that you want or need to run against <b>both</b> 2016b or newer <b>and</b> 2013a or older, then you have additional work to do. You will have to first create the cell array of function handles, using some seriously fugly syntax. Then you can call <tt>buildFunctionHandleTestSuite</tt> with the cell array you created.</p><pre class="codeinput">dbtype <span class="string">examples_2016b_compatibility/testUsingFunctionsAndSubFunHandles.m</span> <span class="string">1:4</span>
81+
</pre><pre class="codeoutput">
82+
1 function testSuite = testUsingFunctionsAndSubFunHandles
83+
2 localFunctionHandles = cellfun(@str2func, ...
84+
3 which('-subfun', mfilename('fullpath')), 'UniformOutput', false);
85+
4 testSuite = buildFunctionHandleTestSuite(localFunctionHandles);
86+
</pre><p>Unfortunately, there is no other way to handle all test suite types across that many releases.</p><p><a href="../index.html">Back to MATLAB xUnit Test Framework</a></p><p class="footer"><br><a href="http://www.mathworks.com/products/matlab/">Published with MATLAB&reg; R2016a</a><br></p></div><!--
87+
##### SOURCE BEGIN #####
88+
%% <../index.html MATLAB xUnit Test Framework>: Compatibility with R2016b
89+
% Significant changes were made to MATLAB in R2016b that affect how xUnit
90+
% works. If you wrote tests using version 4.0.0 or earlier, you may need
91+
% to make slight changes to your tests to make them work on 2016b and
92+
% subsequent releases.
93+
%
94+
% An incredible amount of effort was expended trying to find a solution that
95+
% would allow all existing tests to continue to run on 2016b and on previous versions,
96+
% with no changes, but we don't believe that to be possible. (Although you
97+
% are welcome to try, and submit a pull request if you succeed.)
98+
%
99+
% Listed below are the different scenarios you may be in, and what to do
100+
% about it.
101+
102+
%% I use class-based tests
103+
% My tests start like this:
104+
105+
dbtype examples_2016b_compatibility/TestUsingClasses.m 1
106+
107+
%%
108+
% Five points for using classes! You can stop reading now. You're not affected.
109+
110+
%% I use function-based tests
111+
% My tests start like this:
112+
113+
dbtype examples_2016b_compatibility/testUsingFunctionsDeprecated.m 1:2
114+
115+
%%
116+
% The way this worked is that |inittestsuite| was actually a script, called
117+
% from within the scope of your test function. And as a result of that, it
118+
% had access to all the subfunctions that were your actual tests, and was
119+
% able to build a test suite that way. Starting with 2016b, scripts called
120+
% from functions no longer have access to the caller's scope, and this
121+
% strategy will not (can not) work.
122+
%
123+
% The replacement is to construct a test suite out of function handles,
124+
% while still in the scope of |testUsingFunctionsDeprecated|. In 2014b and
125+
% newer, the built-in function |localfunctions| can be used. In 2013b and
126+
% 2014a, |localfunctions| is not able to see functions inside of packages,
127+
% and is somewhat broken for our purposes. In 2013a and older releases,
128+
% |localfunctions| doesn't exist.
129+
%
130+
% This gisves us the following three situations you may be in.
131+
132+
%% I use function-based tests (and I only care about 2016a or older)
133+
% You _technically_ don't need to change anything. Your tests will continue
134+
% to work. However, |inittestsuite| is now deprecated, and you will receive
135+
% warnings when your tests run. This functionality will be removed in a
136+
% future major release.
137+
138+
%% I use function-based tests (and I only care about 2013b or newer)
139+
% The replacement for |inittestsuite| is |buildFunctionHandleTestSuite|,
140+
% and you will pipe the cell array from |localfunctions| into it.
141+
142+
dbtype examples_2016b_compatibility/testUsingFunctions.m 1:2
143+
144+
%% I use function-based tests (and I don't fall into either prior category)
145+
% If you have function-based tests that you want or need to run against
146+
% *both* 2016b or newer *and* 2013a or older, then you have additional work
147+
% to do. You will have to first create the cell array of function handles,
148+
% using some seriously fugly syntax. Then you can call
149+
% |buildFunctionHandleTestSuite| with the cell array you created.
150+
151+
dbtype examples_2016b_compatibility/testUsingFunctionsAndSubFunHandles.m 1:4
152+
153+
%%
154+
% Unfortunately, there is no other way to handle all test suite types
155+
% across that many releases.
156+
157+
%%
158+
% <../index.html Back to MATLAB xUnit Test Framework>
159+
##### SOURCE END #####
160+
--></body></html>

‎doc/xunit_product_page.html

+4
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,10 @@ <h2>Getting Started</h2>
5353
<a href="html/exRunTestsInPackage.html">How to Run Tests in a Package</a>
5454
</p>
5555

56+
<p>
57+
<a href="html/compatibilityWith2016b.html">How to Alter Your Tests for 2016b</a>
58+
</p>
59+
5660
<h2>Advanced Usage</h2>
5761

5862
<p>

0 commit comments

Comments
 (0)