From 84706fbcef7646495eecc6bff22f952114459f1c Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Wed, 31 May 2023 14:22:55 +0100 Subject: [PATCH] Adds testable examples to be automatically pulled in redis.io docs (#2601) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Adding examples * Update readme * Update Readme * Remove unneeded lines. Added an examples.json file * Update readme for examples * More fixes * Add example tags * Update examples.json * Rename * Add another hide block * Temporary test * Add example id for lpush and lrange * Update readme * Update output text * Improve examples * Move examples test dir to doctests * Add redis v7's ExpireAtNX, ExpireAtXX, ExpireAtGT, ExpireAtLT, PExpireNX, PExpireXX, PExpireGT, PExpireLT, PExpireAtNX, PExpireAtXX, PExpireAtGT, PExpireAtLT feat: Add redis v7's NX, XX, GT, LT expireat, pexpire, pexpireat variants * add tests for new commands add tests to coverage for the new commands * Adds github workflow to add docexamples tests. Flushes db before every test. * Fixes broken workflow file * Adds Igor’s suggestion of keeping the instructions for docexamples in one place * Removes unneeded “Missing” section, because it was solved as a workflow * Revert "add tests for new commands" This reverts commit af12cb6bd6eba2b68bf90545724f1495fd4797e8. * Fixes review comments * Specifies versions as strings instead of floats --------- Co-authored-by: carner --- .github/workflows/doctests.yaml | 41 ++++++++++++++++++++++++++++ .gitignore | 1 + doctests/README.md | 22 +++++++++++++++ doctests/lpush_lrange_test.go | 47 +++++++++++++++++++++++++++++++++ doctests/set_get_test.go | 47 +++++++++++++++++++++++++++++++++ 5 files changed, 158 insertions(+) create mode 100644 .github/workflows/doctests.yaml create mode 100644 doctests/README.md create mode 100644 doctests/lpush_lrange_test.go create mode 100644 doctests/set_get_test.go diff --git a/.github/workflows/doctests.yaml b/.github/workflows/doctests.yaml new file mode 100644 index 00000000..00b0063b --- /dev/null +++ b/.github/workflows/doctests.yaml @@ -0,0 +1,41 @@ +name: Documentation Tests + +on: + push: + branches: [master, examples] + pull_request: + branches: [master, examples] + +permissions: + contents: read + +jobs: + doctests: + name: doctests + runs-on: ubuntu-latest + + services: + redis-stack: + image: redis/redis-stack-server:latest + options: >- + --health-cmd "redis-cli ping" --health-interval 10s --health-timeout 5s --health-retries 5 + ports: + - 6379:6379 + + strategy: + fail-fast: false + matrix: + go-version: [ "1.18", "1.19", "1.20" ] + + steps: + - name: Set up ${{ matrix.go-version }} + uses: actions/setup-go@v4 + with: + go-version: ${{ matrix.go-version }} + + - name: Checkout code + uses: actions/checkout@v3 + + - name: Test doc examples + working-directory: ./doctests + run: go test \ No newline at end of file diff --git a/.gitignore b/.gitignore index dc322f9b..64a7cb51 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ *.rdb testdata/* .idea/ +.DS_Store diff --git a/doctests/README.md b/doctests/README.md new file mode 100644 index 00000000..2623c184 --- /dev/null +++ b/doctests/README.md @@ -0,0 +1,22 @@ +# Command examples for redis.io + +These examples appear on the [Redis documentation](https://redis.io) site as part of the tabbed examples interface. + +## How to add examples + +- Create a Go test file with a meaningful name in the current folder. +- Create a single method prefixed with `Example` and write your test in it. +- Determine the id for the example you're creating and add it as the first line of the file: `// EXAMPLE: set_and_get`. +- We're using the [Testable Examples](https://go.dev/blog/examples) feature of Go to test the desired output has been written to stdout. + +### Special markup + +See https://github.com/redis-stack/redis-stack-website#readme for more details. + +## How to test the examples + +- Start a Redis server locally on port 6379 +- CD into the `doctests` directory +- Run `go test` to test all examples in the directory. +- Run `go test filename.go` to test a single file + diff --git a/doctests/lpush_lrange_test.go b/doctests/lpush_lrange_test.go new file mode 100644 index 00000000..64020c91 --- /dev/null +++ b/doctests/lpush_lrange_test.go @@ -0,0 +1,47 @@ +// EXAMPLE: lpush_and_lrange +// HIDE_START +package example_commands_test + +import ( + "context" + "fmt" + "github.com/redis/go-redis/v9" +) + +func ExampleLPushLRange() { + ctx := context.Background() + + rdb := redis.NewClient(&redis.Options{ + Addr: "localhost:6379", + Password: "", // no password docs + DB: 0, // use default DB + }) + + // HIDE_END + + // REMOVE_START + errFlush := rdb.FlushDB(ctx).Err() // Clear the database before each test + if errFlush != nil { + panic(errFlush) + } + // REMOVE_END + + listSize, err := rdb.LPush(ctx, "my_bikes", "bike:1", "bike:2").Result() + if err != nil { + panic(err) + } + + fmt.Println(listSize) + + value, err := rdb.LRange(ctx, "my_bikes", 0, -1).Result() + if err != nil { + panic(err) + } + fmt.Println(value) + // HIDE_START + + // Output: 2 + // [bike:2 bike:1] +} + +// HIDE_END diff --git a/doctests/set_get_test.go b/doctests/set_get_test.go new file mode 100644 index 00000000..792bd419 --- /dev/null +++ b/doctests/set_get_test.go @@ -0,0 +1,47 @@ +// EXAMPLE: set_and_get +// HIDE_START +package example_commands_test + +import ( + "context" + "fmt" + "github.com/redis/go-redis/v9" +) + +func ExampleSetGet() { + ctx := context.Background() + + rdb := redis.NewClient(&redis.Options{ + Addr: "localhost:6379", + Password: "", // no password docs + DB: 0, // use default DB + }) + + // HIDE_END + + // REMOVE_START + errFlush := rdb.FlushDB(ctx).Err() // Clear the database before each test + if errFlush != nil { + panic(errFlush) + } + // REMOVE_END + + err := rdb.Set(ctx, "bike:1", "Process 134", 0).Err() + if err != nil { + panic(err) + } + + fmt.Println("OK") + + value, err := rdb.Get(ctx, "bike:1").Result() + if err != nil { + panic(err) + } + fmt.Printf("The name of the bike is %s", value) + // HIDE_START + + // Output: OK + // The name of the bike is Process 134 +} + +// HIDE_END