Registry /
testing / mutation-server-protocol
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MutationServer
✓ import type { MutationServer } from 'mutation-server-protocol';
✗ import { MutationServer } from 'mutation-server-protocol';
This package primarily ships TypeScript types and interfaces; use `import type` for clarity and better tree-shaking.
DiscoverParams, MutationTestParams
✓ import type { DiscoverParams, MutationTestParams } from 'mutation-server-protocol';
✗ const { DiscoverParams } = require('mutation-server-protocol');
Types are not directly consumable as runtime objects. CommonJS `require` is not recommended for type imports and this package targets Node.js >=18, favoring ESM.
FileRange
✓ import type { FileRange } from 'mutation-server-protocol';
✗ import * as protocol from 'mutation-server-protocol';
While `* as protocol` might work for types, it's generally best practice to import specific types as needed for clarity and to avoid pulling in unnecessary definitions.
Demonstrates defining a basic Mutation Server Protocol handler using its TypeScript types and simulates client-server message exchange for `discover` and `mutationTest` methods.
import type {
MutationServer,
DiscoverParams,
MutationTestParams,
MutationTestResult,
FileRange,
Mutant,
Location,
} from 'mutation-server-protocol';
// Simulate a basic JSON-RPC message handler implementing the MSP server interface
class MyMutationServer implements MutationServer {
private requestIdCounter = 0;
// MSP method: discover mutants in a given scope
async discover(params: DiscoverParams): Promise<Mutant[]> {
console.log(`[Server] Received discover request for files: ${params.files?.map(f => f.fileName).join(', ')}`);
// In a real server, this would analyze code to find potential mutants
const mutants: Mutant[] = [
{
id: 'mutant-1',
mutatorName: 'BinaryExpression',
replacement: 'false', // Example replacement
location: { start: { line: 1, column: 10 }, end: { line: 1, column: 15 } },
fileName: 'src/example.js',
status: 'Pending'
},
];
return mutants;
}
// MSP method: run mutation tests for specific mutants
async mutationTest(params: MutationTestParams): Promise<MutationTestResult> {
console.log(`[Server] Received mutationTest request for mutants: ${params.mutants?.map(m => m.id).join(', ')}`);
// In a real server, this would execute tests against mutated code
const result: MutationTestResult = {
mutantResults: {
'mutant-1': { status: 'Killed', coveredBy: ['testA'] },
},
// ... other results like files, test results
};
return result;
}
// Example of how a client might construct and send a request
async simulateClientRequest() {
const server = new MyMutationServer();
const discoverRequest = {
jsonrpc: '2.0',
id: ++this.requestIdCounter,
method: 'discover',
params: {
files: [{ fileName: 'src/example.js' } as FileRange],
// Optional other params like 'testFramework'
} as DiscoverParams,
};
console.log('\n[Client] Sending discover request:', JSON.stringify(discoverRequest, null, 2));
const discoverResponse = await server.discover(discoverRequest.params);
console.log('[Client] Received discover response:', JSON.stringify(discoverResponse, null, 2));
const mutationTestRequest = {
jsonrpc: '2.0',
id: ++this.requestIdCounter,
method: 'mutationTest',
params: {
mutants: discoverResponse.slice(0, 1), // Test the first discovered mutant
// Optional other params
} as MutationTestParams,
};
console.log('\n[Client] Sending mutationTest request:', JSON.stringify(mutationTestRequest, null, 2));
const mutationTestResponse = await server.mutationTest(mutationTestRequest.params);
console.log('[Client] Received mutationTest response:', JSON.stringify(mutationTestResponse, null, 2));
}
}
const simulator = new MyMutationServer();
simulator.simulateClientRequest();
Errors
Common errors & fixes
Content-Length header missing or invalid
The incoming JSON-RPC message is not correctly framed with the required `Content-Length` header followed by `\r\n\r\n` before the JSON payload.
fixEnsure all messages sent over `stdio` or `socket` transports adhere to the base protocol's framing: `Content-Length: <length>\r\n\r\n{json_payload}`. Error: listen EADDRINUSE: address already in use :::<port>
When running the server in `socket` mode, the specified `--port` is already occupied by another process.
fixChoose an available port number, or ensure no other application is using the intended port before starting the mutation server.
TypeError: Cannot read properties of undefined (reading 'fileName') for FileRange
A `FileRange` object passed to `discover` or `mutationTest` (e.g., in the `files` array) is missing the required `fileName` property, or the `files` array itself is not properly structured.
fixEnsure `FileRange` objects always include a `fileName` string. Validate that the `files` array matches the `FileRange[]` type definition.
Audit
Dependencies
No dependency data recorded yet.