Project Settings

Access the Project Settings page by clicking the Settings icon on any project card from the Projects dashboard. This comprehensive settings area is your control center for a specific project.

Edit Project Details

The Edit tab allows you to modify the project’s basic information:

Project Name: The name of the project.
URL: The primary URL that your tests will be run against.

mechasm.ai/dashboard/projects/.../edit

Environment Variables

The Environment tab stores custom values used by your tests without hardcoding them. Email and VPN connection settings are managed in their own tabs and do not appear here.

mechasm.ai/dashboard/projects/.../settings/env

CI Integration

The CI Integration tab is where you can configure how your tests are run from your Continuous Integration (CI) pipeline and get the necessary credentials to do so.

mechasm.ai/dashboard/projects/.../settings/ci

Test Run Mode

You can choose how your tests are executed:

Queue: Tests are run one after another in the order they are received.
Parallel: Tests are run concurrently to speed up the execution process.

All manual and CI runs share your organization’s parallel-test allowance. Extra runs wait in order; regeneration keeps its current slot until the run passes or finally fails.

Triggering Tests from CI

To run your tests from a CI environment, you’ll need a CI Token. You can generate one here if you don’t have one, or regenerate it if needed.

Note for Local Testing: When running this script locally, you must prepend stdbuf -oL to the curl command to disable output buffering. This is not needed in most CI environments like GitHub Actions, but is essential for local execution. Once you have a token, you can integrate tests into your CI pipeline with a simple bash script using only standard Unix tools. Here’s how it works:

Zero Dependencies: Uses only curl and jq - available in virtually all CI environments
Real-Time Logging: Streams test logs in real-time using Server-Sent Events (SSE)
Robust Connection: Retries interrupted streams and bounds each connection to 10 minutes
Accurate Status: Lists passed, failed, and incomplete runs, then exits with the correct status

How It Works

The script performs three steps:

Trigger Run: Makes a POST request to start your test suite
Stream Logs: Connects to SSE endpoint and prints logs in real-time
Check Status: Waits for final status event and exits with appropriate code

Example GitHub Actions Integration:

- name: Run Tests
  run: |
    # Trigger test run
    RESPONSE=$(curl --fail-with-body --show-error -s \
      --connect-timeout 30 --max-time 60 \
      -X POST 'https://api.mechasm.ai/ci-runs/trigger' \
      -H 'Content-Type: application/json' \
      -H 'x-ci-token: ${{ secrets.CI_TOKEN }}' \
      -d '{}')

    CI_RUN_ID=$(echo "$RESPONSE" | jq -r '.ciRunId // empty')

    if [ -z "$CI_RUN_ID" ] || [ "$CI_RUN_ID" = "null" ]; then
      echo "❌ Failed to start CI run"
      echo "Response: $RESPONSE"
      exit 1
    fi

    echo "🚀 CI Run ID: $CI_RUN_ID"
    echo "📋 Streaming logs..."

    # Stream logs and capture final status from API
    PASSED=0
    FAILED=0
    INCOMPLETE=0
    STATUS=""
    FINAL_STATUS_JSON=""

    while IFS= read -r line; do
      if [[ $line == data:* ]]; then
        json_data="${line#data: }"

        # Print log content
        if echo "$json_data" | jq -e '.content' &>/dev/null; then
          echo "$json_data" | jq -r '"[\(.timestamp[11:19])] [\(.testRunId[0:8])] \(.content)"'
        fi

        # Check for final status
        if echo "$json_data" | jq -e '.type == "status"' &>/dev/null; then
          PASSED=$(echo "$json_data" | jq -r '.passed // 0')
          FAILED=$(echo "$json_data" | jq -r '.failed // 0')
          INCOMPLETE=$(echo "$json_data" | jq -r '.incomplete // 0')
          STATUS=$(echo "$json_data" | jq -r '.status // "failed"')
          FINAL_STATUS_JSON="$json_data"
          break
        fi
      fi
    done < <(curl --fail-with-body --show-error -sN --http1.1 \
      --connect-timeout 30 --max-time 600 \
      --retry 2 --retry-all-errors --retry-delay 2 \
      "https://api.mechasm.ai/stream/ci-run/$CI_RUN_ID" \
      -H "x-ci-token: ${{ secrets.CI_TOKEN }}")

    # Check if we received final status
    if [[ -z "$FINAL_STATUS_JSON" ]]; then
      echo ""
      echo "⚠️ Error: Did not receive final status from server"
      exit 1
    fi

    echo ""
    echo "📊 Test results:"
    echo "$FINAL_STATUS_JSON" | jq -r '
      .runs[]? |
      (if .status == "passed" then "✅"
       elif .status == "failed" then "❌"
       else "⚠️" end) +
      " [" + (.testRunId[0:8]) + "] " + .testName + " — " + .status'
    echo "Summary: $PASSED passed, $FAILED failed, $INCOMPLETE incomplete"

    # Check test results
    if [[ "$STATUS" != "completed" ]] || (( FAILED > 0 || INCOMPLETE > 0 )); then
      echo ""
      echo "❌ CI failed"
      exit 1
    else
      echo ""
      echo "✅ Tests passed: $PASSED passed"
      exit 0
    fi

Filtering with Tags

You can selectively run tests by filtering them based on tags. In the CI Integration tab, you’ll find a tag selector that allows you to choose from all existing tags within the project.

Select Tags: Click the dropdown to see a list of available tags. Select one or more tags to filter the tests that will be executed.
Persistent Filters: The tags you select are saved as part of the project’s settings. Any subsequent CI run triggered via the curl command will only execute tests matching these tags.
Updated curl Command: The provided curl command automatically includes the selected tags, ensuring your CI pipeline runs the correct subset of tests.

This feature is useful for running specific test suites, such as smoke tests, regression tests, or tests for a particular feature, without executing the entire test suite.

Email Integration

The Email tab contains the inbox host, username, and password used for email-based test steps. Configure and enable the integration without adding custom environment variables. See IMAP Integration.

VPN Integration

The VPN tab contains the protocol, configuration file, credentials, and DNS settings. Upload the original .ovpn or .conf file; Mechasm handles the required conversion. See VPN Integration.

Assets Settings

The Assets Settings tab lets you configure how recordings (videos and traces) of your test runs are handled.

docs.mechasm.ai/assets-settings.png

Video Recording

You can control when video recordings are saved:

Save on Passed: Save a video recording even when the test passes.
Save on Failed: Save a video recording only when the test fails.

Trace Recording

You can control when traces are saved:

Save on Passed: Save a trace file even when the test passes.
Save on Failed: Save a trace file only when the test fails.

Test Files

The Files tab stores files uploaded for browser tests and files captured from browser downloads. Configure file limits, retention, and how repeated downloads are handled. See Project Files for the full guide.