Mastra Smoke Test

Comprehensive smoke testing for Mastra projects.

⚠️ Mandatory Test Checklist

Use

task_write

--test

Do not skip tests unless you hit an actual blocker. "Seemed complex" or "wasn't sure" are not valid reasons. Attempt everything - only stop a test when you literally cannot proceed. Report what you tried and what blocked you.

references/tests/setup.md

references/tests/agents.md

--test agents

references/tests/tools.md

--test tools

references/tests/workflows.md

--test workflows

references/tests/traces.md

--test traces

references/tests/scorers.md

--test scorers

references/tests/memory.md

--test memory

references/tests/mcp.md

--test mcp

references/tests/errors.md

--test errors

references/tests/studio.md

--test studio

references/tests/server.md

--test server

Execution Flow

1. Read the reference file for each test you're about to run
2. Execute the steps in that reference file
3. Mark the test complete before moving to the next

Partial Testing (

--test

)

If

--test

1. Always run Setup (step 1)
2. Run only the specified test(s)
3. Skip other tests

Example:

--test agents,traces

Usage

# Full smoke test
smoke test --env local --existing-project ~/my-app
smoke test --env staging -d ~/projects -n test-app

# Partial testing
smoke test --env local --existing-project ~/my-app --test agents
smoke test --env production --existing-project ~/my-app --test studio,server,traces

# Multi-environment: same project, different targets
smoke test --env staging --existing-project ~/my-app   # Uses .mastra-project-staging.json
smoke test --env production --existing-project ~/my-app # Uses .mastra-project.json

Multi-Environment Support

One project can target all environments using separate config files:

pnpm dev

.mastra-project-staging.json

.mastra-project.json

See

references/tests/setup.md

Parameters

--env

local

staging

production

--directory

~/mastra-smoke-tests

--name

--existing-project

--tag

latest

alpha

--pm

pnpm

--llm

openai

--db

libsql

libsql

pg

turso

--test

--browser-agent

false

--skip-browser

false

--byok

false

* Either

--directory

--name

--existing-project

Test Options (

--test

)

agents

tools

workflows

traces

scorers

memory

mcp

errors

studio

server

Prerequisites

All environments:

• Node.js + package manager
• LLM API key in env or

  .env

Local (

--env local

• Browser tools enabled (

  /browser on

  )

Cloud (

--env staging/production

• Mastra platform account

Quick Start Flow

1. Setup      → Read references/tests/setup.md, create/verify project
2. Start      → `pnpm run dev` (local) or deploy (cloud)
3. Test       → For each test, read its reference file and execute
4. Verify     → Check all items in reference file's checklist
5. Report     → Summarize pass/fail for each test

References

references/tests/*.md

references/local-setup.md

references/cloud-deploy.md

references/cloud-advanced.md

references/common-errors.md

references/gcp-debugging.md

scripts/test-server.sh

Platform Dashboards

• Production:

  https://projects.mastra.ai

• Staging:

  https://projects.staging.mastra.ai

For Gateway API testing (memory, threads, BYOK via gateway), use

platform-smoke-test

.

Result Reporting

After testing, provide:

## Smoke Test Results

**Environment**: local/staging/production
**Project**: <name>

| Test   | Status | Notes |
| ------ | ------ | ----- |
| Setup  | ✅/❌  |       |
| Agents | ✅/❌  |       |
| Tools  | ✅/❌  |       |
| ...    |        |       |

**Issues Found**: (list any)
**Warnings**: (list any deploy/runtime warnings)
**Skipped Tests**: (list with reason - e.g., "Server Deploy - not applicable in local environment")