selenium-side-runner 3.17.0 → 4.0.0-alpha.16

package/src/capabilities.ts

@@ -0,0 +1,87 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import { JSON } from './types'
+
+export function parseString(input: string): Record<string, JSON> {
+  const capabilities = {}
+
+  matchStringPairs(input).forEach(({ key, value }) => {
+    assignStringKey(key, parseStringValue(value), capabilities)
+  })
+
+  return capabilities
+}
+
+export default {
+  parseString,
+}
+
+function matchStringPairs(input: string) {
+  const regex = /([^\s=]*)\s?=\s?(".*?"|'.*?'|\[.*\]|[^\s]*)/g
+  let result
+  const splitCapabilities = []
+  while ((result = regex.exec(input)) !== null) {
+    splitCapabilities.push({ key: result[1], value: result[2] })
+  }
+
+  return splitCapabilities
+}
+
+type KeyObject = Record<string, string | Record<string, string>>
+
+function assignStringKey(key: string, value: string, keyObject: KeyObject) {
+  keyObject = keyObject || {}
+
+  // @ts-expect-error
+  key.split('.').reduce((objectKey, currKey, index, keys) => {
+    const ref =
+      !objectKey[currKey] || typeof objectKey[currKey] !== 'object'
+        ? {}
+        : objectKey[currKey]
+    objectKey[currKey] = keys.length === index + 1 ? value : ref
+    return ref
+  }, keyObject)
+
+  return keyObject
+}
+
+function parseStringValue(value: string) {
+  // is array
+  if (/^\[.*\]$/.test(value)) {
+    const matches = value.slice(1, -2).match(/(([^,]*)*)/g) as string[]
+    return matches.filter((s) => !!s).map((s) => s.trim())
+  }
+  try {
+    let parsed = JSON.parse(value)
+    if (typeof parsed === 'string') {
+      parsed = parsed.trim()
+    }
+    return parsed
+  } catch (e) {
+    // single quote is illegal in JSON
+    return trimSingleQuote(value)
+  }
+}
+
+function trimSingleQuote(value: string) {
+  let str = value.trim()
+  if (str[0] === str[str.length - 1] && str[0] === "'") {
+    return str.slice(1, -2)
+  }
+  return str
+}

package/{dist/util.js → src/config.ts}

@@ -1,10 +1,3 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.sanitizeFileName = sanitizeFileName;
-
 // Licensed to the Software Freedom Conservancy (SFC) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
@@ -21,6 +14,14 @@ exports.sanitizeFileName = sanitizeFileName;
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.
-function sanitizeFileName(name) {
-  return name.replace(/^([^a-z0-9])|([^a-z0-9._-]*)/gi, '');
-}
+
+import fs from 'fs'
+import yaml from 'js-yaml'
+
+export function load(config: string) {
+  return yaml.load(fs.readFileSync(config, 'utf8'))
+}
+
+export default {
+  load,
+}

package/src/main.test.ts

