How can I view documentation for previous PlatformIO versions

Advanced Solutions Unit Testing
1

How can I see the PlatformIO documentation for previus versions, specifically v5.2.5? There are configuration settings such as “test_transport” that are no longer available in v6.0.x, but I need to see what these settings used to do.

We have not yet done the work required to bring our projects and CI pipelines forward to v6.0.x, so are trying to keep them working on v5.2.5 until we do. The latest problem is the native platform update to v1.2.1 which is incompatible with PlatformIO v5.2.5. Although native @ 1.2.0 still installs OK on v5.2.5, “test_transport = none” now fails with;

Error: Unknown Unit Test transport `None`. Please check a documentation how to create an own 'Test Transport':

[36](https://gitlab.tactiq.co.uk/tactiq/windermere/sw/sw/-/jobs/835950#L36)- https://docs.platformio.org/page/plus/unit-testing.html

[38](https://gitlab.tactiq.co.uk/tactiq/windermere/sw/sw/-/jobs/835950#L38)
2

Good point! The docs on the lower left has a version selected, but no tagged previous versions for e.g. the PIO Core 5 exist

image

CC @ivankravets

And that is happening with the PIO Core 5? (pio --version or pio system info to make sure)

3

You can docs in its Github repository platformio-docs/projectconf/section_env_test.rst at v5.2.5 · platformio/platformio-docs · GitHub

We don’t keep docs for the previous major releases because we don’t provide LTS releases. All PlatformIO Core versions are compatible with a project created for any PIO Core version. So, please always use the latest PIO Core. If you see that something does not work with the next major version, this is a bug. Please report it to GitHub - platformio/platformio-core: Your Gateway to Embedded Software Development Excellence 👽

There is backward compatibility in PlatformIO Core 6.0 with “custom transports”. Nevertheless, we recommend removing this option from your configuration file and using the straight Unity configuration file. See docs and example.

PlatformIO Core 5.0 and test_transport were the wrappers around Unity configuration. You can now have full access to the Unity configuration. Just update/rename you “transport” functions.

4

Thank you for the quick response Ivan!

Ok, that works. The “Latest/Stable” version options in the sidebar on the main documentation page led me to think I could just select the previous version there.

The problem is that our CI build needs to be migrated to 6.0.x and we haven’t done that work yet. We were using the get_platformio.py method, but had to switch to pip install to force PlatformIO back to v5.2.5. In the meantime, a couple of package auto-update compatibility issues have have broken our CI build which impacts the whole team until we find a workaround.

We do need to get our PlatformIO projects onto 6.0.x as soon as possible. However, I would also encourage you to think about supporting LTS and/or specific version installations. A production software team often needs to be able to reliably recreate and update (bug fix) a previous software version, without forcing an update to the latest WIP version, as this may bring other issues along with it.

5

Yes, this is with pio v5.2.5, installed using

pip install platformio==5.2.5

Last week, one project started failing when the latest native platform changed from v1.2.0 to v1.2.1 as follows;

Platform Manager: Installing native
Downloading...
Unpacking...
Platform Manager: native @ 1.2.1 has been installed!
Platform Manager: Removing native @ 1.2.1
Platform Manager: native @ 1.2.1 has been removed!
Error: Development platform 'native' is not compatible with PlatformIO Core v5.2.5 and depends on PlatformIO Core ^6.

After I changed platformio.ini to use the previous version v1.2.0 specifically, the native test build failed with;

Building...
Error: Unknown Unit Test transport `None`. Please check a documentation how to create an own 'Test Transport':
- https://docs.platformio.org/page/plus/unit-testing.html

I was able to workaround this by adding test_transport = custom to the native build.

6

PlatformIO Core 6.0 is compatible with PIO Core 0-5 projects. Which issues do you have with Core 6.0?

7

Yes, this is a legacy configuration. It is very easy to port your code and use unity_config.h without any PlatformIO hooks that were applied in PIO Core 5.0. See project example platformio-examples/unit-testing/stm32cube/test at develop · platformio/platformio-examples · GitHub

8

Thanks again Ivan! I’m hoping to get time to move our CI build up to v6.0.x this week. I found out today that another dev team has already adapted their project build, so I am expecting it to be straightforward. I’ll let you know when I’ve done it.

1 Like
9

I’ve now got one of our projects building, checking and testing with PlatformIO Core 6.0.2. I would expect most projects to be simpler. Some factors making this project harder were:

  1. We build on Windows & on Linux,
  2. On Linux we run directly on the native Ubuntu 18.04 OS, which is quite old now,
  3. We use a hybrid unit test set up: Unity for common native and target tests & GoogleTest for native only tests,
  4. Most of our source code in under lib/ rather than src/. Most Unity unit test code is co-located with the library module that it tests.

Apart from the basic porting of settings as given in the migration guide, the fixes I needed to get the project building were;

  1. Remove legacy GoogleTest options and compile flags
  2. Remove test_transport = custom
  3. Add a GoogleTest main to each test/test_xxx folder
  4. Do not specify the test_framework, let PlatformIO deduce that. Use lib_deps = googletest, unity to pull in those packages for the native build.

Something that is not made clear in the test options documentation is what the “test name” means for test_filter and test_ignore. It means the test name that is listed in the summary table that PlatformIO presents when you run pio test, in other words the test/test_xxx directory containing a particular group of tests. It is not the test source file name, nor the test C function name.