SmartUI Storybook package

Author: Pinank Solanki

.gitignore

@@ -0,0 +1 @@
+node_modules

README.md

@@ -0,0 +1,61 @@
+# LambdaTest SmartUI CLI
+The @lambdatest/smartui package is LambdaTest's command-line interface (CLI) aimed to help you run your SmartUI tests on LambdaTest platform.
+
+
+# Installation
+
+### Prerequisites
+1. Node version >=14.15.0 required
+  ```
+  node --version
+  ```
+
+2. Storybook version >=6.4 required. Also, add the following to your `.storybook/main.js`. You can read more about this here [Storybook Feature flags](https://storybook.js.org/docs/react/configure/overview#feature-flags)
+  ```js
+  module.exports = {
+    features: {
+      buildStoriesJson: true
+    }
+  }
+  ```
+
+### Install package using npm
+```bash
+npm install -g [email protected]:Lambdatest/smartui-storybook.git
+```
+
+# Usage
+
+## Step 1: Set SmartUI Project Token in environment variables
+
+  <b>For Linux/macOS:</b>
+ 
+  ```
+  export PROJECT_TOKEN="your-project-token"
+  ```
+
+   <b>For Windows:</b>
+
+  ```
+  set PROJECT_TOKEN="your-project-token"
+  ```
+
+## Step 2: Create config file
+```bash
+smartui config create .smartui.json
+```
+
+## Step 3: Execute tests
+Run the following command to run tests on your Storybook stories. Provide your storybook url, build name and config file (Default config used if no config file provided)
+
+```bash
+smartui storybook http://localhost:6006 --buildname Build1 --config .smartui.json
+```
+
+# About LambdaTest
+
+[LambdaTest](https://www.lambdatest.com/) is a cloud based selenium grid infrastructure that can help you run automated cross browser compatibility tests on 2000+ different browser and operating system environments. LambdaTest supports all programming languages and frameworks that are supported with Selenium, and have easy integrations with all popular CI/CD platforms. It's a perfect solution to bring your [selenium automation testing](https://www.lambdatest.com/selenium-automation) to cloud based infrastructure that not only helps you increase your test coverage over multiple desktop and mobile browsers, but also allows you to cut down your test execution time by running tests on parallel.
+
+# License
+
+Licensed under the [MIT license](./LICENSE).

commands/config.js

@@ -0,0 +1,26 @@
+const path = require('path');
+const fs = require('fs');
+const { defaultSmartUIConfig } = require('./utils/config')
+
+function createConfig(filepath) {
+    // default filepath
+    filepath = filepath || '.smartui.json';
+    let filetype = path.extname(filepath);
+    if (filetype != '.json') {
+        console.log(`[smartui] Error: Config file must have .json extension`);
+        process.exit(1);
+    }
+
+    // verify the file does not already exist
+    if (fs.existsSync(filepath)) {
+        console.log(`[smartui] Error: LambdaTest SmartUI config already exists: ${filepath}`);
+        process.exit(1);
+    }
+
+    // write stringified default config options to the filepath
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    fs.writeFileSync(filepath, JSON.stringify(defaultSmartUIConfig, null, 2) + '\n');
+    console.log(`[smartui] Created LambdaTest SmartUI config: ${filepath}`);
+};
+
+module.exports = { createConfig };

commands/storybook.js

@@ -0,0 +1,76 @@
+const { default: axios } = require('axios')
+const fs = require('fs');
+const { sendDoM } = require('./utils/dom')
+const { validateStorybookUrl } = require('./utils/validate')
+const { defaultSmartUIConfig } = require('./utils/config')
+const { skipStory } = require('./utils/story')
+
+async function storybook(url, options) {
+    // Check connection with storybook url
+    await validateStorybookUrl(url);
+
+    // TODO: modularize this and separate check for file exists
+    let storybookConfig = defaultSmartUIConfig.storybook; 
+    if (options.config) {
+        try {
+            storybookConfig = JSON.parse(fs.readFileSync(options.config)).storybook;
+        } catch (error) {
+            console.log('[smartui] Error: ', error.message);
+            process.exit(1);
+        }
+
+        storybookConfig.browsers.forEach(element => {
+            if (!(['chrome', 'safari', 'firefox'].includes(element))) {
+                console.log('[smartui] Error: Invalid value for browser. Accepted browsers are chrome, safari and firefox');
+                process.exit(0);
+            }
+        });
+        // TODO: Sanity check resolutions
+    }
+
+    // Convert browsers and resolutions arrays to string
+    let resolutions = [];
+    storybookConfig.resolutions.forEach(element => {
+        resolutions.push(element.join('x'));
+    });
+    storybookConfig.resolutions = (!resolutions.length) ? 'all' : resolutions.toString();
+    storybookConfig.browsers = (!storybookConfig.browsers.length) ? 'all' : storybookConfig.browsers.toString();
+
+    // Get stories object from stories.json and add url corresponding to every story ID 
+    axios.get(new URL('stories.json', url).href)
+        .then(function (response) {
+            let stories = {}
+            for (const [storyId, storyInfo] of Object.entries(response.data.stories)) {
+                if (!skipStory(storyInfo.name, storybookConfig)) {
+                    stories[storyId] = {
+                        name: storyInfo.name,
+                        kind: storyInfo.kind,
+                        url: new URL('/iframe.html?id=' + storyId + '&viewMode=story', url).href
+                    }
+                }
+            }
+            
+            if (Object.keys(stories).length === 0) {
+                console.log('[smartui] Error: No stories found');
+                process.exit(0);
+            } else {
+                for (const [storyId, storyInfo] of Object.entries(stories)) {
+                    console.log('[smartui] Story found: ' + storyInfo.name);
+                }
+            }
+            // Capture DoM of every story and send it to renderer API
+            sendDoM(stories, storybookConfig, options);
+        })
+        .catch(function (error) {
+            if (error.response) {
+                console.log('[smartui] Error: Cannot fetch Storybook stories');
+            } else if (error.request) {
+                console.log('[smartui] Error: Cannot fetch Storybook stories');
+            } else {
+                console.log('[smartui] Error: Cannot fetch Storybook stories');
+            }
+            process.exit(0);
+        });
+};
+
+module.exports = { storybook };

commands/utils/config.js

@@ -0,0 +1,16 @@
+const defaultSmartUIConfig = {
+    storybook: {
+        browsers: [
+            'chrome',
+            'firefox',
+            'safari'
+        ],
+        resolutions: [
+            [1920, 1080]
+        ],
+        include: [],
+        exlcude: []
+    }
+};
+
+module.exports = { defaultSmartUIConfig }

commands/utils/constants.js

@@ -0,0 +1,13 @@
+var constants = {}
+
+constants.env = 'prod';
+constants.stage = {
+    AUTH_URL: "https://stage-api.lambdatestinternal.com/storybook/auth",
+    RENDER_API_URL: "https://stage-api.lambdatestinternal.com/storybook/render"
+};
+constants.prod = {
+    AUTH_URL: "https://api.lambdatest.com/storybook/auth",
+    RENDER_API_URL: "https://api.lambdatest.com/storybook/render"
+};
+
+module.exports = { constants };

commands/utils/dom.js

@@ -0,0 +1,66 @@
+const axios = require('axios');
+const fs = require('fs');
+const formData = require('form-data');
+var { constants } = require('.//constants');
+
+async function sendDoM(stories, storybookConfig, options) {
+    const createBrowser = require('browserless')
+    const browser = createBrowser()
+
+    if (!fs.existsSync('doms')){
+        fs.mkdir('doms', (err) => {
+            if (err) {
+                return console.error(err);
+            }
+        });
+    }
+    for (const [storyId, storyInfo] of Object.entries(stories)) {
+        const browserless = await browser.createContext()
+        const html = await browserless.html(storyInfo.url)
+
+        try {
+            fs.writeFileSync('doms/' + storyId + '.html', html);
+        } catch (err) {
+            console.error(err);
+        }
+
+        await browserless.destroyContext()
+    }
+    await browser.close()
+
+    // Send html files to the renderer API
+    const form = new formData();
+    for (const [storyId, storyInfo] of Object.entries(stories)) {
+        const file = fs.readFileSync('doms/' + storyId + '.html');
+        form.append('html', file, storyInfo.kind + ': ' + storyInfo.name + '.html');
+    }
+    form.append('resolution', storybookConfig.resolutions);
+    form.append('browser', storybookConfig.browsers);
+    form.append('projectToken', process.env.PROJECT_TOKEN);
+    form.append('buildName', options.buildname);
+    axios.post(constants[constants.env].RENDER_API_URL, form, {
+        headers: {
+            ...form.getHeaders()
+        }
+        })
+        .then(function (response) {
+            console.log('[smartui] Build successful')
+        })
+        .catch(function (error) {
+            fs.rm('doms', {recursive: true}, (err) => {
+                if (err) {
+                    return console.error(err);
+                }
+            });
+            console.log('[smartui] Build failed: Error: ', error.message);
+            process.exit(0);
+        });
+
+    fs.rm('doms', {recursive: true}, (err) => {
+        if (err) {
+            return console.error(err);
+        }
+    });
+};
+
+module.exports = { sendDoM };

commands/utils/story.js

@@ -0,0 +1,20 @@
+// Returns true or false if the story should be skipped based on include and exclude config
+function skipStory(name, config) {
+    let matches = regexp => {
+      if (typeof regexp === 'string') {
+        let [, parsed, flags] = /^\/(.+)\/(\w+)?$/.exec(regexp) || [];
+        regexp = new RegExp(parsed ?? regexp, flags);
+      }
+  
+      return regexp?.test?.(name);
+    };
+  
+    let include = [].concat(config?.include).filter(Boolean);
+    let exclude = [].concat(config?.exclude).filter(Boolean);
+
+    let skip = include?.length ? !include.some(matches) : false;
+    if (!skip && !exclude?.some(matches)) return false;
+    return true;
+  };
+
+  module.exports = { skipStory };

commands/utils/validate.js

@@ -0,0 +1,54 @@
+const axios = require('axios');
+var { constants } = require('./constants');
+
+function validateProjectToken() {
+    if (process.env.PROJECT_TOKEN) { 
+        return axios.get(constants[constants.env].AUTH_URL, {
+            headers: {
+                projectToken: process.env.PROJECT_TOKEN
+            }})
+            .then(function (response) {
+                console.log('[smartui] Project Token Validated');
+            })
+            .catch(function (error) {
+                if (error.response) {
+                    console.log('[smartui] ] Error: Invalid Project Token');
+                } else if (error.request) {
+                    console.log('[smartui] ] Error: Project Token could not be validated');
+                } else {
+                    console.log('[smartui] ] Error: Project Token could not be validated');
+                }
+                process.exit(0);
+            }); 
+    }
+    else { 
+        console.log('[smartui] Error: No PROJECT_TOKEN set');
+        process.exit(0);
+    }
+};
+
+function validateStorybookUrl(url) {
+    let aboutUrl;
+    try {
+        aboutUrl = new URL('?path=/settings/about', url).href;
+    } catch (error) {
+        console.log('[smartui] Error: ', error.message)
+        process.exit(0);
+    }
+    return axios.get(aboutUrl)
+        .then(function (response) {
+            console.log('[smartui] Connection to storybook established');
+        })
+        .catch(function (error) {
+            if (error.response) {
+                console.log('[smartui] Error: Connection to storybook could not be established');
+            } else if (error.request) {
+                console.log('[smartui] Error: Connection to storybook could not be established');
+            } else {
+                console.log('[smartui] Error: Connection to storybook could not be established');
+            }
+            process.exit(0);
+        });
+};
+
+module.exports = { validateProjectToken, validateStorybookUrl };

index.js

@@ -0,0 +1,34 @@
+#! /usr/bin/env node
+
+const { Command } = require('commander');
+const program = new Command();
+const { storybook } = require('./commands/storybook');
+const { validateProjectToken } = require('./commands/utils/validate');
+const { createConfig } = require('./commands/config');
+
+program
+    .name('smartui')
+    .description('CLI to help you run your SmartUI tests on LambdaTest platform')
+    .version('1.0.0');
+
+const configCommand = program.command('config')
+    .description('Manage LambdaTest SmartUI config')
+
+configCommand.command('create')
+    .description('Create LambdaTest SmartUI config file')
+    .argument('[filepath]', 'Optional config filepath')
+    .action(function(filepath) {
+        createConfig(filepath);
+    });
+
+program.command('storybook')
+    .description('Snapshot Storybook stories')
+    .argument('<url>', 'Storybook url')
+    .requiredOption('--buildname <string>', 'Build name')
+    .option('-c --config <file>', 'Config file path')
+    .action(async function(url, options) {
+        await validateProjectToken();
+        storybook(url, options);
+    });
+
+program.parse();