@shelex/split-specs-client NPM

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: test@test.com 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: 'test@test.com',
    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.