Agent

Introduction

The Skyramp Agent brings powerful automated testing capabilities directly into your IDE. Generate and execute integration, contract, smoke, fuzz, load, E2E, and UI tests with AI assistance, without ever leaving your development flow.

Skyramp Agent is currently available as a VSCode Extension.

Installation

Please refer to the Installation Guide for instructions on how to install Skyramp VS Code Extension.

Getting Started

The agent is designed to provide a self-service experience to Cursor users. When you have any questions about Skyramp capabilities or guidelines for using a tool, simply ask VS code and it will leverage internal agent documentation to provide you with the most relevant and up-to-date guidance.

When using VS Code, Skyramp Agent works best when using the Claude Sonnet 4.5 model

Below are some example prompts to help you get started.

Discover Capabilities

• “What can I do with Skyramp?”

• “How do I generate an integration test with Skyramp?”

• “How do I generate a UI test with the Skyramp?”

A sample workflow for creating UI tests with the MCP is outlined below. For instructions on how to create other test types using Skyramp, just ask VS Code.

E2E Test Generation

Follow these steps to generate a end-to-end (E2E) test using the Skyramp Extension in VSCode. An E2E test validates an application's entire workflow from start to finish, combining front-end interactions and back-end operations in a single test, to ensure all integrated components work together seamlessly.

Using Skyramp’s Demo Shop, a lightweight e-commerce application for product and order management, we’ll illustrate how traces can be collected and transformed into reliable tests. Learn more about the Demo Shop.

Trace Collection

Skyramp provides a native workflow for collecting traces that power reliable test generation. By working from traces, Skyramp ensures tests are built on real-world behavior, not assumptions, resulting in resilient tests that accurately mirror user flows and backend interactions.

A trace is simply a log of user actions and system behavior captured during a scenario. Skyramp operates as a man-in-the-middle proxy, capturing both UI activity (via Playwright) and network traffic. It collects data from three key sources:

• Network traffic through the CLI

• Network traffic from the Browser

• UI traces through the Playwright recorder

Skyramp’s test generation engine then correlates these trace files to automatically produce high-fidelity test cases. In the following sections, we’ll walk through how to record your first trace and use it as the foundation for generating a test.

Want to skip straight to test generation? Download the following trace file.
You can find more information on the recorded scenario here.

Start Trace Collection

To start collecting traces, you can use the following prompt in the chat.

The first time you run this command, it might take a while to bring up Skyramp. If you come across issues start the trace collection for the first time, please refer to the 'Trace Collections section of the Troubleshooting guide.

This will trigger Cursor to call the Skyramp function skyramp_start_trace_collection and will launch three new windows on your Desktop:

• Terminal window (records network traffic triggered via shell)

  • Note: The terminal window used when collecting backend calls during the trace, not relevant for UI Test generation

• Playwright Browser (records network traffic triggered via the UI)

• Playwright Inspector (records all UI interactions)

Additional flags

• Viewport-size: ... and use the viewport size "1440, 960"

  • This controls the browser size during trace collection.

  • You can choose from the following predefined sizes:

    • hd - 1280 x 720

    • full-hd - 1920 x 1080

    • 2k - 2560 x 1440

    • 'x,y' - you can choose what height and width you prefer for your trace collection

