Merge pull request #1230 from glados-verma:feat-test-measurements-and-helper

PiperOrigin-RevId: 761656356

Author: copybara-github

examples/hello_world.py

@@ -26,14 +26,14 @@
 For more information on output, see the output.py example.
 """
 
+import os.path
+
 # Import openhtf with an abbreviated name, as we'll be using a bunch of stuff
 # from it throughout our test scripts. See __all__ at the top of
 # openhtf/__init__.py for details on what's in top-of-module namespace.
 import openhtf as htf
-
 # Import this output mechanism as it's the specific one we want to use.
 from openhtf.output.callbacks import json_factory
-
 from openhtf.plugs import user_input
 
 
@@ -63,7 +63,7 @@ def hello_world(test):
   test.measurements.hello_world_measurement = 'Hello Again!'
 
 
-def main():
+def create_and_run_test(output_dir: str = '.'):
   # We instantiate our OpenHTF test with the phases we want to run as args.
   # Multiple phases would be passed as additional args, and additional
   # keyword arguments may be passed as well.  See other examples for more
@@ -73,10 +73,13 @@ def main():
   # In order to view the result of the test, we have to output it somewhere,
   # and a local JSON file is a convenient way to do this.  Custom output
   # mechanisms can be implemented, but for now we'll just keep it simple.
-  # This will always output to the same ./hello_world.json file, formatted
-  # slightly for human readability.
+  # With the default output_dir argument, this will always output to the
+  # same ./hello_world.json file, formatted slightly for human readability.
   test.add_output_callbacks(
-      json_factory.OutputToJSON('./{dut_id}.hello_world.json', indent=2))
+      json_factory.OutputToJSON(
+          os.path.join(output_dir, '{dut_id}.hello_world.json'), indent=2
+      )
+  )
 
   # prompt_for_test_start prompts the operator for a DUT ID, a unique identifier
   # for the DUT (Device Under Test).  OpenHTF requires that a DUT ID is set
@@ -89,4 +92,4 @@ def main():
 
 
 if __name__ == '__main__':
-  main()
+  create_and_run_test()

examples/measurements.py

@@ -43,16 +43,15 @@
     measurements, which some output formats require.
 """
 
+import os.path
+import random
+
 # Import openhtf with an abbreviated name, as we'll be using a bunch of stuff
 # from it throughout our test scripts. See __all__ at the top of
 # openhtf/__init__.py for details on what's in top-of-module namespace.
-import random
-
 import openhtf as htf
-
 # Import this output mechanism as it's the specific one we want to use.
 from openhtf.output.callbacks import json_factory
-
 # You won't normally need to import this, see validators.py example for
 # more details.  It's used for the inline measurement declaration example
 # below, but normally you'll only import it when you want to define custom
@@ -94,9 +93,11 @@ def lots_of_measurements(test):
 # describing the measurement.  Validators can get quite complex, for more
 # details, see the validators.py example.
 @htf.measures(
-    htf.Measurement('validated_measurement').in_range(
-        0,
-        10).doc('This measurement is validated.').with_units(htf.units.SECOND))
+    htf.Measurement('validated_measurement')
+    .in_range(0, 10)
+    .doc('This measurement is validated.')
+    .with_units(htf.units.SECOND)
+)
 def measure_seconds(test):
   # The 'outcome' of this measurement in the test_record result will be a PASS
   # because its value passes the validator specified (0 <= 5 <= 10).
@@ -112,7 +113,8 @@ def measure_seconds(test):
     'inline_kwargs',
     docstring='This measurement is declared inline!',
     units=htf.units.HERTZ,
-    validators=[validators.in_range(0, 10)])
+    validators=[validators.in_range(0, 10)],
+)
 @htf.measures('another_inline', docstring='Because why not?')
 def inline_phase(test):
   """Phase that declares a measurements validators as a keyword argument."""
