test: add tests

.gitignore

@@ -1 +1,4 @@
+.phpunit.cache/
+.phpunit.result.cache
+docs/coverage/
 vendor/

Makefile

@@ -0,0 +1,18 @@
+.PHONY: all
+all: ./vendor
+
+.PHONY: test
+test: ./vendor
+	./vendor/bin/phpunit tests
+
+.PHONY: lint
+lint: ./vendor
+	./vendor/bin/psalm --show-info=true
+
+docs/coverage: ./vendor $(wildcard src/**.php) $(wildcard tests/**.php)
+	XDEBUG_MODE=coverage ./vendor/bin/phpunit --coverage-html docs/coverage tests
+	@touch $@
+
+./vendor: composer.json composer.lock
+	composer install
+	@touch $@

composer.json

@@ -14,5 +14,12 @@
             "email": "kattendick@bde-software.com"
         }
     ],
-    "require": {}
+    "require": {
+        "php": "^8.4"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^13.0",
+        "vimeo/psalm": "^6.15",
+        "psalm/plugin-phpunit": "^0.19.5"
+    }
 }

phpunit.xml

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         cacheDirectory=".phpunit.cache"
+         executionOrder="depends,defects"
+         requireCoverageMetadata="true"
+         beStrictAboutCoverageMetadata="true"
+         beStrictAboutOutputDuringTests="true"
+         displayDetailsOnPhpunitDeprecations="true"
+         failOnPhpunitDeprecation="true"
+         failOnRisky="true"
+         failOnWarning="true">
+    <testsuites>
+        <testsuite name="unit">
+            <directory>tests/unit</directory>
+        </testsuite>
+        <testsuite name="integration">
+            <directory>tests/integration</directory>
+        </testsuite>
+    </testsuites>
+
+    <source ignoreIndirectDeprecations="true" restrictNotices="true" restrictWarnings="true">
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

psalm.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<psalm
+    errorLevel="2"
+    resolveFromConfigFile="true"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+    findUnusedBaselineEntry="true"
+    findUnusedCode="true"
+>
+    <projectFiles>
+        <directory name="src"/>
+        <directory name="tests"/>
+        <ignoreFiles>
+            <directory name="vendor"/>
+        </ignoreFiles>
+    </projectFiles>
+
+    <issueHandlers>
+    </issueHandlers>
+
+    <plugins>
+        <pluginClass class="Psalm\PhpUnitPlugin\Plugin"/>
+    </plugins>
+</psalm>

tests/integration/CommandIntegrationTest.php

@@ -0,0 +1,188 @@
+<?php
+
+namespace Nih\CommandBuilder;
+
+use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\CoversTrait;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(Child::class)]
+#[CoversClass(ChildException::class)]
+#[CoversClass(ChildStdout::class)]
+#[CoversClass(Command::class)]
+#[CoversClass(ExitStatus::class)]
+#[CoversClass(Output::class)]
+#[CoversClass(Stdio::class)]
+#[CoversTrait(StreamReadTrait::class)]
+#[CoversTrait(StreamWriteTrait::class)]
+final class CommandIntegrationTest extends TestCase
+{
+    public function testStatus(): void
+    {
+        $this->assertTrue(new Command('true')->status()->success());
+    }
+
+    /**
+     * Test that the stdin, stdout, and stderr handles are captured.
+     */
+    public function testOutput(): void
+    {
+        $output = new Command('true')
+            ->stdin(Stdio::null())
+            ->stdout(Stdio::null())
+            ->stderr(Stdio::null())
+            ->output();
+
+        $this->assertTrue($output->status->success());
+    }
+
+    public function testChildOnlyAcceptsProcesses(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+        new Child($handle, []);
+    }
+
+    /**
+     * Test that the stdin, stdout, and stderr handles are captured.
+     */
+    public function testChild(): void
+    {
+        $child = new Command('/usr/bin/sleep')
+            ->stdin(Stdio::null())
+            ->stdout(Stdio::null())
+            ->stderr(Stdio::null())
+            ->arg('1000')
+            ->spawn();
+
+        $this->assertGreaterThan(1, $child->id());
+
+        $child->kill();
+
+        $status = $child->wait();
+
+        $this->assertEquals(null, $status->code());
+        $this->assertEquals(9, $status->signal());
+        $this->assertEquals(null, $status->stoppedSignal());
+
+        // Killing and waiting after the child exited does nothing.
+        $child->kill();
+        $this->assertSame($child->wait(), $status);
+        $output = $child->waitWithOutput();
+        $this->assertSame($output->status, $status);
+        $this->assertSame($child->waitWithOutput(), $output);
+    }
+
+    public function testChildDestructor(): void
+    {
+        $process = proc_open(
+            ['true'],
+            [
+                0 => ['pipe', 'w'],
+                1 => ['pipe', 'r'],
+                2 => ['pipe', 'r'],
+            ],
+            $pipes,
+        );
+
+        $this->assertNotFalse($process);
+
+        $child = new Child($process, $pipes);
+
+        $this->assertEquals('process', get_resource_type($process));
+        $this->assertEquals('stream', get_resource_type($pipes[0]));
+        $this->assertEquals('stream', get_resource_type($pipes[1]));
+        $this->assertEquals('stream', get_resource_type($pipes[2]));
+
+        unset($child);
+        gc_collect_cycles();
+
+        $this->assertEquals('Unknown', get_resource_type($process));
+        $this->assertEquals('Unknown', get_resource_type($pipes[0]));
+        $this->assertEquals('Unknown', get_resource_type($pipes[1]));
+        $this->assertEquals('Unknown', get_resource_type($pipes[2]));
+    }
+
+    public function testStdio(): void
+    {
+        if (PHP_OS_FAMILY === 'Windows') {
+            $this->markTestSkipped();
+        }
+
+        $cat = new Command('cat')
+            ->stdin(Stdio::piped())
+            ->stdout(Stdio::piped())
+            ->stderr(Stdio::piped())
+            ->spawn();
+
+        $cat->stdin?->write('Hello, World!');
+        $cat->stdin?->close();
+
+        $this->assertNotNull($cat->stdout);
+
+        $output = new Command('cat')
+            ->stdin($cat->stdout)
+            ->output();
+
+        $this->assertTrue($cat->wait()->success());
+        $this->assertTrue($output->status->success());
+
+        $this->assertEquals('Hello, World!', $output->stdout);
+        $this->assertEquals('', $output->stderr);
+    }
+
+    public function testThrowsOnNotExecutable(): void
+    {
+        $this->expectException(ChildException::class);
+        new Command(uniqid())->spawn();
+    }
+
+    public function testEnv(): void
+    {
+        if (PHP_OS_FAMILY === 'Windows') {
+            $this->markTestSkipped();
+        }
+
+        $output = new Command('env')
+            ->envClear()
+            ->envs([
+                'FOO' => 'foo',
+                'BAR' => 'bar',
+                'BAZ' => 'baz',
+            ])
+            ->envRemove('FOO')
+            ->output();
+
+        $this->assertTrue($output->status->success());
+        $this->assertEquals("BAR=bar\nBAZ=baz\n", $output->stdout);
+    }
+
+    public function testEnvInherit(): void
+    {
+        if (PHP_OS_FAMILY === 'Windows') {
+            $this->markTestSkipped();
+        }
+
+        $home = getenv('HOME');
+        $this->assertIsString($home, 'Congratulations! You have a weird system');
+
+        $child = new Command('env')
+            ->stdout(Stdio::piped())
+            ->env('FOO', 'foo')
+            ->spawn();
+
+        $this->assertNotNull($child->stdout);
+
+        $envs = [];
+        foreach (explode(PHP_EOL, $child->stdout->getContents()) as $line) {
+            [$var, $val] = explode('=', $line);
+            $envs[$var] = $val;
+        }
+
+        $this->assertEquals($home, $envs['HOME']);
+        $this->assertEquals('foo', $envs['FOO']);
+    }
+}

