split-specs-client

API Client library for Split specs.
Service could be used as orchestrator for your spec files during parallel testing across different machines/containers.

Registration

You can register your account at split-specs UI or use demo credentials - email: [email protected] and password: test.
Source code: split-specs.

Install

• yarn:

yarn add @shelex/split-specs-client

• npm:

npm install @shelex/split-specs-client

Example

import { SpecSplitClient, filesToSpecInput } from '@shelex/split-specs-client';
// const { SpecSplitClient, filesToSpecInput } = require("@shelex/split-specs-client")

const client = new SpecSplitClient({
    project: 'test',
    email: '[email protected]',
    password: 'test'
});

/**
 * specs are located in folder "specs"
 * files: "spec1.js", "spec2.js", "spec3.js", "spec5.js", "spec4.js"
 * take all js files in "specs" folder excepting "spec5.js"
 */
const specs = filesToSpecInput(['**/specs/*.js'], ['**/specs/spec5.js']);

// create new session (project will be created automatically, or link existing)
client.addSession(specs);
// or in case you have files as strings just pass them as array of objects:
// const specs = [{ filePath: 'spec1.js' }, { filePath: 'spec2.js' }, { filePath: 'spec3.js' }, { filePath: 'spec4.js' }]
// client.addSession(specs)

// query next spec for any of your runners
const next = client.nextSpec({ machineId: 'runner1' }); // start spec1, return spec1
const next = client.nextSpec({ machineId: 'runner2' }); // start spec2, return spec2
const next = client.nextSpec({ machineId: 'runner2' }); // finish spec2, start spec3, return spec3
const next = client.nextSpec({ machineId: 'runner1' }); // finish spec1, start spec4, return spec4
const next = client.nextSpec({ machineId: 'runner2' }); // finish spec3, return null
const next = client.nextSpec({ machineId: 'runner1' }); // finish spec4, return null

// get current state of project "test"
const project = client.project();
console.log(project);

CLI

Library also provides CLI interface

Create session

split-specs-cli create-session --project test --token $split_spec_token --include-specs '**/cypress/integration/**'

Use split-specs-cli create-session --help to check arguments available
Created session will be stored as json file or just console.log session id to catch from bash:

SPLIT_SPEC_SESSION_ID=$(split-spec-cli create-session (args for split spec client) | tail -1)

Run Cypress

split-specs-cli run --project test -token $split_spec_token --sessionId $split_spec_sessionId --machineId $split_spec_machineId ...cypress run args

with some cypress args: split-specs-cli run --project sample -token sample --sessionId sample --machineId sample --env allure=true --browser chrome

with plugin to manipulate configuration function(config, specName):config split-specs-cli run --project sample -token sample --sessionId sample --machineId sample --config-plugin-path './updateConfig.js' --env allure=true --browser chrome

You can have multiple machines\actions\containers with such runner (with different machineId) and each runner will ask service for next spec file to execute.

API

const client = new SpecSplitClient({options})

Constructor. options may contain inital values for:

• url, default: "https://split-specs.shelex.dev/api"; url for split-specs service queries
• project, may be also passed as second argument to addSession
• token, in case you have obtained token in web version or other way, it could be passed so login step will be skipped
• email and password, in case token option is empty, constructor will call login method with this credentials to obtain token

client.addSession(specs: SpecInput[], projectName?: string): {sessionId: string}

Create a new session for project. Project will be reused, or created in case it still not exist.
Returns object with property sessionID that could be used for retrieving spec.

client.nextSpec({ machineId?: string, sessionId?: string, previousStatus?: string }): string;

Get next spec for machineId + sessionId, returns spec filePath.
Ends previous spec for this machineId + sessionId in case it exists.

project(id?: string): Project

Get project details with latest 15 sessions

Motivation

Idea is to have separate service for orchestrating specs during test runs. Classical solution is to manually split spec files in groups, however it may be not so efficient in terms of run duration. Strategy used in this service is basically to run new specs and then from longest to shortest compared to previous session.
Potentially, some UI could be built on top of Split specs service to track test sessions across the time.

License

Copyright © 2022 Oleksandr Shevtsov [email protected]

This work is free. You can redistribute it and/or modify it under the terms of the MIT License. See LICENSE for full details.