@@ -0,0 +1,129 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import each from 'jest-each'
+import fs from 'fs'
+import glob from 'glob'
+import { createLogger, format, transports } from 'winston'
+import { Configuration, Project } from './types'
+import buildRegister from './register'
+import buildRunners from './run'
+import { SuiteShape, TestShape } from '@seleniumhq/side-model'
+
+const metadata = require('../package.json')
+
+process.title = metadata.name
+
+// Capture and show unhandled exceptions
+process.on('unhandledRejection', function handleWarning(reason) {
+  console.log('[PROCESS] Unhandled Promise Rejection')
+  console.log('- - - - - - - - - - - - - - - - - - -')
+  console.log(reason)
+  console.log('- -')
+})
+
+process.on('uncaughtException', (error) => {
+  console.error('Unhandled Error', error)
+})
+
+const configuration: Configuration = JSON.parse(
+  process.env.SE_CONFIGURATION as string
+)
+
+// Jest timeout should be really far back, otherwise it will impede people
+// When working right, we should close shop and detonate on our own much sooner
+jest.setTimeout(60 * 60 * 1000) // 60 minutes before we just cut it off
+
+const logger = createLogger({
+  level: configuration.debug ? 'debug' : 'info',
+  transports: [
+    new transports.Console({
+      format: format.combine(format.colorize(), format.simple()),
+    }),
+  ],
+})
+
+const projectTitle = 'Running project $name'
+const suiteTitle = 'Running suite $name'
+const testTitle = 'Running test $name'
+
+const projects: Project[] = [
+  ...configuration.projects.reduce((projects, project) => {
+    glob.sync(project).forEach((p) => {
+      projects.add(p)
+    })
+    return projects
+  }, new Set<string>()),
+]
+  .map((p) => {
+    const project = JSON.parse(fs.readFileSync(p, 'utf8'))
+    project.path = p
+    return project
+  })
+  .filter((p) => Boolean(p))
+
+if (!projects.length) {
+  throw new Error(
+    'No matching projects found, supplied filepaths: ' +
+      configuration.projects.join(', ')
+  )
+}
+
+const factoryParams = {
+  configuration,
+  logger: logger as unknown as Console,
+}
+const register = buildRegister(factoryParams)
+const runners = buildRunners(factoryParams)
+each(projects).describe(projectTitle, (project: Project) => {
+  const suites = project.suites.filter(
+    (suite) =>
+      suite.tests.length && new RegExp(configuration.filter).test(suite.name)
+  )
+  if (suites.length) {
+    each(suites).describe(suiteTitle, (suite: SuiteShape) => {
+      const isParallel = suite.parallel
+      const tests = suite.tests
+        .map((tID) => register.test(project, tID))
+        .filter((test) => new RegExp(configuration.filter).test(test.name))
+      const testExecutor = each(tests)
+      const testMethod = isParallel
+        ? testExecutor.test.concurrent
+        : testExecutor.test
+      testMethod(testTitle, async (test: TestShape) => {
+        await runners.test(project, test)
+      })
+    })
+  } else {
+    console.info(`
+      Project ${project.name} doesn't have any suites matching filter ${configuration.filter},
+      attempting to iterate all tests in project
+    `)
+    const tests = project.tests
+      .map((test) => register.test(project, test.id))
+      .filter((test) => new RegExp(configuration.filter).test(test.name))
+    if (!tests.length) {
+      throw new Error(
+        `No suites or tests found in project ${project.name} matching filter ${configuration.filter}, unable to test!`
+      )
+    }
+    const testExecutor = each(tests)
+    testExecutor.test(testTitle, async (test: TestShape) => {
+      await runners.test(project, test)
+    })
+  }
+})

package/src/proxy.ts

@@ -0,0 +1,89 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import { ProxyCapabilities, ProxyInputOptions, ProxyType } from './types'
+
+export default function ParseProxy(
+  type: ProxyType,
+  options?: ProxyInputOptions
+): ProxyCapabilities {
+  if (type === 'direct' || type === 'system') {
+    return {
+      proxyType: type,
+    }
+  } else if (type === 'pac') {
+    if (!options || typeof options !== 'string') {
+      throw new Error(
+        'A proxy autoconfig URL was not passed (e.g. --proxy-options="http://localhost/pac")'
+      )
+    }
+    return {
+      proxyType: type,
+      proxyAutoconfigUrl: options,
+    }
+  } else if (type === 'manual') {
+    if (!options) {
+      return {
+        proxyType: type,
+      }
+    } else if (typeof options !== 'object') {
+      throw new Error(
+        'Proxy options were not passed to manual proxy (e.g. --proxy-options="http=localhost:321 ftp=localhost:4324")'
+      )
+    } else {
+      let opts: Omit<ProxyCapabilities, 'proxyType'> = {}
+      if (options.http) opts.httpProxy = options.http as string
+      if (options.https) opts.sslProxy = options.https as string
+      if (options.ftp) opts.ftpProxy = options.ftp as string
+      if (options.bypass) opts.noProxy = options.bypass as string[]
+      return {
+        proxyType: type,
+        ...opts,
+      }
+    }
+  } else if (type === 'socks') {
+    if (!options || typeof options === 'string' || !options.socksProxy) {
+      throw new Error(
+        'Proxy options were not passed to socks proxy (e.g. --proxy-options="socksProxy=localhost:321")'
+      )
+    } else {
+      if (options.socksVersion) {
+        const ver = parseInt(options.socksVersion as string)
+        if (ver) {
+          return {
+            proxyType: 'manual',
+            socksProxy: options.socksProxy as string,
+            socksVersion: ver,
+          }
+        } else {
+          throw new Error(
+            'Proxy socks version is invalid (e.g. --proxy-options="socksProxy=localhost:321 socksVersion=5")'
+          )
+        }
+      } else {
+        return {
+          proxyType: 'manual',
+          socksProxy: options.socksProxy as string,
+        }
+      }
+    }
+  } else {
+    throw new Error(
+      'An unknown proxy type was passed, use one of: direct, system, manual, socks or pac (e.g. --proxy-type="direct")'
+    )
+  }
+}

package/src/register.ts

