Library guide#

go get gitlab.com/agentic-fx/surge

package main

import (
	"time"
	"gitlab.com/agentic-fx/surge"
)

func main() {
	s := surge.New("shop")                        // a scenario
	s.BaseURL("http://localhost:8080").
		Closed(50, 2*time.Minute).                // 50 users for 2 minutes
		Thresholds("p95 < 500ms", "error_rate < 1%")

	buyer := s.User("buyer", 3).                  // a population, weight 3
		Wait(time.Second, 3*time.Second)          // think time between tasks

	buyer.OnStart(func(c *surge.Ctx) error {      // once per virtual user
		r := c.POST("/auth/login", surge.Name("login"),
			surge.JSON(map[string]string{"username": "u", "password": "p"}))
		c.Set("token", r.JSON("data.token"))
		return r.Err()
	})

	buyer.Task("browse", 4, func(c *surge.Ctx) error {   // weight 4
		c.GET("/api/items", surge.Name("browse"), surge.Bearer(c.Str("token")))
		return nil
	})

	s.RunMain()                                   // flags, run, exit code
}

go run .                               # the plan in the code
go run . -vus 200 -duration 5m         # override it
go run . -rate 500 -duration 1m -html report.html

s.ClosedStages(
	surge.Stage{Duration: 30 * time.Second, Target: 100},  // ramp
	surge.Stage{Duration: 2 * time.Minute, Target: 100},   // hold
	surge.Stage{Duration: 30 * time.Second, Target: 0},    // down
)

s.OpenStages(                                              // arrival rate
	surge.Stage{Duration: 30 * time.Second, Target: 200},
	surge.Stage{Duration: time.Minute, Target: 1000},       // find the knee
)

s.SetupCommand("./scripts/seed.sh 150").
	TeardownCommand("./scripts/clean.sh").
	HookTimeout(10 * time.Minute)

s.SetupCommand("psql", "-f", "seed.sql")

api := s.User("api-client", 7)      // 70% of VUs
ui := s.User("ui-user", 3)          // 30%

api.Task("items", 1, func(c *surge.Ctx) error {
	return c.GET("/api/items", surge.Name("items")).Err()
})

ui.Sequential()                     // a fixed journey, step per iteration
ui.Task("home", 1, func(c *surge.Ctx) error { return c.GET("/").Err() })
ui.Task("search", 1, func(c *surge.Ctx) error { return c.GET("/search?q=hat").Err() })
ui.Task("checkout", 1, func(c *surge.Ctx) error { return c.POST("/cart/checkout").Err() })

r := c.GET("/api/items", surge.Name("items"))
if r.OK() && r.JSONExists("items.0.id") {
	c.Set("first", r.JSON("items.0.id"))
}

c.Set("token", r.JSON("data.token"))   // per-VU state
c.Str("token")                          // read it back as a string
c.Value("conn")                         // read any value

c.Check("order confirmed", r.JSON("status") == "confirmed")  // feeds check_rate
c.Think(time.Second, 3*time.Second)                          // interruptible pause

c.VU()          // this VU's number
c.UserName()    // which population
c.Context()     // the run context

u.OnStart(func(c *surge.Ctx) error {
	conn, err := grpc.Dial(addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		return err
	}
	c.Set("client", pb.NewSearchClient(conn))
	c.Set("conn", conn)
	return nil
})

u.OnStop(func(c *surge.Ctx) {
	c.Value("conn").(*grpc.ClientConn).Close()
})

u.Task("search", 1, func(c *surge.Ctx) error {
	client := c.Value("client").(pb.SearchClient)
	return c.Time("grpc.Search", func() error {
		_, err := client.Search(c.Context(), &pb.Query{Term: "widget"})
		return err
	})
})

sum, err := s.Run(context.Background())
if err != nil {
	log.Fatal(err)          // setup problem; a failed threshold is not an error
}

for _, r := range sum.Requests {       // per request name
	fmt.Printf("%s p95=%.1fms errors=%d\n", r.Name, r.P95Ms, r.Errors)
}
for _, t := range sum.Thresholds {
	fmt.Printf("%v %s (actual %s)\n", t.OK, t.Expr, t.Actual)
}

func TestCheckoutPerformance(t *testing.T) {
	if testing.Short() {
		t.Skip("load test skipped in -short mode")
	}
	staging := "https://staging.example.com"
	s := surge.New("checkout-budget").BaseURL(staging).Quiet().
		Closed(20, 30*time.Second).
		Thresholds("p95 < 400ms", "error_rate < 1%")

	s.User("u", 1).Task("checkout", 1, func(c *surge.Ctx) error {
		return c.POST("/api/checkout", surge.Name("checkout")).Err()
	})

	sum, err := s.Run(context.Background())
	if err != nil {
		t.Fatal(err)
	}
	if !sum.Passed {
		for _, th := range sum.Thresholds {
			if !th.OK {
				t.Errorf("threshold failed: %s (actual %s)", th.Expr, th.Actual)
			}
		}
	}
}