@@ -128,7 +130,8 @@ def inline_phase(test):
 # A multidim measurement including how to convert to a pandas dataframe and
 # a numpy array.
 @htf.measures(
-    htf.Measurement('power_time_series').with_dimensions('ms', 'V', 'A'))
+    htf.Measurement('power_time_series').with_dimensions('ms', 'V', 'A')
+)
 @htf.measures(htf.Measurement('average_voltage').with_units('V'))
 @htf.measures(htf.Measurement('average_current').with_units('A'))
 @htf.measures(htf.Measurement('resistance').with_units('ohm').in_range(9, 11))
@@ -138,7 +141,7 @@ def multdim_measurements(test):
   for t in range(10):
     resistance = 10
     voltage = 10 + 10.0 * t
-    current = voltage / resistance + .01 * random.random()
+    current = voltage / resistance + 0.01 * random.random()
     dimensions = (t, voltage, current)
     test.measurements['power_time_series'][dimensions] = 0
 
@@ -158,39 +161,51 @@ def multdim_measurements(test):
 
   # Finally, let's estimate the resistance
   test.measurements['resistance'] = (
-      test.measurements['average_voltage'] /
-      test.measurements['average_current'])
+      test.measurements['average_voltage']
+      / test.measurements['average_current']
+  )
 
 
 # Marginal measurements can be used to obtain a finer granularity of by how much
 # a measurement is passing. Marginal measurements have stricter minimum and
 # maximum limits, which are used to flag measurements/phase/test records as
 # marginal without affecting the overall phase outcome.
 @htf.measures(
-    htf.Measurement('resistance').with_units('ohm').in_range(
-        minimum=5, maximum=17, marginal_minimum=9, marginal_maximum=11))
+    htf.Measurement('resistance')
+    .with_units('ohm')
+    .in_range(minimum=5, maximum=17, marginal_minimum=9, marginal_maximum=11)
+)
 def marginal_measurements(test):
   """Phase with a marginal measurement."""
   test.measurements.resistance = 13
 
 
-def main():
+def create_and_run_test(output_dir: str = '.'):
   # We instantiate our OpenHTF test with the phases we want to run as args.
-  test = htf.Test(hello_phase, again_phase, lots_of_measurements,
-                  measure_seconds, inline_phase, multdim_measurements)
+  test = htf.Test(
+      hello_phase,
+      again_phase,
+      lots_of_measurements,
+      measure_seconds,
+      inline_phase,
+      multdim_measurements,
+  )
 
   # In order to view the result of the test, we have to output it somewhere,
   # and a local JSON file is a convenient way to do this.  Custom output
   # mechanisms can be implemented, but for now we'll just keep it simple.
   # This will always output to the same ./measurements.json file, formatted
   # slightly for human readability.
   test.add_output_callbacks(
-      json_factory.OutputToJSON('./measurements.json', indent=2))
+      json_factory.OutputToJSON(
+          os.path.join(output_dir, 'measurements.json'), indent=2
+      )
+  )
 
   # Unlike hello_world.py, where we prompt for a DUT ID, here we'll just
   # use an arbitrary one.
   test.execute(test_start=lambda: 'MyDutId')
 
 
 if __name__ == '__main__':
-  main()
+  create_and_run_test()

openhtf/util/example_test.py

@@ -0,0 +1,45 @@
+# Copyright 2016 Google Inc. All Rights Reserved.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Utilities for integration testing OpenHTF examples."""
+
+from typing import Any
+import unittest
+
+
+class ExampleTestBase(unittest.TestCase):
+  """Base class for integration testing OpenHTF examples."""
+
+  def get_phase_by_name(
+      self, json_data: dict[str, Any], phase_name: str
+  ) -> dict[str, Any]:
+    """Finds a phase by its name in a test output JSON.
+
+    Args:
+      json_data: The JSON data as loaded from the output file, generated by the
+        default JSON output callback.
+      phase_name: The name of the phase to find.
+
+    Returns:
+      The phase dictionary if found.
+
+    Raises:
+      AssertionError (via test_case.fail()): If the phase is not found
+        or json_data does not have the expected "phases" key.
+    """
+    if "phases" not in json_data:
+      self.fail("JSON data does not contain 'phases' key.")
+    for p in json_data["phases"]:
+      if p["name"] == phase_name:
+        return p
+    self.fail(f"Phase '{phase_name}' not found in output.")

test/examples/hello_world_test.py