@@ -0,0 +1,79 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import { ProjectShape, SuiteShape, TestShape } from '@seleniumhq/side-model'
+import Satisfies from './versioner'
+import { Configuration, Project } from './types'
+
+export interface HoistedThings {
+  configuration: Configuration
+  logger: Console
+}
+
+export type SuiteArgs = [SuiteShape, TestShape[]]
+export type ProjectArgs = [ProjectShape, SuiteArgs[]]
+const buildRunners = ({ configuration, logger }: HoistedThings) => {
+  const registerTest = (project: Project, testID: string) =>
+    project.tests.find((t) => t.id === testID) as TestShape
+
+  const registerSuite = (project: Project, suite: SuiteShape): SuiteArgs => {
+    let tests: TestShape[] = []
+    for (let i = 0, ii = suite.tests.length; i != ii; i++) {
+      tests.push(registerTest(project, suite.tests[i]))
+    }
+    return [suite, tests]
+  }
+
+  const registerProject = (project: Project): ProjectArgs => {
+    if (!configuration.force) {
+      let warning = Satisfies(project.version, '2.0')
+      if (warning) {
+        logger.warn(warning)
+      }
+    } else {
+      logger.warn("--force is set, ignoring project's version")
+    }
+    if (!project.suites.length) {
+      throw new Error(
+        `The project ${project.name} has no test suites defined, create a suite using the IDE.`
+      )
+    }
+
+    const suites: SuiteArgs[] = []
+    for (let i = 0, ii = project.suites.length; i != ii; i++) {
+      suites.push(registerSuite(project, project.suites[i]))
+    }
+    return [project, suites]
+  }
+
+  const registerAll = (projectConfigs: Project[]): ProjectArgs[] => {
+    const projects: ProjectArgs[] = []
+    for (let i = 0, ii = projectConfigs.length; i != ii; i++) {
+      projects.push(registerProject(projectConfigs[i]))
+    }
+    return projects
+  }
+
+  return {
+    all: registerAll,
+    project: registerProject,
+    suite: registerSuite,
+    test: registerTest,
+  }
+}
+
+export default buildRunners

package/src/run.ts

@@ -0,0 +1,185 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import {
+  getCustomCommands,
+  loadPlugins,
+  Playback,
+  PlaybackEvents,
+  PlaybackEventShapes,
+  Variables,
+  WebDriverExecutor,
+} from '@seleniumhq/side-runtime'
+import { WebDriverExecutorConstructorArgs } from '@seleniumhq/side-runtime/dist/webdriver'
+import { SuiteShape, TestShape } from '@seleniumhq/side-model'
+import * as path from 'path'
+import Satisfies from './versioner'
+import { Configuration, Project } from './types'
+
+export interface HoistedThings {
+  configuration: Configuration
+  logger: Console
+}
+
+const buildRunners = ({ configuration, logger }: HoistedThings) => {
+  const runTest = async (project: Project, test: TestShape) => {
+    logger.info(`Running test ${test.name}`)
+    const shortenedProjectPath = project.path
+      .split(path.sep)
+      .slice(0, -1)
+      .join(path.sep)
+    const plugins = await loadPlugins(shortenedProjectPath, project.plugins)
+    const customCommands = getCustomCommands(plugins)
+    const driver = new WebDriverExecutor({
+      capabilities:
+        configuration.capabilities as unknown as WebDriverExecutorConstructorArgs['capabilities'],
+      customCommands,
+      hooks: {
+        onBeforePlay: async () => {
+          await Promise.all(
+            plugins.map((plugin) => {
+              const onBeforePlay = plugin.hooks.onBeforePlay
+              if (onBeforePlay) {
+                return onBeforePlay({ driver })
+              }
+            })
+          )
+        },
+      },
+      server: configuration.server,
+    })
+    await playbackUntilComplete()
+    function playbackUntilComplete() {
+      // eslint-disable-next-line no-async-promise-executor
+      return new Promise(async (resolve, reject) => {
+        const playback = new Playback({
+          baseUrl: project.url,
+          executor: driver,
+          getTestByName: (name: string) =>
+            project.tests.find((t) => t.name === name) as TestShape,
+          logger,
+          variables: new Variables(),
+        })
+        const onComplete = (failure: any) => {
+          playback.cleanup()
+          if (failure) {
+            logger.warn('Completed with failure', failure)
+            return reject(failure)
+          } else {
+            return resolve(null)
+          }
+        }
+        const EE = playback['event-emitter']
+        EE.addListener(
+          PlaybackEvents.PLAYBACK_STATE_CHANGED,
+          ({ state }: PlaybackEventShapes['PLAYBACK_STATE_CHANGED']) => {
+            logger.debug(`Playing state changed ${state}`)
+            switch (state) {
+              case 'aborted':
+              case 'errored':
+              case 'failed':
+              case 'finished':
+              case 'paused':
+              case 'stopped':
+                logger.info(
+                  `Finished test ${test.name} ${
+                    state === 'finished' ? 'Success' : 'Failure'
+                  }`
+                )
+                onComplete(state !== 'finished')
+            }
+          }
+        )
+        EE.addListener(
+          PlaybackEvents.COMMAND_STATE_CHANGED,
+          ({
+            command,
+            state,
+          }: PlaybackEventShapes['COMMAND_STATE_CHANGED']) => {
+            const cmd = command
+            const niceString = [cmd.command, cmd.target, cmd.value]
+              .filter((v) => !!v)
+              .join('|')
+            logger.debug(`${state} ${niceString}`)
+          }
+        )
+        try {
+          await playback.play(test, {
+            startingCommandIndex: 0,
+          })
+        } catch (e) {
+          console.error(e)
+          playback.cleanup()
+          return reject(e)
+        }
+      })
+    }
+  }
+
+  const runSuite = async (project: Project, suite: SuiteShape) => {
+    logger.info(`Running suite ${suite.name}`)
+    if (!suite.tests.length) {
+      throw new Error(
+        `The suite ${suite.name} has no tests, add tests to the suite using the IDE.`
+      )
+    }
+    for (let i = 0, ii = suite.tests.length; i != ii; i++) {
+      await runTest(
+        project,
+        project.tests.find((t) => t.id === suite.tests[i]) as TestShape
+      )
+    }
+    logger.info(`Finished suite ${suite.name}`)
+  }
+
+  const runProject = async (project: Project) => {
+    logger.info(`Running project ${project.name}`)
+    if (!configuration.force) {
+      let warning = Satisfies(project.version, '2.0')
+      if (warning) {
+        logger.warn(warning)
+      }
+    } else {
+      logger.warn("--force is set, ignoring project's version")
+    }
+    if (!project.suites.length) {
+      throw new Error(
+        `The project ${project.name} has no test suites defined, create a suite using the IDE.`
+      )
+    }
+
+    for (let i = 0, ii = project.suites.length; i != ii; i++) {
+      await runSuite(project, project.suites[i])
+    }
+    logger.info(`Finished project ${project.name}`)
+  }
+
+  const runAll = async (projects: Project[]) => {
+    for (let i = 0, ii = projects.length; i != ii; i++) {
+      await runProject(projects[i])
+    }
+  }
+
+  return {
+    all: runAll,
+    project: runProject,
+    suite: runSuite,
+    test: runTest,
+  }
+}
+
+export default buildRunners

