test:subprocess: unify tests with abstract base class

Author: scivision

+stdlib/dotnet_api.m

@@ -1,18 +1,16 @@
 %% SUBPROCESS_RUN run process
 %
-% with optional cwd, env. vars, stdin, timeout
-%
 % handles command lines with spaces
 % input each segment of the command as an element in a string array
 % this is how python subprocess.run works
 %
 %%% Inputs
 % * cmd: command line. Windows paths should use filesep '\'
-% * opt.env: environment variable struct to set
-% * opt.cwd: working directory to use while running command
-% * opt.stdin: string to pass to subprocess stdin pipe
-% * opt.stdout: logical to indicate whether to use pipe for stdout
-% * opt.stderr: logical to indicate whether to use pipe for stderr
+% * env: environment variable struct to set
+% * cwd: working directory to use while running command
+% * stdin: string to pass to subprocess stdin pipe
+% * stdout: logical to indicate whether to use pipe for stdout
+% * stderr: logical to indicate whether to use pipe for stderr
 %%% Outputs
 % * status: 0 is generally success. Other codes as per the
 % program / command run
@@ -25,7 +23,7 @@
 %
 % NOTE: if cwd option used, any paths must be absolute, or they are relative to pwd.
 
-function [status, msg] = subprocess_run(cmd, opt)
+function [status, msg, err] = subprocess_run(cmd, opt)
 arguments
   cmd (1,:) string
   opt.env (1,1) struct = struct()
@@ -36,9 +34,13 @@
   opt.echo (1,1) logical = false
 end
 
+err = string.empty;
+% for compatibility with implementations that return stderr separately.
+% Matlab system() returns combined stdout and stderr in msg, and leaves err empty.
+
 
 if ~stdlib.strempty(opt.cwd)
-  assert(isfolder(opt.cwd), opt.cwd + " is not a folder")
+  mustBeFolder(opt.cwd)
 
   cmd = join(["cd", opt.cwd, stdlib.cmdsep(), cmd]);
 end

+stdlib/dotnet_home.m

@@ -1,4 +1,4 @@
-%% JAVA_RUN run process for Matlab only
+%% SUBPROCESS_RUN_JAVA run process using Java ProcessBuilder interface
 %
 % with optional cwd, env. vars, stdin, timeout
 %
@@ -8,30 +8,30 @@
 %
 %%% Inputs
 % * cmd_array: vector of string to compose a command line
-% * opt.env: environment variable struct to set
-% * opt.cwd: working directory to use while running command
-% * opt.stdin: string to pass to subprocess stdin pipe - OK to use with timeout
-% * opt.timeout: time to wait for process to complete before erroring (seconds)
-% * opt.stdout: logical to indicate whether to use pipe for stdout
-% * opt.stderr: logical to indicate whether to use pipe for stderr
+% * env: environment variable struct to set
+% * cwd: working directory to use while running command
+% * stdin: string to pass to subprocess stdin pipe - OK to use with timeout
+% * timeout: time to wait for process to complete before erroring (seconds)
+% * stdout: logical to indicate whether to use pipe for stdout
+% * stderr: logical to indicate whether to use pipe for stderr
 %%% Outputs
 % * status: 0 is generally success. -1 if timeout. Other codes as per the
 % program / command run
 % * stdout: stdout from process
 % * stderr: stderr from process
 %
 %% Example
-% subprocess_run(["mpiexec", "-help2"])
-% subprocess_run(["sh", "-c", "ls", "-l"])
-% subprocess_run(["cmd", "/c", "dir", "/Q", "/L"])
+% subprocess_run_java(["mpiexec", "-help2"])
+% subprocess_run_java(["sh", "-c", "ls", "-l"])
+% subprocess_run_java(["cmd", "/c", "dir", "/Q", "/L"])
 %
 % NOTE: if cwd option used, any paths must be absolute or relative to cwd.
 % otherwise, they are relative to pwd.
 %
 % uses Matlab Java ProcessBuilder interface to run subprocess and use stdin/stdout pipes
 % https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/ProcessBuilder.html
 