tests/unit/CommandTest.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace Nih\CommandBuilder;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use ValueError;
+
+#[CoversClass(Command::class)]
+#[CoversClass(Stdio::class)]
+#[CoversClass(StreamException::class)]
+#[CoversClass(ChildException::class)]
+final class CommandTest extends TestCase
+{
+    public function testChildErrorHandling(): void
+    {
+        $this->expectException(ChildException::class);
+
+        try {
+            set_error_handler(ChildException::handleError(...));
+            trigger_error('Oh no!');
+        } finally {
+            restore_error_handler();
+        }
+    }
+
+    public function test(): void
+    {
+        $command = new Command('echo');
+
+        $this->assertEquals(
+            'echo',
+            $command->getProgram(),
+        );
+
+        $this->assertNull($command->getCurrentDir());
+
+        $command->currentDir('/tmp');
+
+        $this->assertEquals(
+            '/tmp',
+            $command->getCurrentDir(),
+        );
+
+        $command->arg('foo')->args(['bar', 'baz']);
+
+        $this->assertEquals(
+            ['foo', 'bar', 'baz'],
+            $command->getArgs(),
+        );
+
+        $command->env('FOO', 'foo');
+
+        $this->assertEquals(
+            ['FOO' => 'foo'],
+            $command->getEnvs(),
+        );
+
+        $command->envs([
+            'BAR' => 'bar',
+            'BAZ' => 'baz',
+        ]);
+
+        $this->assertEquals(
+            [
+                'FOO' => 'foo',
+                'BAR' => 'bar',
+                'BAZ' => 'baz',
+            ],
+            $command->getEnvs(),
+        );
+
+        $command->envRemove('BAR');
+
+        $this->assertEquals(
+            [
+                'FOO' => 'foo',
+                'BAR' => null,
+                'BAZ' => 'baz',
+            ],
+            $command->getEnvs(),
+        );
+
+        $command->envClear();
+
+        $this->assertEquals(
+            [],
+            $command->getEnvs(),
+        );
+    }
+
+    public function testStdioFromStream(): void
+    {
+        // Only verifies its okay to pass valid stream resources.
+        $this->expectNotToPerformAssertions();
+
+        new Command('echo')
+            ->stdin(STDIN)
+            ->stdout(STDOUT)
+            ->stderr(STDERR);
+    }
+
+    public function testThrowsOnEmptyProgram(): void
+    {
+        $this->expectException(ValueError::class);
+        new Command('');
+    }
+
+    public function testToString(): void
+    {
+        $this->assertEquals(
+            "'ls' '*' 'foo bar'",
+            (string) new Command('ls')->arg('*')->arg('foo bar'),
+        );
+    }
+}