package/src/types.ts

@@ -0,0 +1,82 @@
+import { ProjectShape } from '@seleniumhq/side-model'
+import { Command } from 'commander'
+
+export type JSON =
+  | null
+  | string
+  | number
+  | boolean
+  | JSON[]
+  | { [key: string]: JSON }
+
+export interface Project extends ProjectShape {
+  path: string
+}
+
+export type ProxyType =
+  | 'autodetect'
+  | 'direct'
+  | 'manual'
+  | 'pac'
+  | 'socks'
+  | 'system'
+
+export type ProxyInputOptions =
+  | string
+  | Record<string, string | string[] | number>
+
+export type ProxyCapabilities = {
+  proxyType: 'autodetect' | 'direct' | 'manual' | 'pac' | 'system'
+  proxyAutoconfigUrl?: string
+  ftpProxy?: string
+  httpProxy?: string
+  noProxy?: string[]
+  sslProxy?: string
+  socksProxy?: string
+  socksVersion?: number
+}
+
+export interface SideRunnerCLIConfig {
+  // Override the base URL that was set in the IDE
+  baseUrl: string
+  // Webdriver capabilities
+  capabilities: string
+  // Use specified YAML file for configuration. (default: .side.yml)
+  configFile: string
+  // Print debug logs
+  debug: boolean
+  // Run suites matching name
+  filter: string
+  // Forcibly run the project, regardless of project's version
+  force: boolean
+  // Maximum amount of workers that will run your tests, defaults to number of cores
+  maxWorkers: number
+  // General parameters
+  params: string
+  // Proxy options to pass, for use with manual, pac and socks proxies
+  proxyOptions?: string
+  // Type of proxy to use (one of: direct, manual, pac, socks, system)
+  proxyType?: ProxyType
+  // Webdriver remote server
+  server: string
+  // The maximimum amount of time, in milliseconds, to spend attempting to locate
+  // an element. (default: ${DEFAULT_TIMEOUT})
+  timeout: number
+}
+
+export type SideRunnerAPI = Command & SideRunnerCLIConfig
+
+export type Configuration = Required<
+  Pick<
+    SideRunnerCLIConfig,
+    'baseUrl' | 'filter' | 'maxWorkers' | 'server' | 'timeout'
+  >
+> &
+  Pick<SideRunnerCLIConfig, 'debug' | 'force' | 'proxyType'> & {
+    capabilities: Record<string, JSON>
+    params: Record<string, JSON>
+    projects: string[]
+    proxyOptions: ProxyInputOptions
+    runId: string
+    path: string
+  }