From cf6fd4ccea5ecb67b30f0dd86d17e01f74618d3a Mon Sep 17 00:00:00 2001 From: Beth Probert Date: Wed, 17 Jun 2026 16:42:25 +0100 Subject: [PATCH] Update to cover new logic. Updatee READMEs and Guides with --debug arg information --- README.md | 2 +- apidocs/dev/README.md | 4 ++ apidocs/dev/simulation_guide.md | 2 + src/openflexure_microscope_server/logging.py | 5 ++- tests/unit_tests/test_logging.py | 28 ++++++++++++ tests/unit_tests/test_server_cli.py | 47 +++++++++----------- 6 files changed, 59 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 4af9d1bf..52ebcd0f 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ More information is also available in the [handbook](https://gitlab.com/openflex ## Running directly -The Python package provides a command `ofm-microscope-server` that runs the server. This is what is used by `systemd` to run the service. You will need to provide some command-line arguments, see the output of `--help` for an up to date list. See `/etc/systemd/system/openflexure-microscope-server.service` for the command line used to run the server by default on the Raspberry Pi. In general, you are likely to want to specify a configuration file with `-c`, a host (`--host 0.0.0.0` to serve on all addresses) and a port (`--port 5000`). The `--fallback` option will allow the server to start *even if the hardware specified in the configuration file can't load*. This serves an error page, rather than have the server fail. In the future, it should redirect users to a way to fix their configuration. +The Python package provides a command `ofm-microscope-server` that runs the server. This is what is used by `systemd` to run the service. You will need to provide some command-line arguments, see the output of `--help` for an up to date list. See `/etc/systemd/system/openflexure-microscope-server.service` for the command line used to run the server by default on the Raspberry Pi. In general, you are likely to want to specify a configuration file with `-c`, a host (`--host 0.0.0.0` to serve on all addresses) and a port (`--port 5000`). The `--fallback` option will allow the server to start *even if the hardware specified in the configuration file can't load*. This serves an error page, rather than have the server fail. In the future, it should redirect users to a way to fix their configuration. The `--debug` option spins up both the OpenFlexure Microscope server and the LabThings server in `DEBUG` mode, providing more verbose logging information. It is also possible to run the server in simulation mode. See Developer guidelines below. diff --git a/apidocs/dev/README.md b/apidocs/dev/README.md index bd68d26a..e24986b3 100644 --- a/apidocs/dev/README.md +++ b/apidocs/dev/README.md @@ -71,6 +71,8 @@ sudo -u openflexure-ws application/openflexure-microscope-server/.venv/bin/openf ``` +> Note: If you would like more detailed logging information from both the OpenFlexure Microscope server and the LabThings server, you can add the `--debug` argument to the end of the above command to activate `DEBUG` level logs. + ### Running the simulation server on other platforms To start the simulation server: @@ -81,6 +83,8 @@ To start the simulation server: `openflexure-microscope-server --fallback -c ./ofm_config_simulation.json` +> Note: If you would like more detailed logging information from both the OpenFlexure Microscope server and the LabThings server, you can add the `--debug` argument to the end of the above command to activate `DEBUG` level logs. + * Open the address displayed in the terminal in any browser. * To close the simulation server, return to the terminal and press `ctrl + c`. diff --git a/apidocs/dev/simulation_guide.md b/apidocs/dev/simulation_guide.md index cf7997ae..a79d6e6e 100644 --- a/apidocs/dev/simulation_guide.md +++ b/apidocs/dev/simulation_guide.md @@ -27,6 +27,8 @@ The simulation server GUI is a copy of the GUI you would find on the hardware wi This can fail with an error that the chosen port is already in use. In that case, append `--port 8081` +> Note: If you would like more detailed logging information from both the OpenFlexure Microscope server and the LabThings server, you can add the `--debug` argument to the end of the above command to activate `DEBUG` level logs. + --- ## Video Walkthrough diff --git a/src/openflexure_microscope_server/logging.py b/src/openflexure_microscope_server/logging.py index 0d4375f4..aa68741a 100644 --- a/src/openflexure_microscope_server/logging.py +++ b/src/openflexure_microscope_server/logging.py @@ -73,7 +73,10 @@ def configure_logging(log_folder: str, debug: bool = False) -> None: except PermissionError as e: LOGGER.error(f"Cannot create log file at {OFM_LOG_FILE}: {e}") - LOGGER.info("OFM server root logger has been set up at %s level", logging.getLevelName(root_logger.level)) + LOGGER.info( + "OFM server root logger has been set up at %s level", + logging.getLevelName(root_logger.level), + ) def retrieve_log() -> PlainTextResponse: diff --git a/tests/unit_tests/test_logging.py b/tests/unit_tests/test_logging.py index 56de711f..0f961c23 100644 --- a/tests/unit_tests/test_logging.py +++ b/tests/unit_tests/test_logging.py @@ -206,3 +206,31 @@ def test_uvicorn_error_only_says_error_on_error( assert name in log_txt for name in names_not_in_log: assert name not in log_txt + + +@pytest.mark.parametrize( + ("debug_flag", "expected_level"), + [ + (False, logging.INFO), + (True, logging.DEBUG), + ], +) +def test_configure_logging_debug_mode(debug_flag, expected_level): + """Check that debug flag sets the correct root and handler logging levels.""" + # Reset handler at start of test + ofm_logging.OFM_HANDLER = ofm_logging.OFMHandler() + + with tmp_logging_dir() as tmpdir: + # Run configuration with the parameterised debug flag + ofm_logging.configure_logging(tmpdir, debug=debug_flag) + + root_logger = logging.getLogger() + + # Assert the root logger level was set correctly + assert root_logger.level == expected_level + # Assert the custom OFM handler level was synced to the root logger + assert ofm_logging.OFM_HANDLER.level == expected_level + + # Cleanup: Remove the OFM_HANDLER from the root logger so it doesn't + # interfere with other tests in the suite. + root_logger.removeHandler(ofm_logging.OFM_HANDLER) diff --git a/tests/unit_tests/test_server_cli.py b/tests/unit_tests/test_server_cli.py index b9eda4f3..90a5bfda 100644 --- a/tests/unit_tests/test_server_cli.py +++ b/tests/unit_tests/test_server_cli.py @@ -112,42 +112,35 @@ def test_failed_customise(mocker): def test_debug_mode(mocker): """Test that --debug flag triggers lt.logs.configure_thing_logger.""" - - # Use a side_effect to map the CLI debug arg to the mock server's debug attribute - def mock_from_config(_, debug_flag): - mock_server = mocker.Mock() - mock_server.debug = debug_flag # This will now be correctly True or False - return mock_server - - mocker.patch( + # Mock the LabThings server creation so we can inspect its arguments + mock_from_config = mocker.patch( "openflexure_microscope_server.server.lt.ThingServer.from_config", - side_effect=mock_from_config, + return_value=mocker.Mock(), ) - # Mock customisation dependencies to avoid side effects - mocker.patch.object(ofm_server, "add_v2_endpoints") - mocker.patch.object(ofm_server, "add_static_files") - # Mock logging to avoid side effects and allow checking calls - mocker.patch.object(ofm_server, "configure_logging") - mocker.patch.object(ofm_server, "retrieve_log") - mocker.patch.object(ofm_server, "retrieve_log_from_file") - # Mock uvicorn.run to avoid starting a server + # Mock configure_logging to inspect its arguments and prevent side effects + mock_configure_logging = mocker.patch.object(ofm_server, "configure_logging") + + # Mock other dependencies to avoid side effects (file writing, server starting) + mocker.patch.object(ofm_server, "customise_server") mocker.patch("openflexure_microscope_server.server.uvicorn.run") - # Mock the target function - mock_configure_thing_logger = mocker.patch( - "openflexure_microscope_server.server.lt.logs.configure_thing_logger" - ) - # 1. Run with --debug ofm_server.serve_from_cli(["-c", SIM_CONFIG, "--debug"]) - # Verify it was called with DEBUG level - mock_configure_thing_logger.assert_called_once_with(logging.DEBUG) + # Verify configure_logging was called with debug=True (the second argument) + assert mock_configure_logging.call_args.args[1] is True + # Verify ThingServer.from_config was called with debug=True (the second argument) + assert mock_from_config.call_args.args[1] is True + + # Reset the mocks for the next run + mock_configure_logging.reset_mock() + mock_from_config.reset_mock() # 2. Run without --debug - mock_configure_thing_logger.reset_mock() ofm_server.serve_from_cli(["-c", SIM_CONFIG]) - # Verify it was NOT called - mock_configure_thing_logger.assert_not_called() + # Verify configure_logging was called with debug=False + assert mock_configure_logging.call_args.args[1] is False + # Verify ThingServer.from_config was called with debug=False + assert mock_from_config.call_args.args[1] is False