notes/index.md

   1 This repository is structured around integration tests found in the python/testing
   2 directory. The tests offer a procedural way to assert equivalence between 'native' CircuitPython (CP) behaviour and
   3 behaviour of the MicropythonCircuitPython (MCP) layer.
   4
   5
   6 In particular, automated introspection of the python runtime combines with interactive prompts
   7 to configure a scenario for testing (e.g. which platform, which board, what is wired to it) meaning that
   8 the same routines can be carried out on Micropython boards, dual boards running either CP or MCP
   9 or dedicated CP boards.
  10
  11 From a project-management point of view, tests can provide a strictly-interpreted way to
  12 communicate missing features, with the means of verifying that intended features for the
  13 MCP layer are in fact already served from the CP layer.
  14
  15 # Example
  16
  17 To take a minimal example, the following asserts the default behaviour of the DigitalInOut
  18 constructor, to configure a pin as an input with no pull. The gc.collect() calls help to
  19 minimise heap fragmentation, and ensure there is enough memory to run the particular test.
  20
  21 ```python
  22 import gc
  23 import testing
  24 gc.collect()
  25 import testing.platform.all.digitalio as suite
  26 gc.collect()
  27 case = suite.TestDigitalInOut()
  28 gc.collect()
  29 if hasattr(case, 'setUp'):
  30     case.setUp()
  31 gc.collect()
  32
  33 gc.mem_free()
  34 case.test_default()
  35 ```
  36
  37 ## Comments
  38
  39 There is a routine in the top level of the repo called `upload_feather_m0_watch.py` which monitors the repo folder (on a regular
  40 filesystem) and selectively synchronizes it with the CIRCUITPY folder
  41 when any changes are saved, which assists with development.
  42
  43 Given the limited memory available, on the Feather M0 Express, running the test case requires that
  44 the [micropython-lib unittest library](https://github.com/micropython/micropython-lib/blob/master/unittest/unittest.py)
  45 is distributed as a compatible Micropython bytecode .mpy file
  46 pre-compiled under an mpy-cross version from the CircuitPython 2.2.3-tagged repository. Otherwise
  47 simply loading the unittest module already busts the available memory.
  48
  49 # Test Suite Structure
  50
  51 The structure of the testing modules is as follows, to permit test suites to be imported selectively
  52 on different implementations, platforms and boards (see agnostic.py for definitions of these terms)...
  53
  54 * _testing_ - common function definitions for suite-execution
  55 * _testing.mcp_ - test suite for hardware-agnostic elements of MCP layer (e.g. Enum)
  56 * _testing.implementation_ - calculates implementation-specific parameters for test fixtures
  57 * _testing.implementation.all_ - suites expected to run on all platforms
  58 * _testing.implementation.micropython_ - suites testing MCP-specific classes and behaviours (under the hood of the hardware compatibility layer) and only
  59 expected to run on Micropython
  60 * _testing.implementation.circuitpython - suites testing CircuitPython-specific
  61 classes and behaviours, and only expected to run in CircuitPython_
  62
  63 e.g.
  64 * testing.implementation.all.digitalio - tests against the
  65 digitalio module regardless of platform
  66 * testing.implementation.circuitpython.digitalio - tests of digitalio against a
  67 native circuitpython host
  68 * testing.implementation.mcp.digitalio - tests of digitalio against the MCP
  69 compatibility layer
  70
  71
  72 # Next Steps
  73
  74 To be able to run a substantial series of testing modules, a dedicated
  75 feather m0 express firmware image should be prepared with [frozen modules](https://learn.adafruit.com/micropython-for-samd21/frozen-modules) which
  76 minimises overhead by holding test definitions in flash instead of RAM.