Tesults API Library

Common errors

• Error: Cannot find module 'tesults'

  cause The 'tesults' package is not installed or not resolvable in the current Node.js environment or project.
  fix Run `npm install tesults` in your project's root directory to install the package.

• TypeError: tesults.results is not a function

  cause The `tesults` object was not correctly imported or initialized, or a variable named `tesults` was inadvertently overwritten before calling the `results` method.
  fix Ensure that `const tesults = require('tesults');` (for CommonJS) or `import tesults from 'tesults';` (for ESM with appropriate configuration) is at the top of your file and that `tesults` has not been reassigned.

• SyntaxError: Cannot use import statement outside a module (or similar ERR_REQUIRE_ESM)

  cause You are attempting to use an `import` statement for `tesults` in a CommonJS module file (e.g., a `.js` file without `"type": "module"` in `package.json`), or attempting to `require()` in an ES Module context.
  fix If your file is CommonJS, use `const tesults = require('tesults');`. If your project is ES Modules (`"type": "module"` in `package.json` or `.mjs` files), use `import tesults from 'tesults';` or `const tesults = await import('tesults');` and ensure your Node.js version supports ESM (v12.20.0+ is recommended).

Warnings

• gotcha The `tesults` npm package version 1.2.1 was published in 2017. While it functions, it uses older Node.js patterns (e.g., CommonJS modules, callback-based asynchronous operations) that may not align with modern Node.js development, which favors ES Modules and Promises/async-await. This could lead to integration complexities in newer projects or environments.
  Fix: Consider wrapping the callback-based API in a Promise for async/await usage or using dynamic `import()` for ESM contexts. For new projects, evaluate if newer alternatives exist or if the core Tesults service offers alternative SDKs.
• gotcha The primary `tesults.results` method uses a Node.js-style callback pattern (`function (err, response)`). Developers expecting Promise-based or async/await syntax in modern JavaScript will need to wrap this in a Promise or adapt their code accordingly, as direct `await tesults.results(...)` will not work as intended.
  Fix: Wrap the `tesults.results` call in a Promise for modern async/await usage: ```javascript function uploadResults(data) { return new Promise((resolve, reject) => { tesults.results(data, (err, response) => { if (err) return reject(err); resolve(response); }); }); } // Usage: try { const response = await uploadResults(data); // handle response } catch (error) { // handle error } ```
• gotcha The `target` value, which is your Tesults API token, is crucial for authentication. Hardcoding this token directly into your application's source code is a security risk. If exposed, it could allow unauthorized access to your Tesults project.
  Fix: Always use environment variables (e.g., `process.env.TESULTS_TOKEN`), a secrets management service, or a secure configuration system to provide your Tesults API token. Avoid committing tokens to version control.

Install

• npm install tesults npm
• yarn add tesults yarn
• pnpm add tesults pnpm

Imports

• tesults

  const tesults = require('tesults');

  This package (v1.2.1) is primarily designed for CommonJS environments.
• tesults
  wrong:

  import { tesults } from 'tesults';

  correct:

  import tesults from 'tesults';

  When importing a CommonJS module into an ES Module, the `module.exports` object is typically provided as the default export. Named imports generally do not work without specific `exports` map configuration in the package's `package.json`, which this older version lacks.
• tesults

  const tesults = await import('tesults');

  For dynamic asynchronous loading of a CommonJS module (like this one) within an ES Module context, `import()` can be used. The `module.exports` object will be available as the default export of the imported module.

Quickstart

This quickstart demonstrates installing the Tesults package, configuring it with a token (preferably from environment variables), and uploading a sample set of test results using the callback-based API. It includes examples of passing and failing tests with descriptions and additional parameters.

import * as tesults from 'tesults';

const TESULTS_TOKEN = process.env.TESULTS_TOKEN ?? 'your_tesults_token'; // Replace or use environment variable

const data = {
    target: TESULTS_TOKEN,
    results: {
        cases: [
            {
                name: 'User Login Test',
                desc: 'Verify a user can log in with valid credentials.',
                suite: 'Authentication Suite',
                result: 'pass'
            },
            {
                name: 'Invalid Password Test',
                desc: 'Attempt login with an incorrect password and check error message.',
                suite: 'Authentication Suite',
                result: 'fail',
                reason: 'Expected error message "Invalid credentials", but got "User not found".'
            },
            {
                name: 'Data Persistence Check',
                desc: 'Ensure saved user data remains after logout and re-login.',
                suite: 'Data Integrity',
                result: 'pass',
                params: {
                    userType: 'admin',
                    region: 'US-East'
                },
                files: [] // Optionally attach log files or screenshots
            }
        ]
    }
};

tesults.results(data, function (err, response) {
    if (err) {
        console.error('Tesults library error:', err);
        return;
    }

    if (response.success) {
        console.log('Test results successfully uploaded to Tesults.');
    } else {
        console.error('Failed to upload results:', response.message);
        if (response.warnings && response.warnings.length > 0) {
            console.warn('Warnings:', response.warnings);
        }
        if (response.errors && response.errors.length > 0) {
            console.error('Errors:', response.errors);
        }
    }
});