examples/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, also providing the implicit means of verifying that intended
  13 features for the 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, checks the behaviour of switch_to_input/output(), configures a pin as a pull-up button, a pull-down button and an LED.
  19
  20 ```python
  21 import testing
  22 testing.main()
  23 ```
  24
  25 ## Comments
  26
  27 There are routines in the top level of the repo like `upload_feather_m0_watch.py` which selectively synchronize files it with the CIRCUITPY or PYBFLASH folder for stm32 and samd21 (with a file-watching behaviour for edits), or which execute a selective ampy upload for CircuitPython/Micropython on esp8266.
  28
  29 Given the limited memory available, on the Feather M0 Express, running the test case requires that
  30 the [micropython-lib unittest library](https://github.com/micropython/micropython-lib/blob/master/unittest/unittest.py)
  31 is distributed as a compatible Micropython bytecode .mpy file
  32 pre-compiled under an mpy-cross version from the CircuitPython 2.2.3-tagged repository. Otherwise
  33 simply loading the unittest module already busts the available memory.
  34
  35 # Test Suite Structure
  36
  37 The structure of the testing modules is as follows, to permit test suites to be imported selectively
  38 on different implementations, platforms and boards (see agnostic.py for definitions of these terms)...
  39
  40 * _testing_ - common function definitions for suite-execution
  41 * _testing.mcp_ - test suite for hardware-agnostic elements of MCP layer (e.g. Enum)
  42 * _testing.implementation_ - calculates implementation-specific parameters for test fixtures
  43 * _testing.implementation.all_ - suites expected to run on all platforms
  44 * _testing.implementation.micropython_ - suites testing MCP-specific classes and behaviours (under the hood of the hardware compatibility layer) and only
  45 expected to run on Micropython
  46 * _testing.implementation.circuitpython - suites testing CircuitPython-specific
  47 classes and behaviours, and only expected to run in CircuitPython_
  48
  49 e.g.
  50 * testing.implementation.all.digitalio - tests against the
  51 digitalio module regardless of platform
  52 * testing.implementation.circuitpython.digitalio - tests of digitalio against a
  53 native circuitpython host
  54 * testing.implementation.micropython.digitalio - tests of digitalio against the MCP
  55 compatibility layer
  56
  57
  58 # Next Steps
  59
  60 To be able to run a substantial series of testing modules, a dedicated
  61 feather m0 express firmware image should be prepared with [frozen modules](https://learn.adafruit.com/micropython-for-samd21/frozen-modules) which
  62 minimises overhead by holding test definitions in flash instead of RAM.