process_run test helpers (process_run_test)
process_run_test is the test support package of process_run: a tiny echo
program you compile and spawn to get exactly the stdout, stderr, exit code and
stdin behaviour a test needs, plus two shared test suites that any
implementation can run against itself. Nothing here is meant to ship in an
application.
Guidelines
- Dependency (git only, not on pub.dev), always in
dev_dependencies:
It bringsdev_dependencies: process_run_test: git: url: https://github.com/tekartik/process_run.dart path: packages/process_run_testprocess_run(pub.dev),args,path,pub_semver,synchronizedandtest. Inside the repo it resolvesprocess_runthrough adependency_overridespath to the sibling package; a consumer gets the published one. - Everything is
dart:iobased: start such a test file with@TestOn('vm')+library;and run it withdart test. - Drive the test programs with
Shell(runExecutableArguments,throwOnError: false), aShellLinesControllerfor their stdin (binaryStream,write,close()= end of input) and one for their stdout lines (sink,stream),onProcessfor theProcess, neverdart:ioProcess.start: see the process-run-shell skill, "Driving a program";test/child_test.dartandtest/shared_stdin_test.dartshow it. - Public entry points (five, plus the echo, child and shared stdin child
sources):
package:process_run_test/echo/compile_echo.dart:Future<String> compileEcho({String? path, bool force = false, bool? verbose}).package:process_run_test/child/compile_child.dart:Future<String> compileChild({String? path, bool force = false, bool? verbose}),childVersion,int childSignalExitCode(ProcessSignal signal)(-9forsigkill, the exit code of a killed process on Linux and macOS).package:process_run_test/shared_stdin/compile_shared_stdin_child.dart:Future<String> compileSharedStdinChild({String? path, bool? verbose}),sharedStdinChildVersion.package:process_run_test/echo_test.dart:EchoTestContextandvoid echoTests(EchoTestContext testContext, {bool supportsStdin = true, bool supportsBinaryOutput = true}).package:process_run_test/shell_core_test.dart:void shellCoreTests(ShellContext shellContext).package:process_run_test/echo/echo.dartis the echomainitself; it is compiled, not imported.lib/src/process_run_import.dartis internal: importpackage:process_run/shell.dartinstead.
compileEcho()runsdart compile exe lib/echo/echo.dart -o <path>/build/<linux|macos|windows>/process_run_echo[.exe]and returns that absolute path. It compiles relative topath(the current directory whenpathis null), sopathmust be the root of theprocess_run_testpackage checkout. From another package, resolve it once withIsolate.resolvePackageUri(Uri.parse('package:process_run_test/echo/echo.dart'))and pass the package root aspath. The binary is written tobuild/inside that same directory (so inside the pub cache for a git dependency); compile it once in asetUpAll. The result is cached: an existing binary whose--versionmatchesechoVersionis reused,force: truerecompiles,verbose: trueshows the compile command.compileEcho(),compileChild()andcompileSharedStdinChild()are serialized (aLock: concurrent calls compile once); the first two check an existing binary once per process.- The child program (
compileChild(),build/<os>/process_run_child[.exe], samepathrule) is the process to kill: it waits (--wait <ms>, 60 s by default, then exits with--exit-code <n>), starts a chain of descendants with--depth <n>(same options, one level less), and writesready <pid>once it and its descendants are started (theirs first, soready <rootPid>is the last line: wait for it, the lines give the pids of the tree).--sigterm-exit-code <n>and--sigint-exit-code <n>catch the signal, writesignal SIGTERM/signal SIGINTand exit withn;--ignore-sigtermcatches it and keeps running (the sigkill fallback ofShell.kill()). Sigterm cannot be caught on Windows, and sigkill nowhere: checkchildSignalExitCode(ProcessSignal.sigkill)(-9) on Linux and macOS, a non zero code on Windows. Read the lines withShell(stdout: ShellLinesController().sink)and get theProcess(itsexitCode) withonProcess;test/child_test.dartshows the pattern. - The shared stdin child (
compileSharedStdinChild(),build/<os>/process_run_shared_stdin_child[.exe], samepathrule) reads its input throughsharedStdInlike a tool and printsdoneoncesharedStdIn.terminate()returned. Modes (first argument):lines(reads until the end of input, printslines: a,b),shell(runs itself ascatwithShell(stdin: sharedStdIn), printsout: <its output>),cat,terminate(printsready, a line then written is pending, unread, atterminate()),prompt(prompt('name')at the end of input, printsno inputon theStateError),--version. Compiled on every call, unlike echo and child: it embeds process_run, a binary reused while its version is the same would test an older process_run. It also runs from its source (dart run lib/shared_stdin/shared_stdin_child.dart <mode>): a program embedding process_run is tested both ways, astest/shared_stdin_test.dartdoes (one group each). - Quote the returned path with
shellArgument(echoPath)before putting it in ashell.run('...')script (it is absolute and may contain spaces); pass it raw torunExecutableArguments(echoPath, [...]). - echo options, all optional and combinable:
--stdout <text>/-o,--stderr <text>/-e,--stdout-hex <hex>/-pand--stderr-hex <hex>/-f(raw bytes, upper or lower case, any other character such as a space is ignored; read them withstdoutEncoding: null/stderrEncoding: null),--stdin/-i(echo the first stdin line to stdout),--write-line/-l(add a trailing newline),--exit-code <n>/-x(a non numeric value crashes with exit code 255),--wait <ms>,--stdout-env <VAR>(echo an environment variable),--all-env(the wholeShellEnvironmentas pretty json),--version,--help. Remaining positional arguments are written as lines to stdout. With no argument at all it exits 0 having written nothing. echoTests(EchoTestContext(echoPath))defines the shared echo suite (stdout, stderr, binary output, environment, stdin, exit codes, crash) inside the currentgroup. UseEchoTestContext.lazy(() => echo)when the path is only known insetUpAll, sinceechoTestsruns at collection time. The shell under test isShell()made in itssetUpAll, so the globalshellContext: set that global to test another context (arunZonedaround the declarations does not reach the test bodies), and passsupportsStdin: false/supportsBinaryOutput: falseto skip the stdin and binary output tests on a context that cannot do them. Run it to validate aprocess_runchange, or as a smoke test that spawning processes works in your environment.shellCoreTests(shellContext)defines the sharedShellsuite (runCommand,runScript,run,ShellCommand.parse,outText,processExecutableArguments, zonedShellEnvironmentvars). Pass the platformshellContext(real processes) orShellContextMemory()/shellContextMemory(in memory, no process spawned, safe on any platform), both frompackage:process_run/utils/shell_context.dart. A memory run is usually wrapped inshellContextMemory.runZoned(() async => shellCoreTests(shellContext))so the zoned context is the memory one. Implementing your ownShellContext? Run this suite against it.- The
example/directory of the package holds runnable demos ofpackage:process_run/stdio.dartline grouping (shellStdioLinesGrouper.runZoned(...)), useful when debugging interleaved stdout/stderr output of concurrent tasks:dart run example/stdout_lines_grouper_example1.dart. - Anti-patterns: depending on
process_run_testat runtime; callingcompileEcho()from a working directory that is not the package root; hard codingbuild/linux/process_run_echoinstead of using the returned path; running these tests on the web or in a sandbox without a Dart SDK (the compile step needsdart).
Examples
Run the shared echo suite from your own package
@TestOn('vm')
library;
import 'dart:isolate';
import 'package:path/path.dart';
import 'package:process_run_test/echo/compile_echo.dart';
import 'package:process_run_test/echo_test.dart';
import 'package:test/test.dart';
/// Root of the process_run_test package in the pub cache or in a path dep.
Future<String> processRunTestPackageRoot() async {
var uri = await Isolate.resolvePackageUri(
Uri.parse('package:process_run_test/echo/echo.dart'),
);
// <root>/lib/echo/echo.dart -> <root>
return normalize(join(dirname(uri!.toFilePath()), '..', '..'));
}
void main() {
late String echo;
setUpAll(() async {
echo = await compileEcho(path: await processRunTestPackageRoot());
});
echoTests(EchoTestContext.lazy(() => echo));
}
Use the echo executable in your own tests
@TestOn('vm')
library;
import 'dart:async';
import 'package:process_run/shell.dart';
import 'package:process_run_test/echo/compile_echo.dart';
import 'package:test/test.dart';
void main() {
late String echo;
late Shell shell;
setUpAll(() async {
echo = await compileEcho();
shell = Shell(options: ShellOptions(throwOnError: false, verbose: false));
});
test('exit code and streams', () async {
var result = await shell.runExecutableArguments(echo, [
'--stdout',
'out',
'--stderr',
'err',
'--exit-code',
'123',
]);
expect(result.stdout, 'out');
expect(result.stderr, 'err');
expect(result.exitCode, 123);
});
test('binary output', () async {
var binShell = shell.cloneWithOptions(ShellOptions(stdoutEncoding: null));
var result = await binShell.runExecutableArguments(echo, [
'--stdout-hex',
'010203',
]);
expect(result.stdout, [1, 2, 3]);
});
test('stdin', () async {
var inCtrl = StreamController<List<int>>();
var stdinShell = shell.cloneWithOptions(ShellOptions(stdin: inCtrl.stream));
var resultFuture = stdinShell.runExecutableArguments(echo, ['--stdin']);
inCtrl.add('in'.codeUnits);
await inCtrl.close();
expect((await resultFuture).stdout, 'in');
});
test('in a script', () async {
// Absolute path: quote it.
await shell.run('${shellArgument(echo)} --stdout hello --write-line');
});
}
Run the shared shell suite on the real and the memory context
import 'package:process_run/utils/shell_context.dart';
import 'package:process_run_test/shell_core_test.dart';
import 'package:test/test.dart';
Future<void> main() async {
group('io', () {
shellCoreTests(shellContext);
});
group('memory', () {
// Everything inside the zone sees the memory shell context.
shellContextMemory.runZoned(() async {
shellCoreTests(shellContext);
});
});
}
Validate your own ShellContext implementation
import 'package:process_run/utils/shell_context.dart';
import 'package:process_run_test/shell_core_test.dart';
void defineTests(ShellContext myContext) {
// The suite only uses shell(), newShellEnvironment(), copyWith() and
// runZoned(): a context that passes it behaves like the platform one.
shellCoreTests(myContext);
}
Commands
# From the process_run_test package itself
dart test # compiles echo, runs every suite
dart run example/stdio_lines_grouper_example.dart