tests/unit/StdioTest.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Nih\CommandBuilder;
+
+use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(Stdio::class)]
+final class StdioTest extends TestCase
+{
+    public function testNull(): void
+    {
+        $null = match (PHP_OS_FAMILY) {
+            'Windows' => 'nul',
+            default => '/dev/null',
+        };
+
+        $this->assertEquals(
+            ['file', $null, 'r'],
+            Stdio::null()->getDescriptiorSpec(0),
+        );
+
+        $this->assertEquals(
+            ['file', $null, 'w'],
+            Stdio::null()->getDescriptiorSpec(1),
+        );
+
+        $this->assertEquals(
+            ['file', $null, 'w'],
+            Stdio::null()->getDescriptiorSpec(2),
+        );
+    }
+
+    public function testInherit(): void
+    {
+        $this->assertEquals(
+            STDIN,
+            Stdio::inherit()->getDescriptiorSpec(0),
+        );
+
+        $this->assertEquals(
+            STDOUT,
+            Stdio::inherit()->getDescriptiorSpec(1),
+        );
+
+        $this->assertEquals(
+            STDERR,
+            Stdio::inherit()->getDescriptiorSpec(2),
+        );
+    }
+
+    public function testFile(): void
+    {
+        $this->assertEquals(
+            ['file', '/foo/bar/baz', 'r'],
+            Stdio::file('/foo/bar/baz', 'r')->getDescriptiorSpec(0),
+        );
+    }
+
+    public function testStream(): void
+    {
+        $this->assertEquals(
+            STDOUT,
+            Stdio::stream(STDOUT)->getDescriptiorSpec(0),
+        );
+    }
+
+    public function testThrowsOnInvalidStream(): void
+    {
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+
+        fclose($handle);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        /** @psalm-suppress InvalidArgument */
+        Stdio::stream($handle);
+    }
+}