@@ -0,0 +1,56 @@
+# Copyright 2016 Google Inc. All Rights Reserved.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import os
+import tempfile
+import unittest
+from unittest import mock
+
+from examples import hello_world
+from openhtf.plugs import user_input
+from openhtf.util import example_test
+
+
+class TestHelloWorld(example_test.ExampleTestBase):
+
+  @mock.patch.object(user_input.UserInput, user_input.UserInput.prompt.__name__)
+  def test_main_execution(self, mock_user_prompt):
+    # The test only has one prompt, for the DUT ID.
+    mock_user_prompt.return_value = "test_dut"
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+      hello_world.create_and_run_test(temp_dir)
+      expected_json_path = os.path.join(temp_dir, 'test_dut.hello_world.json')
+
+      # Assert that the output file was created
+      self.assertTrue(os.path.exists(expected_json_path))
+      with open(expected_json_path) as f:
+        output_data = json.load(f)
+
+    self.assertEqual(output_data["dut_id"], "test_dut")
+    self.assertEqual(output_data["outcome"], "PASS")
+    self.assertGreaterEqual(len(output_data["phases"]), 2)
+
+    hello_world_phase_data = self.get_phase_by_name(output_data, "hello_world")
+    self.assertEqual(
+        hello_world_phase_data["measurements"]["hello_world_measurement"][
+            "measured_value"
+        ],
+        "Hello Again!",
+    )
+
+
+if __name__ == "__main__":
+  unittest.main()

test/examples/measurements_test.py

@@ -0,0 +1,96 @@
+# Copyright 2016 Google Inc. All Rights Reserved.
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import os
+import tempfile
+import unittest
+from examples import measurements
+from openhtf.util import example_test
+
+
+class TestMeasurements(example_test.ExampleTestBase):
+
+  def test_main_execution(self):
+    with tempfile.TemporaryDirectory() as temp_dir:
+      measurements.create_and_run_test(temp_dir)
+      expected_json_path = os.path.join(temp_dir, 'measurements.json')
+
+      # Assert that the output file was created
+      self.assertTrue(os.path.exists(expected_json_path))
+      with open(expected_json_path) as f:
+        output_data = json.load(f)
+
+    self.assertEqual(output_data["dut_id"], "MyDutId")
+    self.assertEqual(output_data["outcome"], "FAIL")
+    self.assertIn("phases", output_data)
+    self.assertEqual(len(output_data["phases"]), 7)
+
+    with self.subTest("hello_phase"):
+      hello_phase_data = self.get_phase_by_name(output_data, "hello_phase")
+      self.assertEqual(
+          hello_phase_data["measurements"]["hello_world_measurement"][
+              "measured_value"
+          ],
+          "Hello!",
+      )
+
+    with self.subTest("measure_seconds"):
+      measure_seconds_data = self.get_phase_by_name(
+          output_data, "measure_seconds"
+      )
+      self.assertEqual(
+          measure_seconds_data["measurements"]["validated_measurement"][
+              "outcome"
+          ],
+          "PASS",
+      )
+      self.assertEqual(
+          measure_seconds_data["measurements"]["validated_measurement"][
+              "measured_value"
+          ],
+          5,
+      )
+
+    with self.subTest("inline_phase"):
+      inline_phase_data = self.get_phase_by_name(output_data, "inline_phase")
+      self.assertEqual(
+          inline_phase_data["measurements"]["inline_kwargs"]["outcome"], "FAIL"
+      )
+      self.assertEqual(
+          inline_phase_data["measurements"]["inline_kwargs"]["measured_value"],
+          15,
+      )
+
+    with self.subTest("multidim_measurements"):
+      multdim_measurements_data = self.get_phase_by_name(
+          output_data, "multdim_measurements"
+      )
+      self.assertAlmostEqual(
+          multdim_measurements_data["measurements"]["average_voltage"][
+              "measured_value"
+          ],
+          55.0,
+      )
+      self.assertTrue(
+          9
+          <= multdim_measurements_data["measurements"]["resistance"][
+              "measured_value"
+          ]
+          <= 11
+      )
+
+
+if __name__ == "__main__":
+  unittest.main()