• Playwright-storage: ... and use the playwright storage path/to/session-file

  • This is useful if you want trace collection to start in an already authenticated state (bypassing login + 2FA)

  • If your login requires 2FA and you don’t yet have a session file created yet, please refer to the 'Handling 2FA' section of the Troubleshooting guide.

  • Include: ... and include only https://demoshop.skyramp.dev/* for this test.

    • Specify a comma-separated list of URLs for Skyramp to filter for during trace collection or in a trace file.

  • Exclude: ... and exclude demoshop.skyramp.dev/api/v1/products/* from the test.

    • Specify a comma-separated list of URLs for which you do not want Skyramp to filter for. This flag takes precedence over --include if a URL is specified in both.

If you specify a session file or viewport size during trace collection, those settings will automatically carry over into test generation and execution.

Record Your User Scenario

Now, leverage the freshly spawned Playwright Browser to collect the traces for your E2E test scenario. You can record your own custom user interactions or follow our example test case (Record Scenario Section). Here is a quick summary of the scenario:

1. Setup session (via UI)

2. Create new product (via curl)

3. Find product in product list (via UI)

4. Update the product price (via UI)

5. Create new order containing the new product (via curl)

6. Find order in order list (via UI)

7. Assert total price of the order (via UI)

8. Delete newly created order (via UI)

9. Delete newly created product (via UI)

Stop Trace Collection

Once you have completed your scenario in the Playwright Browser, simply head back to Cursor and ask to stop the trace in the chat.

Stopping trace collection closes the Playwright Browser, Inspector, and the active terminal session. Skyramp will then generate two files in your working directory:

• skyramp-traces.json: Captures the backend traces we completed via curl during the recording. (Sample: skyramp-trace)

• skyramp_playwright.zip: Contains the Playwright trace data used as part of the E2E test generation. (Sample: playwright-trace)

Adjustments

You can adjust the prompt to control the following outputs:

• Output Directory: ... and save the traces in the /traces folder

• Playwright Trace File Name: ... and save the playwright trace as skyramp_playwright.zip

• Backend Trace File Name: ... and save the backend trace as skyramp.json

Generate the E2E Test

Before generating tests, make sure you’re running the latest version of the Skyramp extension. You can verify this by going to the extension menu in VS Code, selecting “Install Specific Version” under the “Uninstall” button, and checking that you’re on the most recent release.

What happens behind the scenes

• Test Generation - Skyramp leverages the skyramp_playwright.zip and skyramp-traces.json and generates your test file (e2e_test.spec.ts).

• Code Optimization - Skyramp automatically modularizes and parameterizes the code for readability and reuse.

• Error Prevention - Skyramp resolves reference errors, undefined variables, and potential runtime issues.

• Execution Ready - Produces test code with smart selectors and intelligent waits that can be run immediately.Adjustments

Adjustments

The prompt can be modified to control details such as:

• Language: Adjust the specified language to another supported language.

• Framework: Adjust the specified framework to another supported framework for the selected test language.

• Test File Name: Specify the test file name (e.g., ... and save the file as skyramp_test.spec.ts)

• Output Directory: Specify the output directory for the test file (e.g., ... and save the file to the /tests folder)

• Trace File: Specify the 2 trace files you want to leverage for the test generation (e.g.,... and use skyramp-traces.json and skyramp_playwright.zip as the trace inputs)

• Auth header : Specify the key of your authentication header (e.g. ...and use the X-API-KEY as the authentication header). By default, we assume Bearer.

• Include: Specify which endpoints you would like to include in your test generation. (e.g., ... and include only https://demoshop.skyramp.dev/* for this test)

• Exclude: Specify with endpoints you would like to exclude from the your test generation. (e.g.,... and exclude demoshop.skyramp.dev/api/v1/products/* from the test)

A Note on Including/Excluding URLs

When using the --include or --exclude flag, URLs need to be specified either as an exact path to the endpoint or in combination with a wildcard:

• demoshop.skyramp.dev/api/v1/products will only filter for POST and GET of the products endpoint.

• demoshop.skyramp.dev/products* will filter for all products endpoints + any nested endpoints.

• demoshop.skyramp.dev/api/v1/products/* will filter only for any nested endpoints that require a product ID. It will not collect the traces of POST and GET products.

For endpoints that require path parameters, please replace the path parameter with the wildcard:

• Convert demoshop.skyramp.dev/products/{product_id}/reviews to demoshop.skyramp.dev/products/*/reviews

Execute Your E2E Test

Now you can run the tests using Playwright. If you don’t have Playwright, refer to the Installation Guide for setup instructions.

Make sure the terminal you’re in has the Skyramp test token exported, when testing with our demo. This token should be the session ID used during trace collection, you can find it in the generated test to confirm which session ID was used.

export SKYRAMP_TEST_TOKEN

Once the token has been exported, you can now execute the test.

npx playwright test e2e_test.spec.ts --reporter

Additional Flags

--headed: Runs the test in a visible browser so you can confirm the scenario step by step.

Test Results

We are using Playwright's List reporter in this guide, printing a line for each test that is being run and listing all failures at the end. You can adjust the reporter behavior following this documentation.

Smart Selector

Local Execution

To enable smart selector capabilities that automatically update flaky selectors at runtime using your own LLM API, make sure to export it as API_KEY as an environment variable. If you don’t have an API key yet, please reach out to the Skyramp team.

export API_KEY

Skyramp Execution

When running the test using Skyramp executor which handles all dependencies and executes the test in a containerized environment, you can Set your API key using environment variables in a .env file.

Create a .env file in your project root (same directory as your package.json or main code):

# .env
API_KEY