From fd7c8ff56d733bc4326614838d564c90a0ba1642 Mon Sep 17 00:00:00 2001
From: Akash Verma <akashv@google.com>
Date: Wed, 18 Dec 2024 15:39:23 -0800
Subject: [PATCH] Fix broken examples and add a README

---
 examples/README.md       | 67 ++++++++++++++++++++++++++++++++++++++++
 examples/measurements.py |  2 +-
 examples/with_plugs.py   |  2 +-
 3 files changed, 69 insertions(+), 2 deletions(-)
 create mode 100644 examples/README.md

diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 000000000..e76d38729
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,67 @@
+# Running the examples
+
+## Install dependencies
+
+Some examples have their own additional dependencies. They can be installed
+with the following command:
+
+```
+# Activate your virtualenv if not already done.
+pip install pandas
+```
+
+## Running the examples
+
+Each example can be run as a Python script, so for `measurements.py`:
+
+```
+python examples/measurements.py
+```
+
+Running the test will print the outcome on the terminal. You can examine
+the run's JSON file, generated in the working directory, to view the
+measurements for the run. This example generates a JSON output because it
+configures one via output callbacks; read on for more examples with other
+types of outputs.
+
+Some examples also have user prompts, you'll have to enter some text at the
+prompt to continue the example.
+
+## List of examples
+
+### Canonical examples
+
+1.  [`hello_world.py`](hello_world.py): start here if learning how to write
+    an OpenHTF test.
+    Comments explain usage of basic OpenHTF features: measurements, phases,
+    `TestApi` and the OpenHTF test, and output callbacks.
+2.  [`measurements.py`](measurements.py): measurements are the canonical
+    mechanism to record text or numeric parameters for a phase.
+    This example walks you through defining measurements with pass-fail rules ("validators"), units, dimensions, and how to set the measurements from
+    your phases.
+3.  [`with_plugs.py`](with_plugs.py): how to define and subclass plugs, and
+    use them in a phase.
+4.  [`frontend_example.py`](frontend_example.py): How to use the OpenHTF web
+    frontend in a test. This gives your test a GUI via the default browser on
+    the system.
+5.  [`all_the_things.py`](all_the_things.py): demonstates use of plugs,
+    measurements, attachments and `PhaseOptions`. Multiple phases are sequenced
+    via a `Test` and executed, with some output callbacks defined (JSON file,
+    pickle file and console).
+
+### Feature showcases
+
+1.  [`checkpoints.py`](checkpoints.py): checkpoints with measurements can be
+    used to stop a test if any phase before the checkpoint had failed
+    measurements.
+    By default, failed measurements don't stop a test execution.
+2.  [`stop_on_first_failure.py`](stop_on_first_failure.py): shows how to use
+    `TestOptions`, in this case the `stop_on_first_failure` option, to
+    customize test execution.
+    Also shows how to set this via a `Configuration`.
+3.  [`ignore_early_canceled_tests.py`](ignore_early_canceled_tests.py): shows
+    how to customize output callbacks; in this case, JSON output.
+4.  [`phase_groups.py`](phase_groups.py): phase groups can be used to combine
+    phases with their own setup and teardown logic.
+5.  [`repeat.py`](repeat.py): uses `openhtf.PhaseResult.REPEAT` to
+    conditionally repeat execution of a phase in a test.
diff --git a/examples/measurements.py b/examples/measurements.py
index 660fbec7e..b5d8924c3 100644
--- a/examples/measurements.py
+++ b/examples/measurements.py
@@ -152,7 +152,7 @@ def multdim_measurements(test):
   test.measurements['average_voltage'] = power_df['V'].mean()
 
   # We can convert the dataframe to a numpy array as well
-  power_array = power_df.as_matrix()
+  power_array = power_df.to_numpy()
   test.logger.info('This is the same data in a numpy array:\n%s', power_array)
   test.measurements['average_current'] = power_array.mean(axis=0)[2]
 
diff --git a/examples/with_plugs.py b/examples/with_plugs.py
index 6c45c4a23..9b636ff1a 100644
--- a/examples/with_plugs.py
+++ b/examples/with_plugs.py
@@ -74,7 +74,7 @@ class PingDnsB(PingPlug):
 @htf.PhaseOptions(name='Ping-{pinger.host}-{count}')
 @htf.plug(pinger=PingPlug.placeholder)
 @htf.measures('total_time_{pinger.host}_{count}',
-              htf.Measurement('retcode').equals('{expected_retcode}', type=int))
+              htf.Measurement('retcode').equals('{expected_retcode}', type=str))
 def test_ping(test, pinger, count, expected_retcode):
   """This tests that we can ping a host.