Add local build/dev tests for examples

examples/astro/package.json

@@ -12,7 +12,7 @@
   "dependencies": {
     "@astrojs/check": "^0.9.4",
     "@astrojs/vercel": "^7.8.2",
-    "@upstash/workflow": "0.1.2-canary-astro",
+    "@upstash/workflow": "latest",
     "astro": "^4.16.7",
     "typescript": "^5.6.3"
   },

examples/bootstrap.sh

@@ -14,10 +14,12 @@ project_arg="$1"
 
 
 # create dist
-# cd ..
-# bun install
-# bun run build
-# cd examples
+cd ..
+bun install
+bun run build
+cd examples/$project_arg
+pnpm i @upstash/workflow@file:../../dist
+cd ..
 
 # install dependencies
 cd "$project_arg"

examples/ci/.env.local.example

@@ -0,0 +1,11 @@
+QSTASH_URL=""
+QSTASH_TOKEN=""
+
+UPSTASH_REDIS_REST_URL=""
+UPSTASH_REDIS_REST_TOKEN=""
+
+QSTASH_CURRENT_SIGNING_KEY=""
+QSTASH_NEXT_SIGNING_KEY=""
+
+# for local development
+UPSTASH_WORKFLOW_URL=""

examples/ci/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "next/core-web-vitals"
+}

examples/ci/.gitignore

@@ -0,0 +1,37 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+ngrok.log

examples/ci/.prettierrc.json

@@ -0,0 +1,54 @@
+{
+  "arrowParens": "always",
+  "bracketSameLine": false,
+  "bracketSpacing": true,
+  "semi": false,
+  "singleQuote": true,
+  "jsxSingleQuote": false,
+  "quoteProps": "as-needed",
+  "trailingComma": "all",
+  "singleAttributePerLine": false,
+  "htmlWhitespaceSensitivity": "css",
+  "vueIndentScriptAndStyle": false,
+  "proseWrap": "preserve",
+  "insertPragma": false,
+  "printWidth": 80,
+  "requirePragma": false,
+  "tabWidth": 2,
+  "useTabs": false,
+  "embeddedLanguageFormatting": "auto",
+  "jsxBracketSameLine": false,
+  "fluid": false,
+  "importOrder": [
+    "^(react/(.*)$)|^(react$)",
+    "^(next/(.*)$)|^(next$)",
+    "",
+    "<THIRD_PARTY_MODULES>",
+    "",
+    "^@/config/(.*)$",
+    "^@/lib/(.*)$",
+    "^@/hooks/(.*)$",
+    "",
+    "^@/components/ui/(.*)$",
+    "^@/components/(.*)$",
+    "",
+    "^@/styles/(.*)$",
+    "",
+    "^types$",
+    "^@/types/(.*)$",
+    "",
+    "^[./]"
+  ],
+  "importOrderSeparation": true,
+  "importOrderSortSpecifiers": true,
+  "importOrderBuiltinModulesToTop": true,
+  "importOrderParserPlugins": [
+    "typescript",
+    "jsx"
+  ],
+  "importOrderMergeDuplicateImports": true,
+  "importOrderCombineTypeAndValueImports": true,
+  "plugins": [
+    "prettier-plugin-tailwindcss"
+  ]
+}

examples/ci/README.md

