Run your tacl tests locally

Overview

tacl CLI allows you to run your tests locally on your machine using a simple command line interface. Built on top of Playwright, it supports multiple browsers and devices for robust testing. This guide will walk you through setting up and running your tests locally, detail the various CLI options, and offer some tips for integrating your tests into CI/CD pipelines.

Prerequisites

Before you begin, ensure you have the following:

1. Node.js: Install from the official website.
2. Playwright Browsers: Install browser binaries by running:

   npx playwright install
3. API Key: Create an API Key for authentication.
4. Environment Variables: Create a .env file in your project root and add:

   TACL_API_KEY=<your-api-key>

Running Tests Locally

To run your tests locally, use the tacl CLI command:

npx @tacl/runner -t <test-case-id>

This command executes the specified test case. You can also run test suites, specify execution profiles, datasets, and more by using the options detailed below.

Example Commands

• Run a Single Test Case:

  npx @tacl/runner -t 12345

• Run a Test Suite:

  npx @tacl/runner -s 67890

• Run with a Specific Execution Profile:

  npx @tacl/runner -e prof_abc123

• Run with a Dataset and Save Results to a Specific Path:

  npx @tacl/runner -d ds_001 -r ./results

• Run in Headful Mode with Action Delay and Locale Settings:

  npx @tacl/runner -t 12345 --headfull --ad 500 --lc en-US

• Specify a Custom Test Duration (e.g., 3 Minutes):

  npx @tacl/runner -t 12345 --du 180000

info

Identifiers such as <test-case-id>, <test-suite-id>, <execution-profile-id>, and <dataset-id> can be found and copied from the tacl workspace in their respective sections.

info

API Key Configuration: The CLI uses TACL_API_KEY as the default environment variable for the API key. If you manage multiple projects with different API keys, you can store your API key in a .env file and specify the desired environment variable using the -a or --apiKey option.

note

Test Execution Options: Only one of -t/--testcaseId or -s/--testSuiteId should be provided when running tests.

CLI Options Detailed

Alias	Option	Description	Default
-V	--version	Outputs the tacl CLI version	N/A
-a	--apiKey <key>	Environment variable name containing the API key	"TACL_API_KEY"
-t	--testcaseId <Testcase Id>	ID of the test case to run	N/A
-s	--testSuiteId <TestSuite Id>	ID of the test suite to run	N/A
-e	--executionProfileId <Execution Profile Id>	ID of the execution profile to use	N/A
-d	--datasetId <Dataset Id>	ID of the dataset to use for the test run	N/A
-r	--resultsPath <path>	Path to save test results	N/A
-H	--headfull	Runs the browser in headful (non-headless) mode	false
--ad	--actionDelay <value>	Time in milliseconds to wait between each action	N/A
--lc	--locale <locale>	Locale setting for the test run	N/A
--du	--duration <duration>	Duration of a single test run in milliseconds (Default: 120000, i.e., 2 minutes)	"120000"
-h	--help	Displays help for the command	N/A

Tips for CI/CD Integration

Integrating tacl tests into your CI/CD pipelines is straightforward. You can use the same npx @tacl/runner command along with the necessary environment variables to run your tests automatically. Here are some tips to keep in mind:

• Browser Binaries: Ensure you run npx playwright install as part of your pipeline steps. This will install the required browser binaries, ensuring that your tests run successfully.
• Environment Variables: Set your API key (and any other required variables) in your CI/CD environment. For example, in GitHub Actions, you can reference secrets as shown below.

Example: GitHub Actions Workflow

- name: Install Playwright Browsers
  run: npx playwright install

- name: Run tacl tests
  env:
    TACL_API_KEY: ${{ secrets.TACL_API_KEY }}
  run: npx @tacl/runner -t 12345

Conclusion

By following this guide, you can efficiently run and manage your tacl tests locally while also integrating them seamlessly into your CI/CD pipeline. Adjust the command options and environment settings to best suit your project's requirements, and enjoy the flexibility of running automated tests in multiple environments.