Merge remote-tracking branch 'upstream/devel' into fpp-issue-392-stri…

…ng-records

docs/Design/general.md

@@ -11,4 +11,5 @@ viewed through F´.
 | [Communication Adapter Interface](./communication-adapter-interface.md) |
 | [Package Implementations](./package-implementations.md)                 |
 | [FPP JSON Dictionary Specification](./fpp-json-dict.md)                 |
+| [Integration Test API Design](./integration-test-api.md)                |
 

docs/Design/integration-test-api.md

@@ -0,0 +1,37 @@
+## Integration Test API Design
+
+This covers the design of the integration test API.
+
+### Integration Test API Outline
+
+The actual Test API is a very long class that has helpful doc-strings, but these don't convey its organization while skimming. Below is a table of how the API is organized with a brief summary of each section:
+
+| Test API Section| Section Description| Methods|
+| :----| :----| :----|
+| API Functions| These functions give access to helpful API features.| start_test_case, log, get_latest_time, test_assert, predicate_assert, clear_histories, set_event_log_filter|
+| History Functions| These functions give the user access to test histories and the ability to create sub-histories.| get_command_test_history, get_telemetry_test_history, get_event_test_history, get_telemetry_subhistory, remove_telemetry_subhistory, get_event_subhistory, remove_event_subhistory|
+| Command Functions| These functions provide the ability to send commands and search for events/telemetry.| translate_command_name, send_command, send_and_await_telemetry, send_and_await_event|
+| Command Asserts| These functions send commands then perform search and asserts on the histories| send_and_assert_telemetry, send_and_assert_event|
+| Telemetry Functions| These functions help specify and search for telemetry updates.| translate_telemetry_name, get_telemetry_pred, await_telemetry, await_telemetry_sequence, await_telemetry_count|
+| Telemetry Asserts| These functions search and assert for telemetry updates.| assert_telemetry, assert_telemetry_sequence, assert_telemetry_count|
+| Event Functions| These functions help specify and search for event messages.| translate_event_name, get_event_pred, await_event, await_event_sequence, await_event_count|
+| Event Asserts| These functions search and assert for event messages.| assert_event, assert_event_sequence, assert_event_count|
+| History Searches| These functions implement the various searches in the API. They aren't meant for the user, but are mentioned to highlight where searches are actually performed.| __search_test_history, find_history_item, find_history_sequence, find_history_count|
+
+One thing to note about the API's implementation is that the API uses layering so that all searches can be defined by common arguments and share similar behaviors. A diagram of this layering is provided below. In the diagram, each box is an API call. The arrows show how the calls are layered.
+
+![Diagram of GDS Search Layering](img/APISearchLayering.png)
+
+The table below outlines the additional functionality provided by each layer in above diagram.
+
+|Layer Name| Diagram Row| Delegated Functionality|
+| :---| ---:| :---|
+| Assert Layer| 1| This layer adds an assert to the end of the search to check if the search completed successfully.|
+| Await Layer| 2| This layer differentiates whether the particular search is acting on the event or telemetry history.|
+| Search Type Layer| 3| This layer determines what kind of search is being conducted. The API provides 3 types: item, count, and sequence.|
+| Search Helper| 4| The search helper provides the logic, logging, search scoping. and sub-history functionality for all searches.|
+
+### Integration Test Classes
+
+The API uses several classes to support its features. They were organized within the already-present GDS class folder structure. A component view of the integration test API and its relationship to the Integration Tests and the GDS is shown in the diagram below. For simplicity, the predicates library has been left out, but it can be used by Integration tests and is presently used by the Test API and Test History layers.
+![Component View of the Test Framework](img/TestFwComponentView.png)

docs/INSTALL.md

@@ -97,80 +97,4 @@ Sometimes users wish to work with existing F´ projects. Once the project has be
 
 ## Troubleshooting
 
-This section will add some known hints to trouble-shooting with the installation of F´. This will hopefully help users install things more effectively.
-
-### fprime-util: command not found
-
-If the user is using a virtual environment and receives the 'command not found', the problem is likely caused by the environment not being sourced in a new terminal. Make sure to source the environment before running:
-
-```
-. <path/to/project>/fprime-venv/bin/activate
-```
-
-If installing without a virtual environment, PIP occasionally uses `$HOME/.local/bin` as a place to install user tools. Users running without virtual environments should add this directory to the path.
-
-### Helper script 'fpp-redirect-helper' exited with reason: Permission denied
-
-This error can occur when the helper-script, *(`fprime/cmake/autocoder/fpp-wrapper/fpp-redirect-helper`)* loses its execution permission.
-
-To verify that this is the case, change to the directory containing `fpp-redirect-helper` and verify that it is executable.
-
-* `cd fprime/cmake/autocoder/fpp-wrapper/`
-* `ls -l`
-
-If it is not executable, add the permission back.
-
-* `chmod 700 fpp-redirect-helper`
-
-### Ubuntu, Debian, Java and Python PIP
-
-Ubuntu and possibly other Debian variants don't include the pip packages in the default Python 3 installation. To get fully functional, use these commands on Ubuntu and Debian based systems:
-
-```
-sudo apt install git cmake default-jre python3 python3-pip python3-venv
-```
-
-Now you should be able to run the installation without trouble.
-
-### Mac OS X and CMake Command Not Found
-
-If the user chooses to install CMake directly from the CMake site (not using homebrew nor Mac Ports), then the CMake command-line tools must be added to the user's PATH or default system libraries. The quickest command to do that is:
-
-```
-sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install
-```
-
-More information can be found [here](https://stackoverflow.com/questions/30668601/installing-cmake-command-line-tools-on-a-mac)
-
-
-### SSL Error with Python 3.8+ on macOS
-
-> This fix will not work for Python installed via Homebrew.  Try installing Python published at python.org. 
-
-The version of openSSL bundled with Python 3.8+ requires access to macOS's root certificates. If the following error is  encountered while installing fprime: 
-
-```
-Failed find expected download: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get  local issuer certificate
-```
-
-Then run the following command in a macOS terminal to install necessary certificates: 
-
-```
-cd /Applications/Python\ 3.X/
-./Install\ Certificates.command
-```
-
-After running above command, re-try installing `fprime-bootstrap`.
-
-
-### Recommended PIP Versions
-
-Some of the F´ Python packages are built in a way that it is recommended to install them with modern versions of PIP. Systems not recommended or pip versions less than recommended will require Java and run slower versions of FPP tools. The recommended versions are described below:
-
-| System | Recommended `pip` version |
-|---|---|
-| macOS (10.9+) | >= 21.0.1 |
-| x86_64 | >= 19.3 |
-| aarch64| >= 20.3 |
-
-
+For users having issues, please see our [troubleshooting guide](./troubleshooting.md).