diff --git a/cli/concepts/key-terms.mdx b/cli/concepts/key-terms.mdx index 32ef10f..2587496 100644 --- a/cli/concepts/key-terms.mdx +++ b/cli/concepts/key-terms.mdx @@ -1,11 +1,31 @@ --- title: "Key Terms" -description: "Core CLI concepts — projects, tests, runs, statuses, credits, scopes, and failure bundles — all in one place." +description: "Core CLI concepts — workspaces, API keys, projects, tests, runs, statuses, credits, scopes, and failure bundles — all in one place." icon: "square-code" --- This page defines the building blocks you'll see across every `testsprite` command. If a term in the docs feels unfamiliar, this is the place to land. +## Workspace + +Every user has a **personal workspace**, and can belong to one or more **shared workspaces**. Every project, test, and API key belongs to exactly one workspace — whichever one is active when it's created. + + + + - A **personal workspace** is created automatically for you; work here draws on your personal balance. + - A **shared workspace** holds work that belongs to the workspace itself, visible to every member; work here draws on the workspace's balance instead. + + The CLI doesn't have a "switch workspace" command — which workspace you're acting in is determined entirely by the API key you've configured. + + + Every `projectId`, `testId`, and `runId` the CLI returns belongs to the workspace tied to your active API key. To act in a different workspace, configure a key minted from that workspace instead — see [Authentication](/cli/core/authentication) for personal vs. workspace keys. + + + + + Personal vs. shared workspaces, members, and roles + + ## Project A **project** is the top-level named container for your tests. Frontend projects target a live public URL; backend projects point at a codebase. Every project has a stable `projectId` you use in most commands. @@ -168,6 +188,10 @@ Every run is tagged with the surface that triggered it. The **run source** lets **Credits** are the consumption unit for test execution. The CLI reports your balance via `testsprite usage` and exits non-zero when balance is insufficient. + +Which balance `testsprite usage` reports depends on your active API key: a personal key reports your personal balance, a workspace key reports that workspace's balance. See [API Key](#api-key) below. + + Key rules: @@ -192,6 +216,27 @@ Every run is tagged with the surface that triggered it. The **run source** lets +## API Key + +The credential the CLI stores in `~/.testsprite/credentials` and sends with every request. Two kinds exist — a **personal key** (`sk-user-...`), the original kind, bound to you; and a **workspace key** (`sk-member-...`), scoped to a specific shared workspace and the only kind mintable today — see [Workspace](#workspace) above for how the two relate. + + + + Every key carries a list of **scopes** (see [Scopes](#scopes) below) regardless of kind. `testsprite setup` verifies whichever key you provide against `GET /me` before storing it. + + + ```bash + testsprite auth status + ``` + + Shows the identity and scopes bound to your active key, whichever kind it is. + + + + + Personal vs. workspace keys — creation, expiry, and revocation + + ## Scopes **Scopes** are permissions that an API key carries. The CLI checks scopes before sending write or run requests, and when access is denied it prints which scope was required and which scopes your key holds. Read commands need read scopes, writes need `write:tests`, and runs need `run:tests`; the purely local `agent install` command needs none, and `setup` works with any valid key. diff --git a/cli/core/authentication.mdx b/cli/core/authentication.mdx index c736006..da19f90 100644 --- a/cli/core/authentication.mdx +++ b/cli/core/authentication.mdx @@ -152,6 +152,12 @@ API keys carry a list of **scopes** that gate which operations the CLI can perfo If a command fails with a scope error, the CLI prints the required and granted scopes in both text and JSON modes. You can generate a new key with the needed scopes in the dashboard at Settings → API Keys → Create new key. +## Personal vs. workspace keys + +The key you configure above can be either kind: a **personal key** (`sk-user-...`) — the original kind, if you already hold one — bound to you and drawing on your personal balance no matter which workspace page you copied it from, or a **workspace key** (`sk-member-...`) — the only kind mintable today — scoped to a specific shared workspace and drawing on that workspace's balance. Either kind works the same way with the CLI — `testsprite setup` doesn't care which one you paste in. + +Both kinds are capped: 2 active workspace keys per member per workspace, and 3 active personal keys. So replacing a lost or leaked key isn't always as simple as minting a fresh one — if you're already at the cap, revoke one first. + The Web Portal key management walkthrough diff --git a/cli/getting-started/installation.mdx b/cli/getting-started/installation.mdx index e989a27..6846171 100644 --- a/cli/getting-started/installation.mdx +++ b/cli/getting-started/installation.mdx @@ -23,9 +23,9 @@ Before installing, make sure you have: The CLI requires **20.19+**, **22.13+**, or **24+** — the odd-numbered releases (21.x, 23.x) aren't supported. If your version doesn't fall in one of those ranges, download a newer release from [nodejs.org ](https://nodejs.org/). The CLI also checks the Node version at startup and exits with a clear message if it's too old. - Sign in to your TestSprite dashboard, navigate to Settings → API Keys, and click Create new key. The key is shown exactly once — copy it before closing the dialog. If you lose it, just create a new one. + Sign in to your TestSprite dashboard, navigate to Settings → API Keys, and click Create new key. The key is shown exactly once — copy it before closing the dialog. The key you get is a **workspace key** (`sk-member-...`), bound to whichever workspace's page you were on, and capped at 2 active per member per workspace. (TestSprite also has an older **personal key** kind, `sk-user-...` — if you already hold one it keeps working, but new keys are always workspace keys.) If you lose it, revoke it and create a new one — revoke one of the existing keys first if you're already at the cap. - See [API Keys](/web-portal/admin/api-keys) for the full walkthrough. + See [API Keys](/web-portal/admin/api-keys) for the full walkthrough, including personal vs. workspace keys. @@ -64,7 +64,7 @@ The CLI's source code, releases, and issue tracker live on [GitHub](https://gith API Keys page with the Create new key button -3. Copy the key — it is shown **once only**. If you lose it, delete the key and create a new one. +3. Copy the key — it is shown **once only**. If you lose it, revoke it and create a new one. (A workspace key is capped at 2 active per member per workspace — revoke one first if you're already at the limit.) API Key Created dialog with the copy button diff --git a/cli/integrations/ci-cd.mdx b/cli/integrations/ci-cd.mdx index 0cfd676..7f82ce5 100644 --- a/cli/integrations/ci-cd.mdx +++ b/cli/integrations/ci-cd.mdx @@ -12,6 +12,12 @@ The `testsprite` CLI is designed from the ground up for unattended execution: - **Stable `--output json`** — every command emits a machine-readable JSON envelope that your pipeline can parse and forward. - **Stable exit codes** — exit 0 means the run passed; any non-zero exit lets the shell fail the job. No text scraping required. + +**Your target must be reachable from TestSprite's cloud.** Tests run on TestSprite's cloud runners, so `--target-url` has to be a public `http(s)` address. `localhost`, `127.0.0.1`, `::1`, `0.0.0.0`, link-local, and private (RFC 1918) addresses are **rejected during pre-flight with exit code `5`, before any run is triggered** — so a dev server started inside the CI job cannot be tested directly. This is the most common first-run CI failure. + +In CI, point `--target-url` at a **publicly reachable preview, staging, or deploy-preview URL** (for example, the per-pull-request preview URL your hosting provider creates). To test a local app, use the [TestSprite MCP Server](/mcp/getting-started/introduction), which opens a tunnel for you — the CLI itself does not tunnel. + + ## Authenticating in CI Set your API key as a repository or environment secret. In GitHub, go to Settings → Secrets and variables → Actions and click New repository secret: @@ -67,6 +73,10 @@ testsprite test run test_3a9f21c7 --wait --output json > result.json || \ ## A GitHub Actions workflow + +Install and invoke the `testsprite` CLI directly, as the example below does — this is the supported way to run TestSprite in CI, on any platform. If you previously set up an older TestSprite GitHub Action from the marketplace, migrating to the CLI gives you stable exit codes, JUnit output, and a consistent pass/fail verdict. + + The example below runs all backend tests in a project on every pull request and fails the job if any test does not pass: ```yaml diff --git a/docs.json b/docs.json index 8078c36..9836695 100644 --- a/docs.json +++ b/docs.json @@ -150,6 +150,7 @@ { "group": "Admin", "pages": [ + "web-portal/admin/workspaces", "web-portal/admin/api-keys", "web-portal/admin/billing-and-plans" ] diff --git a/mcp/getting-started/installation.mdx b/mcp/getting-started/installation.mdx index 0da70ef..b6fb770 100644 --- a/mcp/getting-started/installation.mdx +++ b/mcp/getting-started/installation.mdx @@ -37,6 +37,8 @@ First, you'll need a TestSprite API key for any installation method: 3. Click **"New API Key"** 4. **Copy** your API key (you'll need it for installation) +The key you just created is a **workspace key** (`sk-member-...`), bound to whichever workspace's page you were on. TestSprite also has an older **personal key** kind (`sk-user-...`) — if you already hold one it works equally well with the MCP Server. See [API Keys](../../web-portal/admin/api-keys) for the full comparison, including expiry and revocation. + ## Installation Follow the instructions for your specific client to add the TestSprite MCP server. diff --git a/mcp/troubleshooting/ide-configuration-issues.mdx b/mcp/troubleshooting/ide-configuration-issues.mdx index 8c56247..5dd5985 100644 --- a/mcp/troubleshooting/ide-configuration-issues.mdx +++ b/mcp/troubleshooting/ide-configuration-issues.mdx @@ -255,14 +255,14 @@ If you experience issues about **Invalid or missing API key**, please follow the ```json { "env": { - "API_KEY": "ts_live_abcd1234efgh5678ijkl" + "API_KEY": "sk-user-abcd1234efgh5678ijkl" } } ``` - - Should start with `sk-user-` + - Should start with `sk-user-` (a personal key) or `sk-member-` (a workspace key) — both are equally valid for the MCP Server - Should be 32+ characters long - No extra spaces or characters diff --git a/web-portal/admin/api-keys.mdx b/web-portal/admin/api-keys.mdx index 4def2b5..d1fb975 100644 --- a/web-portal/admin/api-keys.mdx +++ b/web-portal/admin/api-keys.mdx @@ -1,31 +1,55 @@ --- -title: "API Keys & MCP Integration" -description: "Manage your TestSprite API keys in the Web Portal and view test results from MCP Server executions." +title: "API Keys" +description: "The two kinds of TestSprite API keys — personal and workspace — what each is bound to, and how to create, expire, and revoke them." icon: "key" --- -## Generating API Keys +## Two Kinds of API Keys -Generate API keys for MCP Server integration and other third-party tools. +An API key authenticates the CLI and the MCP Server as you. Two kinds exist: - - - Go to Settings > API Keys and click New API Key. - +| | Personal key | Workspace key | +| :--- | :--- | :--- | +| **Prefix** | `sk-user-` | `sk-member-` | +| **How you get one** | Not mintable today — this is the original key kind, from before workspace keys existed | Click **New API Key** on any workspace's API Keys page, including your personal workspace's | +| **Bound to** | You — not to any workspace, so it behaves the same wherever it was created | The workspace whose page minted it | +| **Where it's listed** | Your personal workspace's API Keys page | That workspace's API Keys page | +| **Draws on** | Your personal balance | That workspace's balance | +| **What it creates** | Lands in your personal workspace | Belongs to that workspace | +| **Active-key cap** | 3 active | 2 active per member, per workspace | +| **Revoking** | Revokes it everywhere — it was never workspace-scoped | Revokes that key only; you can mint another for the same workspace | + + +Both kinds are capped, with different limits: 2 active workspace keys per member per workspace (so you can rotate one while the other stays in use), and 3 active personal keys. Going over a cap fails until you revoke one. Revoking is immediate. + + + +Personal keys predate the workspace-key kind and can no longer be minted. If you already have one, it keeps working exactly as before — every key minted today, from any workspace's API Keys page, is a workspace key. + +A shared workspace's API Keys page lists only that workspace's keys. Your personal keys are on your personal workspace's page, where you can also revoke them — they're left off a shared workspace's page because anything they create lands in your personal workspace, not in the shared one. + + +See [Workspaces](../../web-portal/admin/workspaces) for what a workspace is and how personal vs. shared workspaces differ. + +## Creating a Key + +Every key minted today is a workspace key — there's no separate flow for a personal key. Go to Settings > API Keys in whichever workspace should own the key and click New API Key; the key you get back is bound to that workspace, including your personal workspace if that's the page you were on. + + API Key - - - - Provide a **descriptive name** (e.g., "MCP Integration"), click Create, then use the copy icon to copy the generated API key immediately. - - Store it securely. It won't be shown again - - - API Key - - - + +Provide a **descriptive name** (e.g., "MCP Integration") and optionally set an expiration. Leave it blank and the key does not expire — unless the workspace enforces a maximum lifetime, in which case a longer expiry you request is rejected, and a key created without one is issued with that maximum instead. Click Create, then use the copy icon to copy the generated key immediately. + + + Store it securely. It won't be shown again. + + + +API Key + + +The key is stored hashed; its full value is shown exactly once, at creation, and never again. ## Managing API Keys @@ -40,8 +64,9 @@ Generate API keys for MCP Server integration and other third-party tools. | Field | Description | | :--- | :--- | | Name | Descriptive identifier | -| API Key | Partially hidden (e.g., `sk_test_****...****abcd`) | +| API Key | Partially hidden. A personal key shows its first and last few characters (`sk-user-abcde...vwxyz`); a workspace key shows only its leading characters (`sk-member-ab...`), because the rest is never stored in a readable form | | Created At | When generated | +| Expires | Optional at creation. If not set, the key does not expire — unless the workspace enforces a maximum lifetime, in which case it's issued with that maximum | Manage your API keys with these actions to control access, monitor usage, and maintain security. @@ -86,6 +111,9 @@ Click on any test result to view **detailed test execution logs**, **individual Your API key is used in the MCP Server configuration to authenticate with TestSprite's testing engine. + + What a workspace is and how personal vs. shared workspaces differ + Get hands-on experience with TestSprite MCP diff --git a/web-portal/admin/workspaces.mdx b/web-portal/admin/workspaces.mdx new file mode 100644 index 0000000..7bdba2d --- /dev/null +++ b/web-portal/admin/workspaces.mdx @@ -0,0 +1,55 @@ +--- +title: "Workspaces" +description: "What a workspace is, how a shared workspace differs from your personal workspace, and where members and credentials fit in." +icon: "users" +--- + +## What a Workspace Is + +Everything you do in TestSprite — projects, tests, runs, and API keys — belongs to a **workspace**. Every user has a **personal workspace** automatically, and can also belong to one or more **shared workspaces**. + +Whichever workspace is active determines where new work lands: projects you create, tests you generate, and keys you mint all belong to that workspace, not to you individually. + + +Access inside a workspace is all-members: everyone who belongs to a workspace can see and work with its projects and tests. Roles only gate workspace management itself — things like membership and workspace settings — not day-to-day testing. + + +## Personal Workspace vs. Shared Workspaces + + + + Your personal workspace is created for you automatically and is yours alone — there's no membership to manage. Anything created here draws on your personal balance. + + + A shared workspace holds work that belongs to the workspace itself rather than to any one member. Anyone who belongs to it can see and work with its projects and tests, and spend on work created there draws on the workspace's own balance rather than any individual member's. + + + +## Creating and Switching Workspaces + +You can create additional shared workspaces and switch between them and your personal workspace. Whichever workspace is active at the time determines where a new project, test, or API key is created — so it's worth checking which workspace you're in before you start new work. + +Workspace management — creating a workspace, inviting or removing members, and changing workspace-level settings — lives under Workspace Settings in the Settings area. + +## Members and Roles + +Every member of a shared workspace can see and work with the workspace's projects and tests — there's no per-project access restriction between members. Roles come into play only for managing the workspace itself (for example, membership and workspace settings), not for using it day to day. + +## Credentials + +Workspaces don't have their own separate concept of a login — what you use to authenticate is an **API key**, and a key can either belong to you personally or be scoped to a specific workspace. For the full breakdown of the two kinds of keys, how they're minted, and which balance each one draws on, see the API Keys page. + + + Personal vs. workspace keys, creation, expiry, and revocation + + +## Where to Go Next + + + + Create workspace keys, plus manage any key you already hold + + + Plan tiers and monthly credits + + diff --git a/web-portal/concepts/key-terms.mdx b/web-portal/concepts/key-terms.mdx index d8267f5..796b237 100644 --- a/web-portal/concepts/key-terms.mdx +++ b/web-portal/concepts/key-terms.mdx @@ -1,11 +1,28 @@ --- title: "Key Terms" -description: "Core concepts you'll encounter throughout the TestSprite Web Portal — projects, tests, lists, schedules, and the data they collect." +description: "Core concepts you'll encounter throughout the TestSprite Web Portal — workspaces, API keys, projects, tests, lists, schedules, and the data they collect." icon: "square-code" --- This page defines the building blocks the Web Portal uses. If you've already used TestSprite once, most of these will feel familiar — this is the canonical reference for when a teammate asks "wait, what's a Test List vs a Test?" +## Workspace + +The container everything else on this page lives inside. Every user has a **personal workspace**, and can also belong to one or more **shared workspaces**. Whichever workspace is active determines where a new project, test, or API key belongs. + + + + A personal workspace is created for you automatically and has no membership to manage. A shared workspace holds work that belongs to the workspace itself — visible to every member — rather than to any one person; roles gate workspace management (membership, workspace settings) but not day-to-day use of what's inside. + + + Workspace management lives under Workspace Settings in Settings. + + + + + Personal vs. shared workspaces, members, and roles + + ## Project The top-level container for everything you do in the portal. A project represents one application (or one slice of an application — e.g. one micro-frontend or one API surface) and groups all the tests, runs, credentials, and variables that belong to it. @@ -166,6 +183,25 @@ The keys, tokens, or login details TestSprite uses to call your APIs or sign int +## API Key + +Not to be confused with **Credentials** above: an API key authenticates *you* to TestSprite (it's what the CLI and MCP Server use to act on your behalf), while Credentials are what TestSprite uses against *your* app or API under test. + +Two kinds exist: a **personal key** (`sk-user-...`) — the original kind, bound to you and your personal balance — and a **workspace key** (`sk-member-...`) — scoped to a specific shared workspace and its balance, capped at 2 active per member per workspace. Personal keys predate the workspace-key kind and are no longer mintable; any workspace's API Keys page, including your personal workspace's, always mints a workspace key. + + + + Minted from a workspace's API Keys page, bound to that workspace, shown once at creation, and revocable at any time. An optional expiration can be set at creation — leave it blank and the key does not expire, unless the workspace enforces a maximum lifetime, in which case a longer expiry is rejected and a key created without one gets that maximum instead. + + + Under Settings → API Keys — your personal workspace's page lists any personal key you already hold plus any workspace keys minted from that page, and each shared workspace's page lists that workspace's keys. + + + + + The full comparison, plus creation, expiry, and revocation + + ## Cleanup Post-run teardown of resources tests created — records, files, sessions — so your test environment doesn't fill with leftovers. diff --git a/web-portal/getting-started/overview.mdx b/web-portal/getting-started/overview.mdx index 2772524..378feea 100644 --- a/web-portal/getting-started/overview.mdx +++ b/web-portal/getting-started/overview.mdx @@ -148,6 +148,7 @@ Different roles get different value out of the same dashboard: | All Tests | Every project you've created, grouped by type, with run status and quick-rerun | | Test Lists | Group tests across projects into a single executable list — see [Test Lists](/web-portal/maintenance/test-lists) | | Monitoring | Schedule Test Lists to run on a cadence with execution history — see [Monitoring](/web-portal/maintenance/monitoring) | +| Settings → Workspace Settings | Create and switch workspaces, manage members — see [Workspaces](/web-portal/admin/workspaces) | | Settings → API Keys | Generate keys for MCP / external tooling | | Settings → GitHub App | Connect repos for PR-based test runs and code export | | Settings → Plan & Billing | Plan tier, monthly credits, and feature gating |