Merge pull request #788 from zackgalbreath/github_checks

Add support for creating and updating GitHub checks

Author: acrobat

doc/README.md

@@ -46,6 +46,7 @@ v3 APIs:
   * [Comments](pull_request/comments.md)
 * [Rate Limits](rate_limits.md)
 * [Repositories](repos.md)
+  * [Checks](repo/checks.md)
   * [Contents](repo/contents.md)
   * [Deployments](repo/deployments.md)
   * [Protection](repo/protection.md)

doc/repo/checks.md

@@ -0,0 +1,31 @@
+## Repo / Checks API
+[Back to the "Repos API"](../repos.md) | [Back to the navigation](../README.md)
+
+### Create a check for a commit
+
+[Visit GitHub for a full of list of parameters and their descriptions.](https://developer.github.com/v3/checks/runs/#create-a-check-run)
+
+```php
+$params = [
+  'name' => 'my check', # required
+  'head_sha' => $commitSha, # required
+  'status' => 'pending',
+  'details_url' => 'https://nimbleci.com/...',
+  'output' => {...}
+];
+$checks = $client->api('repo')->checks()->create('NimbleCI', 'docker-web-tester-behat', $params);
+```
+
+### Update an existing check on a commit
+
+https://developer.github.com/v3/checks/runs/#update-a-check-run
+
+```php
+$params = [
+  'name' => 'my check',
+  'status' => 'pending',
+  'details_url' => 'https://nimbleci.com/...',
+  'output' => {...}
+];
+$checks = $client->api('repo')->checks()->create('NimbleCI', 'docker-web-tester-behat', $checkRunId, $params);
+```

lib/Github/Api/Repository/Checks.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Github\Api\Repository;
+
+use Github\Api\AbstractApi;
+use Github\Api\AcceptHeaderTrait;
+use Github\Exception\MissingArgumentException;
+
+/**
+ * @link   https://developer.github.com/v3/checks/
+ *
+ * @author Zack Galbreath <zack.galbreath@kitware.com>
+ */
+class Checks extends AbstractApi
+{
+    use AcceptHeaderTrait;
+
+    /**
+     * @link https://developer.github.com/v3/checks/runs/#create-a-check-run
+     *
+     * @param string $username
+     * @param string $repository
+     * @param array  $params
+     *
+     * @throws MissingArgumentException
+     *
+     * @return array
+     */
+    public function create($username, $repository, array $params = [])
+    {
+        if (!isset($params['name'], $params['head_sha'])) {
+            throw new MissingArgumentException(['name', 'head_sha']);
+        }
+
+        // This api is in preview mode, so set the correct accept-header.
+        $this->acceptHeaderValue = 'application/vnd.github.antiope-preview+json';
+
+        return $this->post('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-runs', $params);
+    }
+
+    /**
+     * @link https://developer.github.com/v3/checks/runs/#update-a-check-run
+     *
+     * @param string $username
+     * @param string $repository
+     * @param string $checkRunId
+     * @param array  $params
+     *
+     * @return array
+     */
+    public function update($username, $repository, $checkRunId, array $params = [])
+    {
+        // This api is in preview mode, so set the correct accept-header.
+        $this->acceptHeaderValue = 'application/vnd.github.antiope-preview+json';
+
+        return $this->patch('/repos/'.rawurlencode($username).'/'.rawurlencode($repository).'/check-runs/'.rawurlencode($checkRunId), $params);
+    }
+}

test/Github/Tests/Api/Repository/ChecksTest.php

@@ -0,0 +1,80 @@
+<?php
+
+namespace Github\Tests\Api\Repository;
+
+use Github\Tests\Api\TestCase;
+
+class ChecksTest extends TestCase
+{
+    /**
+     * @test
+     * @expectedException \Github\Exception\MissingArgumentException
+     */
+    public function shouldNotCreateWithoutHeadSha()
+    {
+        $data = ['name' => 'my check'];
+
+        $api = $this->getApiMock();
+        $api->expects($this->never())
+            ->method('post');
+
+        $api->create('KnpLabs', 'php-github-api', $data);
+    }
+
+    /**
+     * @test
+     * @expectedException \Github\Exception\MissingArgumentException
+     */
+    public function shouldNotCreateWithoutName()
+    {
+        $data = ['head_sha' => 'commitSHA123456'];
+
+        $api = $this->getApiMock();
+        $api->expects($this->never())
+            ->method('post');
+
+        $api->create('KnpLabs', 'php-github-api', $data);
+    }
+
+    /**
+     * @test
+     */
+    public function shouldCreateCheck()
+    {
+        $expectedValue = ['state' => 'success'];
+        $data = ['head_sha' => 'commitSHA123456', 'name' => 'my check'];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('post')
+            ->with('/repos/KnpLabs/php-github-api/check-runs', $data)
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->create('KnpLabs', 'php-github-api', $data));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldUpdateCheck()
+    {
+        $expectedValue = ['state' => 'success'];
+        $data = ['head_sha' => 'commitSHA123456', 'name' => 'my check'];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('patch')
+            ->with('/repos/KnpLabs/php-github-api/check-runs/123', $data)
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->update('KnpLabs', 'php-github-api', '123', $data));
+    }
+
+    /**
+     * @return string
+     */
+    protected function getApiClass()
+    {
+        return \Github\Api\Repository\Checks::class;
+    }
+}