tests/unit/StreamTest.php

@@ -0,0 +1,154 @@
+<?php
+
+namespace Nih\CommandBuilder;
+
+use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\CoversTrait;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ChildStdin::class)]
+#[CoversClass(ChildStdout::class)]
+#[CoversClass(ChildStderr::class)]
+#[CoversClass(ChildException::class)]
+#[CoversClass(StreamException::class)]
+#[CoversTrait(StreamTrait::class)]
+#[CoversTrait(StreamReadTrait::class)]
+#[CoversTrait(StreamWriteTrait::class)]
+final class StreamTest extends TestCase
+{
+    public function testErrorHandler(): void
+    {
+        $this->expectException(StreamException::class);
+
+        try {
+            set_error_handler(StreamException::handleError(...));
+            trigger_error('Oh no!');
+        } finally {
+            restore_error_handler();
+        }
+    }
+
+
+    public function testOnlyAcceptsStreamResource(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $handle = fopen('php://memory', 'w+');
+        $this->assertNotFalse($handle);
+
+        fwrite($handle, 'test');
+        fclose($handle);
+
+        /** @psalm-suppress InvalidArgument */
+        new class($handle) {
+            use StreamTrait;
+        };
+    }
+
+    public function testReadRead(): void
+    {
+        $handle = fopen('php://memory', 'w+');
+        $this->assertNotFalse($handle);
+
+        fwrite($handle, 'test');
+        fseek($handle, 0);
+
+        $r = new class($handle) {
+            use StreamReadTrait;
+        };
+
+        $this->assertEquals('test', $r->read(4));
+        $this->assertEmpty($r->read(4));
+        $r->close();
+        $this->expectException(StreamException::class);
+        $r->read(4);
+    }
+
+    public function testReadGetContents(): void
+    {
+        $handle = fopen('php://memory', 'w+');
+        $this->assertNotFalse($handle);
+
+        fwrite($handle, 'test');
+        fseek($handle, 0);
+
+        $r = new class($handle) {
+            use StreamReadTrait;
+        };
+
+        $this->assertEquals('test', $r->getContents());
+        $this->assertEmpty($r->getContents());
+        $r->close();
+        $this->expectException(StreamException::class);
+        $r->getContents();
+    }
+
+    public function testWriteWrite(): void
+    {
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+
+        $w = new class($handle) {
+            use StreamWriteTrait;
+        };
+
+        $this->assertEquals(4, $w->write('test'));
+        $w->close();
+        $this->expectException(StreamException::class);
+        $w->write('test');
+    }
+
+    public function testWriteFlush(): void
+    {
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+
+        $w = new class($handle) {
+            use StreamWriteTrait;
+        };
+
+        $w->flush();
+        $w->close();
+        $this->expectException(StreamException::class);
+        $w->flush();
+    }
+
+    public function testChildStdin(): void
+    {
+        $handle = fopen('php://memory', 'w');
+        $this->assertNotFalse($handle);
+
+        $stdin = new ChildStdin($handle);
+
+        $this->assertEquals(
+            $handle,
+            $stdin->getDescriptiorSpec(0),
+        );
+    }
+
+    public function testChildStdout(): void
+    {
+        $handle = fopen('php://memory', 'r');
+        $this->assertNotFalse($handle);
+
+        $stdout = new ChildStdout($handle);
+
+        $this->assertEquals(
+            $handle,
+            $stdout->getDescriptiorSpec(1),
+        );
+    }
+
+    public function testChildStderr(): void
+    {
+        $handle = fopen('php://memory', 'r');
+        $this->assertNotFalse($handle);
+
+        $stderr = new ChildStderr($handle);
+
+        $this->assertEquals(
+            $handle,
+            $stderr->getDescriptiorSpec(2),
+        );
+    }
+}