-function [status, stdout, stderr] = java_run(cmd, opt)
+function [status, stdout, stderr] = subprocess_run_java(cmd, opt)
 arguments
   cmd (1,:) string
   opt.env (1,1) struct = struct()
@@ -40,8 +40,11 @@
   opt.timeout (1,1) int64 = 0
   opt.stdout (1,1) logical = true
   opt.stderr (1,1) logical = true
+  opt.echo (1,1) logical = false
 end
 
+% opt.echo is unused, but is a real option of subprocess_run()
+
 if (opt.stdout || opt.stderr) && opt.timeout > 0
   error("stderr or stdout and timeout options are mutually exclusive")
 end
@@ -152,7 +155,7 @@
 
 line = reader.readLine();
 while ~isempty(line)
-  msg = stdlib.append(msg, string(line), newline);
+  msg = join([msg, string(line)], newline);
   line = reader.readLine();
 end
 msg = strip(msg);

+stdlib/dotnet_version.m

@@ -59,6 +59,8 @@ to a compatible Java library by using the
 [jenv](https://www.mathworks.com/help/matlab/ref/jenv.html)
 Matlab function.
 
+### macOS JVM configuration
+
 For example, to use the
 [JDK 17 on macOS](https://www.oracle.com/java/technologies/downloads/#jdk17-mac)
 download and extract the ARM64 Compressed Archive.
@@ -74,12 +76,30 @@ Or for the Amazon Corretto JDK 11 on macOS:
 jenv("/Library/Java/JavaVirtualMachines/amazon-corretto-11.jdk/Contents/Home/")
 ```
 
+### Windows JVM configuration
+
 On Windows, obtain OpenJDK with WinGet, which installs under "$Env:ProgramFiles/Microsoft/jdk-*":
 
 ```sh
-winget install Microsoft.OpenJDK.21
+winget search Microsoft.OpenJDK
+```
+
+Suppose OpenJDK 25 is desired and available like:
+
+```sh
+winget install Microsoft.OpenJDK.25
 ```
 
+Then tell Matlab to use this JDK from the Matlab console by:
+
+```matlab
+jp = ls(fullfile(getenv('ProgramFiles'), 'Microsoft/jdk-25*'));
+mustBeTextScalar(jp)
+jp = fullfile(getenv('ProgramFiles'), 'Microsoft', jp);
+jenv(jp)
+
+## Factory Reset JRE
+
 To
 [revert back to the default JRE](https://www.mathworks.com/help/matlab/ref/matlab_jenv.html)
 if Matlab can't start or has problems, from system Terminal (not within Matlab):

+stdlib/subprocess_run.m

@@ -101,7 +101,7 @@
 exes = fullfile(test_root, exes);
 
 plan("exe") = matlab.buildtool.Task(Inputs=srcs, Outputs=exes, Actions=@build_exe, ...
-                 Description="build demo executables for testing java_run");
+                 Description="build demo executables for testing subprocess_run");
 
 end
 

+stdlib/java_run.m +stdlib/subprocess_run_java.m+stdlib/java_run.m renamed to +stdlib/subprocess_run_java.m

@@ -0,0 +1,142 @@
+classdef (Abstract) SubprocessRunAbstract < matlab.unittest.TestCase
+% Abstract base class for testing subprocess_run* functions
+
+properties (Abstract, Constant)
+% Concrete subclasses must define this
+runFcn  % Function handle
+end
+
+properties
+CI = is_ci()
+end
+
+properties (TestParameter)
+lang_out = {"c", "fortran"}
+lang_in = {"cpp", "fortran"}
+end
+
+methods(TestClassSetup)
+function test_dirs(tc)
+tc.applyFixture(matlab.unittest.fixtures.WorkingFolderFixture())
+end
+end
+
+
+methods (Test)
+% Common tests that apply to all implementations
+
+function test_subprocess_cwd(tc)
+
+if ispc
+  if isequal(tc.runFcn, @stdlib.subprocess_run_java)
+    c = ["cmd", "/c", "cd"];
+  else
+    c = "cd";
+  end
+else
+  c = "pwd";
+end
+
+% 'echo' true is optional, just for debugging command.
+debug = true;
+
+[s, m, e] = tc.runFcn(c, 'echo', debug);
+tc.assertEqual(s, 0, "status non-zero")
+tc.verifyGreaterThan(strlength(m), 0, "empty directory not expected")
+
+[s, mc, ec] = tc.runFcn(c, 'cwd', matlabroot, 'echo', debug);
+tc.assertEqual(s, 0, "status non-zero")
+
+if isequal(tc.runFcn, @stdlib.subprocess_run_java)
+  tc.verifyEqual(strlength(e), 0, e)
+  tc.verifyEqual(strlength(e), 0, ec)
+end
+
+tc.assumeFalse(strcmp(m, mc) && tc.CI, "Some CI block cwd changes")
+tc.verifyNotEqual(m, mc, "expected different directory to have different contents")
+end
+
+
+function test_subprocess_env_run(tc)
+
+cwd = fileparts(mfilename('fullpath'));
+exe = cwd + "/printenv.exe";
+tc.assertThat(exe, matlab.unittest.constraints.IsFile)
+
+names = ["TEST1", "TEST2"];
+vals = ["test123", "test321"];
+
+env = struct(names(1), vals(1), names(2), vals(2));
+
+for i = 1:length(names)
+  [ret, out] = tc.runFcn([exe, names(i)], 'env', env);
+  tc.verifyEqual(ret, 0)
+  tc.verifySubstring(out, vals(i))
+end
+end
+
+
+function test_subprocess_stdout_stderr(tc, lang_out)
+
+cwd = fileparts(mfilename('fullpath'));
+exe = fullfile(cwd, "stdout_stderr_" + lang_out + ".exe");
+
+switch lang_out
+  case "fortran", tc.assumeThat(exe, matlab.unittest.constraints.IsFile)
+  case {"c", "cpp"}, tc.assertThat(exe, matlab.unittest.constraints.IsFile)
+  otherwise, tc.assertTrue(false, "Unknown language: " + lang_out)
+end
+
+[status, msg, err] = tc.runFcn(exe);
+
+if ispc()
+  tc.assumeNotEqual(status, -1073741515, "GCC DLLs probably not on PATH")
+end
+
+tc.assertEqual(status, 0, err)
+
+tc.verifySubstring(msg, 'stdout')
+if isequal(tc.runFcn, @stdlib.subprocess_run_java)
+  tc.verifyEqual(err, "stderr")
+else
+  tc.verifySubstring(msg, 'stderr')
+end
+
+[status, msg] = tc.runFcn(exe, 'stdout', false);
+tc.assertEqual(status, 0)
+if isequal(tc.runFcn, @stdlib.subprocess_run_java)
+  tc.verifyTrue(stdlib.strempty(msg))
+elseif isequal(tc.runFcn, @stdlib.subprocess_run)
+  tc.verifyEqual(msg, 'stderr')
+end
+
+[status, msg] = tc.runFcn(exe, 'stderr', false);
+tc.assertEqual(status, 0)
+tc.verifySubstring(msg, 'stdout')
+end
+
+
+function test_subprocess_stdin(tc, lang_in)
+
+cwd = fileparts(mfilename('fullpath'));
+exe = fullfile(cwd, "stdin_" + lang_in + ".exe");
+
+switch lang_in
+  case "fortran", tc.assumeThat(exe, matlab.unittest.constraints.IsFile)
+  case {"c", "cpp"}, tc.assertThat(exe, matlab.unittest.constraints.IsFile)
+  otherwise, tc.assertTrue(false, "Unknown language: " + lang_in)
+end
+
+[status, msg, err] = tc.runFcn(exe, 'stdin', "1 2");
+
+if ispc()
+  tc.assumeNotEqual(status, -1073741515, "GCC DLLs probably not on PATH")
+end
+
+tc.assertEqual(status, 0, err)
+tc.verifyMatches(msg, "^3$")
+tc.verifyTrue(stdlib.strempty(err))
+end
+
+end
+end