Test/Device/Chip/Adapter.pm

filter: Statementstmt 77.4% 127 / 164 Branchbran 70.0% 14 / 20 Conditioncond 36.3% 4 / 11 MC/DCmcdc 14.2% 1 / 7 Subroutinesub 76.3% 29 / 38 Podpod 6.6% 1 / 15 totaltotal 69.0% 176 / 255 CC 31 SCAR 11.5
CC
31
Cov
74%
txn
10.5
read
5.4
readwrite
5.4
CRAP 3.2
« Device/Chip/Base/RegisteredI2C.pm ↑ Summary Device/Chip.pm »
1 # You may distribute under the terms of either the GNU General Public License
2 # or the Artistic License (the same terms as Perl itself)
3 #
4 # (C) Paul Evans, 2015-2023 -- leonerd@leonerd.org.uk
5  
6 6 ▶use v5.26;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 6 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 6 ▶use Object::Pad 0.800;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 package Test::Device::Chip::Adapter 0.27;
11 class Test::Device::Chip::Adapter
12 6 ▶ :does(Device::Chip::Adapter);
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 6 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 6 ▶use Future::AsyncAwait;
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 6 ▶use Test::Future::Deferred;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 6 ▶use List::Util 1.33 qw( first any );
Subroutine BEGIN: called CC=1 SCAR=0.0
20 6 ▶use Test::Builder;
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 6 ▶use Test::ExpectAndCheck::Future;
Subroutine BEGIN: called CC=1 SCAR=0.0
23  
24 =encoding UTF-8
25  
26 =head1 NAME
27  
28 C<Test::Device::Chip::Adapter> - unit testing on C<Device::Chip>
29  
30 =head1 SYNOPSIS
31  
32 =for highlighter language=perl
33  
34 use Test::More;
35 use Test::Device::Chip::Adapter;
36  
37 use Future::AsyncAwait;
38  
39 my $adapter = Test::Device::Chip::Adapter->new;
40  
41 $chip_under_test->mount( $adapter );
42  
43 # An actual test
44 $adapter->expect_readwrite( "123" )
45 ->will_done( "45" );
46  
47 is( await $chip->do_thing( "123" ), "45", 'result of ->do_thing' );
48  
49 $adapter->check_and_clear( '->do_thing' );
50  
51 =head1 DESCRIPTION
52  
53 This package provides a concrete implementation of L<Device::Chip::Adapter>
54 convenient for using in a unit-test script used to test a L<Device::Chip>
55 instance. It operates in an "expect-and-check" style of mocking, requiring the
56 test script to declare upfront what methods are expected to be called, and
57 what values they return.
58  
59 Futures returned by this module will not yield results immediately; they must
60 be awaited by a toplevel C<await> keyword or invoking the C<< ->get >> method.
61 This ensures that unit tests correctly perform the required asynchronisation.
62  
63 =cut
64  
65 6 field $_protocol;
66  
67 6 field $_controller;
68 6 field $_obj;
69 6 field $_txn_helper;
70  
71 ADJUST
72 {
73 ( $_controller, $_obj ) = Test::Device::Chip::Adapter::_TestController->create;
74 }
75  
76 1 ▶method make_protocol_GPIO ()
Subroutine make_protocol_GPIO: called CC=1 SCAR=0.0
Pod undocumented
77 {
78 1 $_protocol = "GPIO";
79 1 return Test::Future::Deferred->done_later( $self );
80 6 }
81  
82 3 ▶method make_protocol_I2C ()
Subroutine make_protocol_I2C: called CC=1 SCAR=0.0
Pod undocumented
83 {
84 3 $_protocol = "I2C";
85 3 return Test::Future::Deferred->done_later( $self );
86 6 }
87  
88 2 ▶method make_protocol_SPI ()
Subroutine make_protocol_SPI: called CC=1 SCAR=0.0
Pod undocumented
89 {
90 2 $_protocol = "SPI";
91 2 return Test::Future::Deferred->done_later( $self );
92 6 }
93  
94 1 ▶method make_protocol_UART ()
Subroutine make_protocol_UART: called CC=1 SCAR=0.0
Pod undocumented
95 {
96 1 $_protocol = "UART";
97 1 return Test::Future::Deferred->done_later( $self );
98 6 }
99  
100 0 ▶method configure ( % )
Subroutine configure: not called CC=1 SCAR=6.9
Pod undocumented
101 {
102 0 Test::Future::Deferred->done_later;
103 6 }
104  
105 6 field $_read_buffer;
106  
107 method use_read_buffer
108 1 ▶{
Subroutine use_read_buffer: called CC=1 SCAR=0.0
Pod undocumented
109 1 require Future::Buffer;
110 1 $_read_buffer = Future::Buffer->new;
111 6 }
112  
113 1 ▶method write_read_buffer ( $data )
Subroutine write_read_buffer: called CC=2 SCAR=7.0
Pod undocumented
114 {
115 1 ▶ ( $_read_buffer or croak "Read buffer is not enabled" )
Condition50%1/2
$_read_buffer || croak('Read buffer is not enabled')
l!l
10
MC/DC0%0/1
$_read_buffer || croak('Read buffer is not enabled')
$_read_buffer
Truth table50%1/2
A
A= $_read_buffer
Aresult
11
00
116 ->write( $data );
117 6 }
118  
119 =head1 EXPECTATIONS
120  
121 Each of the actual methods to be used by the L<Device::Chip> under test has an
122 associated expectation method, whose name is prefixed C<expect_>. Each returns
123 an expectation object, which has additional methods to control the behaviour of
124 that invocation.
125  
126 $exp = $adapter->expect_write_gpios( \%gpios );
127 $exp = $adapter->expect_read_gpios( \@gpios );
128 $exp = $adapter->expect_tris_gpios( \@gpios );
129 $exp = $adapter->expect_write( $bytes );
130 $exp = $adapter->expect_read( $len );
131 $exp = $adapter->expect_write_then_read( $bytes, $len );
132 $exp = $adapter->expect_readwrite( $bytes_out );
133 $exp = $adapter->expect_assert_ss;
134 $exp = $adapter->expect_release_ss;
135 $exp = $adapter->expect_readwrite_no_ss( $bytes_out );
136 $exp = $adapter->expect_write_no_ss( $bytes );
137  
138 The returned expectation object allows the test script to specify what such an
139 invocation should yield from its future.
140  
141 $exp->will_done( $bytes_in );
142 $exp->will_fail( $failure );
143  
144 Expectations for an atomic I²C transaction are performed inline, using the
145 following additional methods:
146  
147 $adapter->expect_txn_start();
148 $adapter->expect_txn_stop();
149  
150 As a lot of existing unit tests may have already been written to the API shape
151 provided by C<Test::ExpectAndCheck::Future> version 0.03, the expectation
152 object also recognises the C<returns> method as an alias to C<will_done>.
153  
154 $exp->returns( $bytes_in );
155  
156 This wrapper should be considered as a I<temporary> back-compatibility measure
157 however. It now prints a warning and perhaps will be removed entirely in a
158 later version. You should avoid using it in new code; just call C<will_done>
159 directly.
160  
161 =head2 Read Buffering
162  
163 I<Since version 0.26.>
164  
165 Testing with exact C<read> calls can be fragile; especially with UART-based
166 protocols, as it relies on exact ordering, buffer sizes, and so on. A more
167 flexible approach that leads to less brittle tests is to use a buffer.
168  
169 This first has to be enabled:
170  
171 $adapter->use_read_buffer;
172  
173 At this point, no C<read> method call will consume an expectation. Instead, it
174 will attempt to consume data from the read buffer. This can be provided by:
175  
176 $adapter->write_read_buffer( $data );
177  
178 =cut
179  
180 6 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=8.2
181 my %METHODS = (
182 sleep => [ undef,
183 [qw( GPIO SPI I2C UART )] ],
184 2 ▶ write_gpios => [ sub { my ( $v ) = @_; join ",", map { $v->{$_} ? $_ : "!$_" } sort keys %$v },
Subroutine __ANON__: called CC=2 SCAR=6.9
Branch: 1 branch
BranchTrueFalseTotal
$v->{$_} ? : 2 2 4
185 [qw( GPIO SPI I2C UART )] ],
186 2 ▶ read_gpios => [ sub { my ( $v ) = @_; join ",", @$v },
Subroutine __ANON__: called CC=1 SCAR=0.0
187 [qw( GPIO SPI I2C UART )] ],
188 0 ▶ tris_gpios => [ sub { my ( $v ) = @_; join ",", @$v },
Subroutine __ANON__: not called CC=1 SCAR=6.9
189 6 [qw( GPIO SPI I2C UART )] ],
190 write => [ undef,
191 [qw( SPI I2C UART )] ],
192 read => [ undef,
193 [qw( SPI I2C UART )] ],
194 write_then_read => [ undef,
195 [qw( SPI I2C )] ],
196 readwrite => [ undef,
197 [qw( SPI )] ],
198 assert_ss => [ undef,
199 [qw( SPI )] ],
200 release_ss => [ undef,
201 [qw( SPI )] ],
202 write_no_ss => [ undef,
203 [qw( SPI )] ],
204 readwrite_no_ss => [ undef,
205 [qw( SPI )] ],
206 );
207  
208 6 ▶ use Object::Pad 0.800 ':experimental(mop)';
Subroutine BEGIN: called CC=1 SCAR=0.0
209 6 my $meta = Object::Pad::MOP::Class->for_caller;
210  
211 6 foreach my $method ( keys %METHODS ) {
212 72 my ( $canonicalise, $allowed_protos ) = $METHODS{$method}->@*;
213  
214 $meta->add_method(
215 17 ▶ "expect_$method" => method {
Subroutine expect_write_no_ss: called CC=2 SCAR=7.0
Subroutine expect_write_gpios: called CC=2 SCAR=7.0
Pod undocumented
Pod undocumented
216 17 ▶ @_ = $canonicalise->( @_ ) if $canonicalise;
Branch: 2 branches
BranchTrueFalseTotal
if $canonicalise 0 17 17
if $canonicalise 2 27 29
217  
218 17 return $_controller->expect( $method => @_ )
219 ->will_done();
220 72 }
221 );
222  
223 $meta->add_method(
224 17 ▶ "$method" => method {
Subroutine readwrite: called CC=5 SCAR=16.8
Subroutine sleep: called CC=5 SCAR=16.8
Pod undocumented
Pod undocumented
225 17 ▶ @_ = $canonicalise->( @_ ) if $canonicalise;
Branch: 2 branches
BranchTrueFalseTotal
if $canonicalise 0 17 17
if $canonicalise 4 24 28
226  
227 17 my @args = @_;
228  
229 17 ▶ any { $_ eq $_protocol } @$allowed_protos or
Subroutine __ANON__: called CC=1 SCAR=0.0
Branch: 2 branches
BranchTrueFalseTotal
&any(sub { $_ eq $_protocol; } , @$allowed_protos) or croak("Method ->$method not allowed in $_protocol protocol") 17 0 17
&any(sub { $_ eq $_protocol; } , @$allowed_protos) or croak("Method ->$method not allowed in $_protocol protocol") 26 2 28
230 croak "Method ->$method not allowed in $_protocol protocol";
231  
232 17 ▶ if( $method eq "read" and $_read_buffer ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($method eq "read" and $_read_buffer) 0 17 17
if ($method eq "read" and $_read_buffer) 1 25 26
Condition50%3/6
$method eq "read" and $_read_buffer
!ll&&!rl&&r
1700
$method eq "read" and $_read_buffer
!ll&&!rl&&r
2701
MC/DC0%0/2
$method eq "read" and $_read_buffer
$method eq "read" $_read_buffer
MC/DC50%1/2
$method eq "read" and $_read_buffer
$method eq "read" $_read_buffer
Truth table33%1/3
A and B
A= $method eq "read"B= $_read_buffer
ABresult
0X0
100
111
Truth table66%2/3
A and B
A= $method eq "read"B= $_read_buffer
ABresult
0X0
100
111
233 0 my ( $len ) = @args;
234 0 return $_read_buffer->read_exactly( $len );
235 }
236  
237 17 return $_obj->$method( @args );
238 72 }
239 );
240 }
241  
242 class Test::Device::Chip::Adapter::_TxnHelper {
243 6 field $_adapter :param;
244  
245 0 ▶ async method write { await $_adapter->write( @_ ) }
Subroutine write: not called CC=1 SCAR=2.6
246 0 ▶ async method read { return await $_adapter->read( @_ ) }
Subroutine read: not called CC=1 SCAR=2.6
247 0 ▶ async method write_then_read { return await $_adapter->write_then_read( @_ ) }
Subroutine write_then_read: not called CC=1 SCAR=2.6
248 }
249  
250 0 ▶ async method txn ( $code )
Subroutine txn: not called CC=3 SCAR=23.5
Pod undocumented
251 0 {
252 0 ▶ $_protocol eq "I2C" or
Branch: 1 branch
BranchTrueFalseTotal
$_protocol eq "I2C" or croak("Method ->txn not allowed in $_protocol protocol") 0 0 0
253 croak "Method ->txn not allowed in $_protocol protocol";
254  
255 0 ▶ $_txn_helper //= Test::Device::Chip::Adapter::_TxnHelper->new( adapter => $self );
Condition0%0/3
$_txn_helper //= "Test::Device::Chip::Adapter::_TxnHelper"->new("adapter", $self)
l!l&&r!l&&!r
000
MC/DC0%0/2
$_txn_helper //= "Test::Device::Chip::Adapter::_TxnHelper"->new("adapter", $self)
$_txn_helper "Test::Device::Chip::Adapter::_TxnHelper"->new("adapter", $self)
Truth table0%0/3
A //= B
A= $_txn_helperB= "Test::Device::Chip::Adapter::_TxnHelper"->new("adapter", $self)
ABresult
1X1
011
000
256  
257 0 $_obj->txn_start;
258  
259 0 my $result = await $code->( $_txn_helper );
260  
261 0 $_obj->txn_stop;
262  
263 0 return $result;
264 6 }
265  
266 0 ▶ async method expect_txn_start () { $_controller->expect( txn_start => ) }
Subroutine expect_txn_start: not called CC=1 SCAR=4.6
Pod undocumented
267 0 ▶ async method expect_txn_stop () { $_controller->expect( txn_stop => ) }
Subroutine expect_txn_stop: not called CC=1 SCAR=6.9
Pod undocumented
268 }
269  
270 =head1 METHODS
271  
272 This class has the methods available on L<Device::Chip::Adapter>, which would
273 normally be used by the chip instance under test. The following additional
274 methods would be used by the unit test script controlling it.
275  
276 =cut
277  
278 =head2 check_and_clear
279  
280 $adapter->check_and_clear( $name );
281  
282 Checks that by now, every expected method has indeed been called, and emits a
283 new test output line via L<Test::Builder>. Regardless, the expectations are
284 also cleared out ready for the start of the next test.
285  
286 =cut
287  
288 32 ▶method check_and_clear ( $name )
Subroutine check_and_clear: called CC=1 SCAR=0.0
Pod documented
289 {
290 32 $_controller->check_and_clear( $name );
291 32 return;
292 6 }
293  
294 package # hide
295 Test::Device::Chip::Adapter::_TestController
296 6 {
297 6 ▶ use base "Test::ExpectAndCheck::Future";
Subroutine BEGIN: called CC=1 SCAR=0.0
298 6 ▶ use constant EXPECTATION_CLASS => "Test::Device::Chip::Adapter::_Expectation";
Subroutine BEGIN: called CC=1 SCAR=0.0
299 }
300  
301 package # hide
302 Test::Device::Chip::Adapter::_Expectation
303 6 {
304 6 ▶ use base "Test::ExpectAndCheck::Future::_Expectation";
Subroutine BEGIN: called CC=1 SCAR=0.0
305  
306 0 ▶ sub returns ( $self, @result )
Subroutine returns: not called CC=1 SCAR=6.9
307 {
308 0 warnings::warnif deprecated =>
309 "Calling ->returns on a Test::Device::Chip::Adapter expectation is now deprecated; use ->will_done instead";
310 0 $self->will_done( @result );
311 }
312 }
313  
314 =head1 TODO
315  
316 =over 4
317  
318 =item *
319  
320 Handle C<list_gpios> method
321  
322 =item *
323  
324 Handle C<configure>
325  
326 =back
327  
328 =head1 AUTHOR
329  
330 Paul Evans <leonerd@leonerd.org.uk>
331  
332 =cut
333  
334 6 0x55AA;
« Device/Chip/Base/RegisteredI2C.pm ↑ Summary Device/Chip.pm »