@@ -0,0 +1,39 @@
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fupstash%2Fqstash-js%2Ftree%2Fmain%2Fexamples%2Fworkflow%2Fnextjs&env=QSTASH_TOKEN&envDescription=You%20can%20access%20this%20variable%20from%20Upstash%20Console%2C%20under%20QStash%20page.%20&project-name=qstash-workflow-nextjs&repository-name=qstash-workflow-nextjs&demo-title=Upstash%20QStash%20Workflow%20Example&demo-description=A%20Next.js%20application%20utilizing%20QStash%20Workflows)
+
+# Upstash Workflow Nextjs Example
+
+This project has some routes showcasing how Upstash Workflow can be used in a nextjs project. You can learn more in [Workflow documentation for Nextjs](https://upstash.com/docs/qstash/workflow/quickstarts/vercel-nextjs).
+
+Under the app directory, you will find 7 folders, each corresponding to a workflow API except the `-call-qstash`. In each of these folders, you will find the `route.ts` file which defines the endpoint.
+
+The user calls `-call-qstash` with information about which endpoint is to be called in the body. `-call-qstash` publishes a message to QStash. QStash then calls the specified endpoint.
+
+![flow-diagram](../imgs/flow-diagram.png)
+
+## Deploying the Project at Vercel
+
+To deploy the project, you can simply use the `Deploy with Vercel` button at the top of this README. If you want to edit the project and deploy it, you can read the rest of this section.
+
+To deploy the project at vercel and try the endpoints, you should start with setting up the project by running:
+
+```
+vercel
+```
+
+Next, you shoud go to vercel.com, find your project and add `QSTASH_TOKEN`, to the project as environment variables. You can find this env variables from the [Upstash Console](https://console.upstash.com/qstash). To learn more about other env variables and their use in the context of Upstash Workflow, you can read [the Secure your Endpoint in our documentation](https://upstash.com/docs/qstash/workflow/howto/security#using-qstashs-built-in-request-verification-recommended).
+
+Once you add the env variables, you can deploy the project with:
+
+```
+vercel --prod
+```
+
+Note that the project won't work in preview. It should be deployed to production like above. This is because preview requires authentication.
+
+Once you have the app deployed, you can go to the deployment and call the endpoints using the form on the page.
+
+You can observe the logs at [Upstash console under the Worfklow tab](https://console.upstash.com/qstash?tab=workflow) or vercel.com to see your workflow operate.
+
+## Local Development
+
+For local development setup, refer to the [Local Development section in our documentation](https://upstash.com/docs/qstash/workflow/howto/local-development).

examples/ci/app/ci/ci.test.ts

@@ -0,0 +1,17 @@
+import { test, describe } from "bun:test"
+import { TEST_ROUTES } from "./constants";
+import { initiateTest } from "./utils";
+
+describe("workflow integration tests", () => {
+  TEST_ROUTES.forEach(testConfig => {
+    test(
+      testConfig.route,
+      async () => {
+        await initiateTest(testConfig.route, testConfig.waitForSeconds)
+      },
+      {
+        timeout: (testConfig.waitForSeconds + 8) * 1000
+      }
+    )
+  });
+})

examples/ci/app/ci/constants.ts

@@ -0,0 +1,71 @@
+import { TestConfig } from "./types"
+
+export const CI_RANDOM_ID_HEADER = "Ci-Test-Id"
+export const CI_ROUTE_HEADER = `Ci-Test-Route`
+
+export const BASE_URL = process.env.VERCEL_URL
+  ? `https://${process.env.VERCEL_URL}`
+  : process.env.UPSTASH_WORKFLOW_URL
+    ? process.env.UPSTASH_WORKFLOW_URL
+    : "http://localhost:3001"
+
+export const TEST_ROUTE_PREFIX = `${BASE_URL}/test-routes`
+
+export const TEST_ROUTES: Pick<TestConfig, "route" | "waitForSeconds">[] = [
+  {
+    // tests a very basic endpoint with 2 context run statements
+    // payload has unicode chars
+    route: "path",
+    waitForSeconds: 1
+  },
+  {
+    // runs sleep and sleepUntil. checks if sufficient time passed between
+    // steps
+    route: "sleep",
+    waitForSeconds: 8
+  },
+  {
+    // runs sleep parallel with other steps
+    route: "sleepWithoutAwait",
+    waitForSeconds: 18
+  },
+  {
+    // checks auth
+    route: "auth",
+    waitForSeconds: 1
+  },
+  {
+    // checks auth failing
+    route: "auth-fail",
+    waitForSeconds: 0
+  },
+  {
+    // checks context.call (sucess and fail case)
+    route: "call/workflow",
+    waitForSeconds: 24
+  },
+  {
+    // checks context.run with async and sync route methods
+    route: "async-sync-run",
+    waitForSeconds: 1
+  },
+  {
+    // checks failureFunction
+    route: "failureFunction",
+    waitForSeconds: 1
+  },
+  {
+    // checks failureFunction with retries: 1
+    route: "failureFunction-retry",
+    waitForSeconds: 14
+  },
+  {
+    // checks failureUrl
+    route: "failureUrl/workflow",
+    waitForSeconds: 1
+  },
+  {
+    route: "wait-for-event/workflow",
+    waitForSeconds: 20
+  }
+]

examples/ci/app/ci/types.ts

@@ -0,0 +1,44 @@
+export type TestConfig<TPayload = unknown> = {
+  /**
+   * path of the workflow endpoint
+   * 
+   * will also be part of the redis key
+   */
+  route: string,
+  /**
+   * payload to send in the initial request
+   */
+  payload: TPayload,
+  /**
+   * headers of the request
+   */
+  headers?: Record<string, string>,
+  /**
+   * duration the test between initiating the workflow and checking the result
+   */
+  waitForSeconds: number
+  /**
+   * number of times the endpoint is to be called in this test
+   */
+  expectedCallCount: number
+  /**
+   * expected result in the Redis
+   */
+  expectedResult: string
+}
+
+export type RedisResult = {
+  /**
+   * observed call count
+   */
+  callCount: number
+  /**
+   * result written to redis
+   */
+  result: string
+  /**
+   * a randomly generated string which is generated
+   * in each test and sent as a header.
+   */
+  randomTestId: string
+}

examples/ci/app/ci/upstash/qstash.ts

@@ -0,0 +1,51 @@
+import { Client, QstashError } from "@upstash/qstash"
+import { TEST_ROUTE_PREFIX, CI_RANDOM_ID_HEADER, CI_ROUTE_HEADER } from "../constants"
+import { TestConfig } from "../types"
+
+const client = new Client({ baseUrl: process.env.QSTASH_URL, token: process.env.QSTASH_TOKEN! })
+
+/**
+ * starts a workflow run given the config
+ * 
+ * @param testConfig 
+ * @param randomTestId 
+ * @returns 
+ */
+export const startWorkflow = async (
+  testConfig: Pick<TestConfig, "route" | "headers" | "payload">,
+  randomTestId: string
+): Promise<{ messageId: string }> => {
+  const result = await client.publishJSON({
+    url: `${TEST_ROUTE_PREFIX}/${testConfig.route}`,
+    headers: {
+      [ CI_RANDOM_ID_HEADER ]: randomTestId,
+      [ CI_ROUTE_HEADER ]: testConfig.route,
+      ...testConfig.headers
+    },
+    body: testConfig.payload
+  })
+  return result
+}
+
+/**
+ * throws error if workflow hasn't started
+ * 
+ * @param messageId 
+ * @returns 
+ */
+export const checkWorkflowStart = async (messageId: string) => {
+
+  try {
+    const { events } = await client.events({ filter: { messageId }})
+    const startMessageDelivered = Boolean(events.find(event => event.state === "DELIVERED"))
+    if (!startMessageDelivered) {
+      await client.messages.delete(messageId)
+      throw new Error(`Couldn't verify that workflow has begun. Number of events: ${events.length}`)
+    }
+  } catch (error) {
+    if (error instanceof QstashError && error.message.includes(`message ${messageId} not found`)) {
+      return
+    }
+    throw error
+  }
+}