@skyramp/skyramp 1.0.0-sha.b2dfe11 → 1.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Skyramp 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,24 +1,17 @@
-# Skyramp
-Skyramp is an npm module that provides utility functions for leveraging [skyramp CLI](https://skyramp.dev/docs/commands/skyramp/) commands.
+# skyramp
+
+`skyramp` is an npm module that provides functionalities to generate and execute a variety of functional tests (including smoke, contract, and integration tests). It also offers features for asserting scenarios in various test environments. 
+
+For more information about Skyramp, please visit [our website](https://skyramp.dev).
 
 ## Installation
-To install Skyramp, simply run the following command in your terminal:
-```
-npm install skyramp
-```
+To install Skyramp, please refer to the [installation instructions](https://skyramp.dev/docs/quickstart/install) to set up the Skyramp CLI as well as the required dependencies.
 
 ## Usage
-Once you've installed Skyramp, you can import it into your project like this:
+To use `skyramp` please refer to the guide to [generate your first test](https:skyramp.dev/docs/quickstart/first-test-general). Once you generate your first integration test in TypeScript using the Skyramp CLI, you can execute the test with the following command:
 
+```bash
+npx playwright test products_integration_test.spec.ts --reporter=list
 ```
-const skyramp = require('skyramp');
-```
 
-Skyramp currently exports the following six functions:
-- `runConfigApplyLocal`: create a new local test cluster
-- `runAddKubeconfig`: specify kubeconfig for a pre-provisioned workload cluster
-- `runConfigRemoveLocal`: remove a local test cluster
-- `runConfigRemove`: remove a test cluster
-- `runMockerCreate`: generate Mocker configurations
-- `runMockerDeploy`: update Mocker configurations and source schema files
-- `runTesterStart`: starts a skyramp test specified in the test description file
+

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@skyramp/skyramp",
-  "version": "1.0.0-sha.b2dfe11",
+  "version": "1.2.2",
   "description": "module for leveraging skyramp cli functionality",
   "scripts": {
+    "lint": "eslint 'src/**/*.js' 'src/**/*.ts' --fix",
     "pack": "npm pack",
-    "publish-npm": "npm publish --access private --ignore-scripts --@skyramp:skyramp='https://registry.npmjs.org'"
+    "reference-docs": "documentation build src/**/*.js src/classes/**/*.js -f md -o reference.md",
+    "postinstall": "node scripts/download-binary.js",
+    "clean": "rimraf node_modules && rimraf package-lock.json && rimraf skyramp && rimraf lib/*"
   },
   "files": [
-    "lib/**",
+    "scripts/*.js",
     "src/*.js",
     "src/*.ts",
     "src/classes/*.js",
@@ -15,10 +18,16 @@
   ],
   "main": "src/index.js",
   "author": "",
-  "license": "ISC",
+  "license": "MIT",
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.812.0",
     "fs": "^0.0.1-security",
     "js-yaml": "^4.1.0",
-    "koffi": "^2.3.20"
+    "koffi": "2.5.12"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^6.14.0",
+    "@typescript-eslint/parser": "^6.14.0",
+    "eslint": "^8.55.0"
   }
 }

package/scripts/download-binary.js

@@ -0,0 +1,189 @@
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { S3Client, GetObjectCommand } = require("@aws-sdk/client-s3");
+
+function log(level, message) {
+    const timestamp = new Date().toISOString();
+    console.log(`[${timestamp}] [${level.toUpperCase()}] ${message}`);
+}
+
+let S3_PRIVATE = process.env.S3_PRIVATE || false;  // Set to true if libraries are in a private S3 bucket
+const AWS_REGION = process.env.AWS_REGION || 'us-west-2';  // Set your AWS region
+const SKIP_DOWNLOAD = process.env.SKIP_DOWNLOAD || false;  // Set to true to skip the download process
+const PUBLIC_BUCKET_NAME = process.env.INT_LIBRARY_BUCKET || 'skyramp-public';  // Set to your S3 public bucket name
+const PUBLIC_LIBRARY_PATH = process.env.INT_LIBRARY_PATH || `release/v${require('../package.json').version}/lib`;  // Set to your S3 public library root path
+const PRIVATE_BUCKET_NAME = process.env.INT_LIBRARY_BUCKET || undefined;  // Set to your S3 private bucket name
+const PRIVATE_LIBRARY_PATH = process.env.INT_LIBRARY_PATH || '';  // Set to your S3 private library root path
+
+if (SKIP_DOWNLOAD) {
+    log('info', "Skipping download as requested by SKIP_DOWNLOAD=true.");
+    process.exit(0);
+}
+
+if (process.env.CI) {
+    log('info', "Running in CI environment. Defaulting to private S3 download.");
+    S3_PRIVATE = true;
+}
+
+const archMap = {
+    x64: 'amd64',
+    ia32: '386',
+    arm: 'arm',
+    arm64: 'arm64',
+};
+
+const platformMap = {
+    win32: 'windows',
+    darwin: 'darwin',
+    linux: 'linux',
+};
+
+const extMap = {
+    windows: 'dll',
+    darwin: 'dylib',
+    linux: 'so',
+};
+
+const rawPlatform = process.platform;
+const rawArch = process.arch;
+const platform = platformMap[rawPlatform];
+const arch = archMap[rawArch];
+const ext = extMap[platform];
+
+if (!platform || !arch || !ext) {
+    log('error', `Unsupported platform or architecture: ${rawPlatform} / ${rawArch}`);
+    process.exit(1);
+}
+
+const prefix = 'skyramp';
+const binaryFilename = `${prefix}-${platform}-${arch}.${ext}`;
+const headerFilename = `${prefix}-${platform}-${arch}.h`;
+
+const baseUrl = `https://${PUBLIC_BUCKET_NAME}.s3.${AWS_REGION}.amazonaws.com/${PUBLIC_LIBRARY_PATH}/`;
+const localDir = path.join(__dirname, '..', 'lib');
+
+const files = [
+    { name: binaryFilename, dest: path.join(localDir, binaryFilename) },
+    { name: headerFilename, dest: path.join(localDir, headerFilename) },
+];
+
+async function calculateMD5(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = crypto.createHash('md5');
+        const stream = fs.createReadStream(filePath);
+        stream.on('data', data => hash.update(data));
+        stream.on('end', () => resolve(hash.digest('hex')));
+        stream.on('error', (err) => {
+            log('error', `Failed to calculate MD5 for ${filePath}: ${err.message}`);
+            reject(err);
+        });
+    });
+}
+
+async function getETag(url) {
+    return new Promise((resolve, reject) => {
+        https.get(url, { method: 'HEAD' }, res => {
+            if (res.statusCode !== 200) {
+                reject(new Error(`HTTP ${res.statusCode}: ${url}`));
+                return;
+            }
+            resolve(res.headers['etag']?.replace(/"/g, '')); // Remove quotes from ETag
+        }).on('error', (err) => {
+            log('error', `Error during HEAD request to ${url}: ${err.message}`);
+            reject(err);
+        });
+    });
+}
+
+async function download(url, dest, options = {}) {
+    await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+
+    const { session, bucket, s3Key } = options;
+
+    return new Promise((resolve, reject) => {
+        if (session && bucket && s3Key) {
+            // Private S3 download using AWS SDK
+            const command = new GetObjectCommand({ Bucket: bucket, Key: s3Key });
+            session.send(command).then(response => {
+                const stream = response.Body;
+                const file = fs.createWriteStream(dest);
+                stream.pipe(file);
+                stream.on('error', (err) => {
+                    log('error', `Error streaming file from S3: ${err.message}`);
+                    reject(err);
+                });
+                file.on('finish', () => {
+                    log('info', `Successfully downloaded ${s3Key} to ${dest}`);
+                    file.close(resolve);
+                });
+            }).catch(err => {
+                log('error', `Failed to download ${s3Key} from S3: ${err.message}`);
+                reject(err);
+            });
+        } else {
+            // Public URL download using https
+            https.get(url, res => {
+                if (res.statusCode !== 200) {
+                    const error = new Error(`HTTP ${res.statusCode}: ${url}`);
+                    log('error', `Failed to download ${url}: ${error.message}`);
+                    reject(error);
+                    return;
+                }
+                const file = fs.createWriteStream(dest);
+                res.pipe(file);
+                file.on('finish', () => {
+                    log('info', `Successfully downloaded ${url} to ${dest}`);
+                    file.close(resolve);
+                });
+            }).on('error', (err) => {
+                log('error', `Error during download from ${url}: ${err.message}`);
+                reject(err);
+            });
+        }
+    });
+}
+
+(async () => {
+    for (const file of files) {
+        let options = {};
+        let url = baseUrl + file.name;
+        const localFile = file.dest;
+        log('info', `Processing ${file.name}...`);
+
+        try {
+            if (S3_PRIVATE) {
+                log("Pulling libraries from Private S3.");
+                const s3 = new S3Client({region: AWS_REGION});
+
+                url = null; // No URL needed for S3 private download client
+                options = {
+                    session: s3,
+                    bucket: PRIVATE_BUCKET_NAME,
+                    s3Key: `${PRIVATE_LIBRARY_PATH}/${file.name}`
+                };
+            } else if (fs.existsSync(localFile)) {
+                log('info', `Checking ${file.name} for changes...`);
+                const remoteETag = await getETag(url);
+                const localHash = await calculateMD5(localFile);
+                log('debug', `Remote ETag: ${remoteETag}, Local Hash: ${localHash}`);
+
+                if (remoteETag === localHash) {
+                    log('info', `✅ ${file.name} is up-to-date.`);
+                    continue;
+                } else {
+                    log('info', `🔄 ${file.name} differs, downloading...`);
+                }
+            } else {
+                log('info', `⬇️ ${file.name} not found locally, downloading...`);
+            }
+
+            await download(url, file.dest, options);
+            log('info', `✅ Saved ${file.name} to ${file.dest}`);
+        } catch (e) {
+            log('error', `❌ Failed to process ${file.name}: ${e.message}`);
+            process.exit(1);
+        }
+    }
+})();

package/src/classes/Asserts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @typedef {Object} AssertOptions
+ * @property {string} assertValue - The value to be asserted.
+ * @property {string} expectedValue - The expected value for the assertion.
+ * @property {string} assertStepName - The name of the step.
+ * @property {string} description - The description of the assertion.
+ */
+interface AssertOptions {
+    assertValue: string;
+    expectedValue: string;
+    assertStepName: string;
+    description: string;
+}
+export declare class Asserts {
+    constructor(options: AssertOptions);
+}

package/src/classes/Asserts.js

@@ -0,0 +1,41 @@
+/**
+ * The `Assert` class represents an assertion to be used in a test step.
+ * @class
+ */
+class Assert {
+  /**
+   * Initialize a new instance of an Assert.
+   * @constructor
+   * @param {Object} option - The options for initializing the Assert object.
+   * @param {*} option.assertValue - The value to be asserted.
+   * @param {*} option.assertExpectedValue - The expected value for the assertion.
+   * @param {string} option.stepName - The name of the step.
+   * @param {string} option.description - The description of the assertion.
+   */
+  constructor(option) {
+    this.assertValue = option.assertValue;
+    this.expectedValue = option.assertExpectedValue;
+    this.name = option.stepName;
+    this.description = option.description;
+  }
+
+  /**
+   * Convert the assertion to a JSON object.
+   * @returns {Object} The JSON representation of the assertion.
+   */
+  toJson() {
+    return {
+      asserts: `${this.assertValue} == ${this.expectedValue}`,
+    };
+  }
+  
+  /**
+   * Convert the assertion to a string representation.
+   * @returns {string} The string representation of the assertion.
+   */
+  toAssert() {
+    return `${this.assertValue} == ${this.expectedValue}`
+  }
+}
+
+module.exports = Assert;

package/src/classes/AsyncScenario.d.ts

@@ -0,0 +1,133 @@
+import { RequestV2 } from "./RequestV2";
+
+export interface AsyncRequestOptions {
+  name?: string;
+  url?: string;
+  path?: string;
+  method?: string;
+  body?: string;
+  headers?: Record<string, string>;
+  pathParams?: Record<string, string>;
+  queryParams?: Record<string, string | number | boolean>;
+  formParams?: Record<string, string | number | boolean>;
+  multipartParams?: Record<string, string | number | boolean>;
+  dataOverride?: Record<string, string | number | boolean>;
+  description?: string;
+  expectedCode?: string;
+  if_?: string;
+  until?: string;
+  maxRetries?: number;
+  retryInterval?: number;
+}
+
+export class AsyncRequest {
+  scenario: AsyncScenario;
+  request: RequestV2;
+  stepIndex: number;
+
+  constructor(scenario: AsyncScenario, request: RequestV2, stepIndex: number);
+
+  /**
+   * Returns request's response value construct for asynchronous backend
+   * @param path The path to the value
+   */
+  getAsyncRequestValue(path: string | null): string;
+
+  /**
+   * Returns request's status check construct for asynchronous backend
+   * @param code The expected status code
+   */
+  requestStatusCheck(code: string | number): string;
+
+  /**
+   * Adds an assert to the request
+   * @param jsonPath The JSON path to the value
+   * @param expectedValue The expected value
+   */
+  assertEqual(jsonPath: string, expectedValue: string | number | boolean): void;
+
+  /**
+   * Adds a not equal assert to the request
+   * @param jsonPath The JSON path to the value
+   * @param value The value to compare against
+   */
+  assertNotEqual(jsonPath: string, value: string | number | boolean): void;
+}
+
+export interface AsyncScenarioOptions {
+  name: string;
+  ignoreFailure?: boolean;
+}
+
+export class AsyncScenario {
+  name: string;
+  steps: AsyncRequest[];
+  vars: Record<string, string | number | boolean>;
+  until: string;
+  maxRetries: number;
+  retryInterval: number;
+  ignoreFailure: boolean;
+
+  /**
+   * Creates a new AsyncScenario
+   * @param options The scenario options
+   */
+  constructor(options: AsyncScenarioOptions);
+
+  /**
+   * Adds an asynchronous request to this scenario
+   * @param options The request options
+   */
+  addAsyncRequest(options?: AsyncRequestOptions): AsyncRequest;
+
+  /**
+   * Adds an asynchronous nested scenario to this scenario
+   * @param nestedScenario The nested scenario to add
+   * @param until The condition to stop retrying
+   * @param maxRetries The maximum number of retries
+   * @param retryInterval The interval between retries
+   */
+  addAsyncScenario(
+    nestedScenario: AsyncScenario,
+    until?: string,
+    maxRetries?: number,
+    retryInterval?: number
+  ): void;
+
+  /**
+   * Sets a scenario level variable
+   * @param varName The name of the variable
+   * @param value The value of the variable
+   */
+  setAsyncVar(varName: string, value: string | number | boolean): void;
+
+  /**
+   * Returns scenario's variable construct for asynchronous backend
+   * @param varName The name of the variable
+   */
+  getAsyncVar(varName: string): string;
+
+  /**
+   * Returns scenario's response value construct for asynchronous backend
+   * @param varName The name of the variable
+   */
+  getAsyncScenarioValue(varName: string): string;
+
+  /**
+   * Sets a scenario level variable for export
+   * @param varName The name of the variable
+   * @param value The value of the variable
+   */
+  exportAsyncVar(varName: string, value: string | number | boolean): void;
+
+  /**
+   * Adds an assert to the scenario
+   * @param value The value to assert
+   */
+  addAssert(value: string): void;
+
+  /**
+   * Converts this scenario to JSON
+   */
+  toJson(): Record<string, string | number | boolean | object | null>;
+}