[IST-460] Helpful Doc Improvements and Moment Update (#55)

.github/workflows/pr-workflow.yaml

@@ -6,7 +6,7 @@ jobs:
  name: Mabl Test
  runs-on: ubuntu-latest
  steps:
- - uses: actions/checkout@main
+ - uses: actions/checkout@v3
 
  - name: Install dependencies
  run: npm ci

.github/workflows/push-workflow.yaml

@@ -7,7 +7,7 @@ jobs:
  name: Mabl Test
  runs-on: ubuntu-latest
  steps:
- - uses: actions/checkout@main
+ - uses: actions/checkout@v3
 
  - name: Install dependencies
  run: npm ci

README.md

@@ -7,6 +7,8 @@ test runs associated with that deployment and waiting for their results.
 
 For more complex use cases, see the [setup-mabl-cli](https://github.com/marketplace/actions/setup-mabl-cli) Action to access the CLI directly.
 
+To view rich GitHub commit and pull requests information in the mabl app, [install the mabl GitHub App](https://help.mabl.com/docs/github-integration-setup) in _addition_ to using this action.
+
 ### Example workflow: Simple
 
 ```
@@ -19,12 +21,13 @@ jobs:
  name: mabl Test
  runs-on: ubuntu-latest
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v3
 
  - name: Functional test deployment
  id: mabl-test-deployment
  uses: mablhq/github-run-tests-action@v1
  env:
+ # Use a "CI/CD Integration" type of mabl API key
  MABL_API_KEY: ${{ secrets.MABL_API_KEY }}
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
@@ -46,12 +49,13 @@ jobs:
  name: mabl Test
  runs-on: ubuntu-latest
  steps:
- - uses: actions/checkout@v2
+ - uses: actions/checkout@v3
 
  - name: Functional test deployment
  id: mabl-test-deployment
  uses: mablhq/github-run-tests-action@v1
  env:
+ # Use a "CI/CD Integration" type of mabl API key
  MABL_API_KEY: ${{ secrets.MABL_API_KEY }}
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
@@ -78,8 +82,8 @@ jobs:
 
 ### Environment variables
 
-- `MABL_API_KEY` {string} - Your mabl API key
- [available here](https://app.mabl.com/workspaces/-/settings/apis) This should
+- `MABL_API_KEY` {string} - Create a "CI/CD Integration" type mabl API key
+ [here](https://app.mabl.com/workspaces/-/settings/apis). This should
  be installed as a secret in your GitHub repository.
 - `GITHUB_TOKEN` {string} (optional) - The GitHub token for your repository. If
  provided, the mabl action will associate a pull request with the deployment if

package.json

@@ -1,6 +1,6 @@
 {
  "name": "mabl-github-deployments-action",
- "version": "1.11.0",
+ "version": "1.12.0",
  "description": "mabl github action for GitHub pipelines integration",
  "main": "lib/src/index.js",
  "scripts": {
@@ -21,7 +21,7 @@
  "async-retry": "1.3.3",
  "axios": "0.26.1",
  "cli-table3": "0.6.1",
- "moment": "2.29.2"
+ "moment": "2.29.4"
  },
  "devDependencies": {
  "@types/async-retry": "1.4.3",

src/mablApiClient.ts

@@ -2,7 +2,7 @@ import retry from 'async-retry';
 import {Application} from './entities/Application';
 import {Deployment, DeploymentProperties} from './entities/Deployment';
 import {ExecutionResult} from './entities/ExecutionResult';
-import axios, {AxiosInstance, AxiosRequestConfig} from 'axios';
+import axios, {AxiosInstance, AxiosRequestConfig, AxiosResponse} from 'axios';
 import {Environment} from './entities/Environment';
 import {USER_AGENT} from './constants';
 
@@ -30,14 +30,37 @@ export class MablApiClient {
  this.httpClient = axios.create(config);
  }
 
+ /**
+ * Throw helpful error messages, if possible, otherwise throw generic error
+ * @param response error response
+ */
+ static throwHumanizedError(response: AxiosResponse): never {
+ switch (response.status) {
+ case 401:
+ throw new Error(
+ `Unauthorized API error, are you sure you passed the correct API key? Is the key "enabled"?`,
+ );
+ case 403:
+ throw new Error(
+ `Forbidden API error, are you sure you used a "CI/CD Integration" type API key? Ensure this key is for the same workspace you're testing.`,
+ );
+ case 404:
+ throw new Error(
+ `Not Found API error, please ensure any environment or application IDs in your Action config are correct.`,
+ );
+ default:
+ throw new Error(`[${response.status} - ${response.statusText}]`);
+ }
+ }
+
  async makeGetRequest<T>(url: string): Promise<T> {
  return retry(
  async () => {
  const response = await this.httpClient.get<T>(url, {
  timeout: GET_REQUEST_TIMEOUT_MILLIS,
  });
  if ((response.status ?? 400) >= 400) {
- throw new Error(`[${response.status} - ${response.statusText}]`);
+ MablApiClient.throwHumanizedError(response);
  }
  return response.data;
  },
@@ -69,7 +92,7 @@ export class MablApiClient {
  async getApplication(id: string): Promise<Application> {
  try {
  return await this.makeGetRequest<Application>(
- `${this.baseUrl}/v1/applications/${id}`,
+ `${this.baseUrl}/applications/${id}`,
  );
  } catch (error) {
  throw new Error(
@@ -81,7 +104,7 @@ export class MablApiClient {
  async getEnvironment(id: string): Promise<Environment> {
  try {
  return await this.makeGetRequest<Environment>(
- `${this.baseUrl}/v1/environments/${id}`,
+ `${this.baseUrl}/environments/${id}`,
  );
  } catch (error) {
  throw new Error(

test/suite.test.ts

@@ -1,5 +1,5 @@
 import {MablApiClient} from '../src/mablApiClient';
-import { booleanInput, optionalArrayInput, optionalInput, run } from "../src";
+import { booleanInput, optionalArrayInput, optionalInput, run } from '../src';
 import { ActionInputs } from '../src/constants';
 
 describe('GitHub Action tests', () => {
@@ -66,6 +66,50 @@ describe('GitHub Action tests', () => {
  expect(optionalInput(ActionInputs.ApplicationId)).toEqual('BAZ');
  });
 
+ it('humanizes 403 errors', () => {
+ expect(() => MablApiClient.throwHumanizedError({
+ status: 403,
+ statusText: 'This is an error',
+ config: {},
+ headers: {},
+ data: 10,
+ request: {}
+ })).toThrow("Forbidden API error, are you sure you used a \"CI/CD Integration\" type API key? Ensure this key is for the same workspace you're testing.");
+ });
+
+ it('humanizes 401 errors', () => {
+ expect(() => MablApiClient.throwHumanizedError({
+ status: 401,
+ statusText: 'This is an error',
+ config: {},
+ headers: {},
+ data: 10,
+ request: {}
+ })).toThrow('Unauthorized API error, are you sure you passed the correct API key? Is the key "enabled"?');
+ });
+
+ it('humanizes 404 errors', () => {
+ expect(() => MablApiClient.throwHumanizedError({
+ status: 404,
+ statusText: 'This is an error',
+ config: {},
+ headers: {},
+ data: 10,
+ request: {}
+ })).toThrow('Not Found API error, please ensure any environment or application IDs in your Action config are correct.');
+ });
+
+ it('humanizes non-specific errors', () => {
+ expect(() => MablApiClient.throwHumanizedError({
+ status: 500,
+ statusText: 'This is an error',
+ config: {},
+ headers: {},
+ data: 10,
+ request: {}
+ })).toThrow('[500 - This is an error]');
+ });
+
  it('builds the request correctly with all options', () => {
  const expected = {
  environment_id: 'env',