@postlight/ci-failed-test-reporter - npm Package Compare versions

Comparing version 1.0.16 to 1.0.17

package.json

 {
   "name": "@postlight/ci-failed-test-reporter",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "main": "dist/index.js",
@@ -5,0 +5,0 @@ "description": "📝 A tool for outputting JSON test reports as PR comments",

README.md

 # CI Failed Test Reporter
 
-![A PR comment posted with the CI Failed Test Reporter](/readme-images/screenshot.png "CI Failed Test Reporter Screenshot")
+![A PR comment posted with the CI Failed Test Reporter](/readme-assets/demo.gif "CI Failed Test Reporter Screenshot")
 
-A familiar scene: you open up a PR only to see that your CircleCI build failed because of some tests that didn't pass. But which tests? GitHub won't tell you. Your best options for finding out include opening a console and running your test suite locally or manually sifting through the CI logs, and neither of these is as efficient as you'd like. 
+A familiar scene: you open up a PR only to see that your CI build failed because of some tests that didn't pass. But which tests? GitHub won't tell you. Your best options for finding out include opening a console and running your test suite locally or manually sifting through the CI logs, and neither of these is as efficient as you'd like. 
 
-This tool was built to facilitate this process—when your CI build breaks due to failing tests, it reads the JSON test report generated by Jest, formats it into markdown, and posts it as a comment directly on your PR. With this tool, you can see which tests broke the build in the same place you find out it's broken, no context-switching necessary.
+This tool was built to facilitate this process—when your CI build breaks due to failing tests, it reads the JSON test report generated by your testing framework, formats it into markdown, and posts it as a comment directly on your PR. With this tool, you can see which tests broke the build in the same place you find out it's broken, no context-switching necessary.
 
-## Setup
+## Installation
 
-### Installation
+```bash
+yarn add @postlight/ci-failed-test-reporter
 
-This tool is published as an npm package, so installing it is as easy as running `yarn add @postlight/ci-failed-test-reporter` or `npm install @postlight/ci-failed-test-reporter`, depending on your tool of choice.
+# or
 
-### Notes on testing frameworks
+npm install @postlight/ci-failed-test-reporter
+```
 
+### Note on testing frameworks
+
 This package is currently only compatible with JSON test results generated by [Jest](https://jestjs.io/), but we're hoping to add additional support in the future.
 
-### CircleCI config
+## Usage
 
-This tool currently only works with CircleCI, but we're looking into opening it up to other CI solutions. If you haven't set up CircleCI yet, head over to [this page](https://circleci.com/docs/2.0/getting-started/#section=getting-started) to get started. After you've created your `.circleci/config.yml` file, there are two `run` blocks you'll need to add to it, detailed below.
+The basic usage is simple: First, you'll run your Jest tests with the flag to save results to JSON:
 
+```bash
+jest --json --outputFile test-output.json
+```
+
+You'll likely want to add this as a script to your `package.json`, like so:
+
+```json
+  "scripts": {
+    "test-with-output": "jest --json --outputFile test-output.json",
+  }
+```
+
+Next, you run `ciftr` (**ci**-**f**ailed-**t**est-**r**eporter) to parse the test results and report failed tests:
+
+```bash
+yarn ciftr test-output.json
+```
+
+Before that will work in your CI environment, you'll need to do two things:
+
+1. Set up your CI config
+2. [Create a GitHub API key](#setting-up-your-github-api-key-environment-variable) and add it to your CI environment variables
+
+> Currently, this tool currently only works with CircleCI, but we're looking into opening it up to other CI solutions. 
+
+## CI Setup
+
+This tool has only been tested using CircleCI, but should be able to work with any CI solution that allows you to set the proper environment variables. Below, we've outlined the process for setting up a CircleCI config for use with the tool. The process should be somewhat similar across CI solutions—make sure to look at the CI tool's docs to determine what needs to be done differently.
+
+### Setting up a CircleCI config
+
+To set things up with CircleCI, there are two `run` blocks you'll need to add to your `.circleci/config.yml` file.
+
+First, set up your environment variables.
+
 ```yml
 # exports CircleCI env variables so they can be referenced in your code
-# put this near the top of your yml file, like after the `checkout` step
+# put this near the top of your job, e.g., after the `checkout` step
 - run:
@@ -36,2 +75,4 @@ name: Define Environment Variables at Runtime
 
+Next, after you run your tests (the `yarn test` command below is set up like we have it in the script above), you'll run `ciftr`:
+
 ```yml
@@ -41,31 +82,13 @@ - run: yarn test
     name: Upload Test Report
-    command: yarn ciftr /path-to-test-report.json
-    when: on_fail
+    command: yarn ciftr test-report.json # this should mirror whereever you've saved your test results
+    when: on_fail # only run this when tests have failed
 ```
 
-You can check out [this repo's CircleCI config](/.circleci/config.yml) for an example, but be careful not to copy and paste the `Upload Test Report` command, as it's set up for this repo specifically and won't work with yours.
+You can check out [this CircleCI config](.circleci/config.example.yml) for a full working example. The only thing you will definitely want to change is the `working_directory` value, which should be changed to the name of your repo. Note that this config assumes you're saving your test reports as `/test-report.json` in the root directory.
 
-### `package.json` setup
+### Setting Up Your GitHub API Key Environment Variable
 
-You will need to make sure that you have a `package.json` test script that is set up to write test results to a file in the root directory of your repo. This test script then needs to be invoked during the test step of your CircleCI build process. 
+The only environment variable you need to define for use through the CircleCI webapp is `GITHUB_API_KEY`, which must be populated with your GitHub API key. This can be the API key of any user with access to the repo—at Postlight, we've created a `postlight-bot` user and recommend you do similar. In order to create a GitHub API key, start [here](https://github.com/settings/tokens). The rest of the necessary environment variables are built into CircleCI and are exported in your CircleCI config file, as detailed [above](#Set up your CircleCI config).
 
-Using Jest, your `package.json`'s `scripts` section would look something like: 
-
-```json
-  "scripts": {
-    // [...any other scripts...]
-    "test-with-output": "jest --json --outputFile test-output.json",
-    // [...any other scripts...]
-  },
-```
-
-Check out [this repo's package.json](/package.json) if you'd like a firsthand look at an example.
-
-### Environment variables
-
-The only environment variable you need to define for use with CircleCI is `GITHUB_API_KEY`, which must be populated with your GitHub API key. This can be the API key of any user with access to the repo—at Postlight we've so far used it with our `postlight-bot` user, and creating your own bot might be a useful idea. The rest of the necessary environment variables are built in to CircleCI and are exported in your CircleCI config file, as detailed [above](#CircleCI Config).
-
-```markdown
 ---
-A micro project from your friends at [Postlight Labs](https://postlight.com/labs)
-```
+🔬 A project from your friends at [Postlight Labs](https://postlight.com/labs)

src/index.js

@@ -13,9 +13,19 @@ const dotenv = require('dotenv');
 
-  if (!username || !repoName || !prNumber || !apiKey) {
+  if (!prNumber) {
+    console.log('test report not uploaded to github; PR was not detected');
+    return;
+  }
+
+  if (!username || !repoName || !apiKey) {
     const undefinedVars = [];
-    if (!username)  { undefinedVars.push("Username") }
-    if (!repoName)  { undefinedVars.push("Repo Name") }
-    if (!prNumber)  { undefinedVars.push("PR Number") }
-    if (!apiKey)  { undefinedVars.push("GitHub API Key") }
-    throw `${undefinedVars.join(", ")} env variables must not be undefined`;
+    if (!username) {
+      undefinedVars.push('Username');
+    }
+    if (!repoName) {
+      undefinedVars.push('Repo Name');
+    }
+    if (!apiKey) {
+      undefinedVars.push('GitHub API Key');
+    }
+    throw `${undefinedVars.join(', ')} env variables must not be undefined`;
   }
@@ -41,3 +51,3 @@ const body = stripAnsi(getTestReport(filepath));
     } else {
-      throw "Error posting GitHub request";
+      throw 'Error posting GitHub request';
     }
@@ -44,0 +54,0 @@ });

src/tests/getTestReport.test.js

 import stripAnsi from 'strip-ansi';
 
 import getTestReport from '../getTestReport';
-import sampleReport from './sample-report';
 
-test('Generates a test report', () => {
-  // don't test the whitespace formatting, just the content
-  const testReport = stripAnsi(
-    getTestReport(__dirname + '/test-output.test.json')
-  ).replace(/\s/g, '');
-  expect(testReport).toBe(sampleReport.replace(/[\s]*/g, ''));
-});
+describe('getTestReport', () =>
+  test('Generates a test report', () => {
+    // don't test the whitespace formatting, just the content
+    const testReport = stripAnsi(
+      getTestReport(__dirname + '/test-output.test.json')
+    ).replace(/\s/g, '');
+    expect(testReport.startsWith('<details>')).toBeTruthy();
+  }));

src/tests/index.test.js

 import { getReport } from '../index';
-import sampleReport from './sample-report';
 
-test('getReport: returns formatted test report', () => {
-  // don't test the whitespace formatting, just the content
-  const testReport = getReport(__dirname + '/test-output.test.json').replace(
-    /\s/g,
-    ''
-  );
-  expect(testReport).toBe(sampleReport.replace(/[\s]*/g, ''));
-});
+describe('getReport', () =>
+  test('returns formatted test report', () => {
+    // don't test the whitespace formatting, just the content
+    const testReport = getReport(__dirname + '/test-output.test.json').replace(
+      /\s/g,
+      ''
+    );
+    expect(testReport.startsWith('<details>')).toBeTruthy();
+  }));

No alert changes

Improved metrics

Number of package files

24

increased by4.35%

Lines of code

267

increased by3.49%

Number of lines in readme file

93

increased by32.86%

Worsened metrics

Total package byte prevSize

427087

decreased by-8.49%

No dependency changes