|
1 | | -# Shirt Shop Flags SDK Example |
| 1 | +# 🐛 Bugster - Automated Testing for Next.js |
2 | 2 |
|
3 | | -This example uses the [Flags SDK](https://flags-sdk.dev) along with the [Flags Explorer](https://vercel.com/docs/workflow-collaboration/feature-flags/using-vercel-toolbar) and `@vercel/analytics`. |
| 3 | +**Generate and run comprehensive tests for your Next.js applications with AI-powered automation.** |
4 | 4 |
|
5 | | -## Demo |
| 5 | +This is a demo shirt shop built with Next.js to showcase how Bugster can automatically generate and run tests for your web applications. Follow this step-by-step guide to try it from scratch! |
6 | 6 |
|
7 | | -[https://shirt-shop.labs.vercel.dev/](https://shirt-shop.labs.vercel.dev/) |
| 7 | +## 🚀 Phase 1: Try Bugster Locally |
8 | 8 |
|
9 | | -## How it works |
| 9 | +### Step 1: Install Bugster CLI |
10 | 10 |
|
11 | | -This demo uses two feature flags defined in code control the visibility of two banners on the page. |
12 | | -Both flags are configured to show/hide each banner 50% of the time. |
| 11 | +#### macOS/Linux |
13 | 12 |
|
14 | | -Once you visit the page, you can see a variation of both/one/none of the banners. |
15 | | -Since this example is using a stable id to identify users, you will see the same variation all the time. |
| 13 | +```bash |
| 14 | +curl -sSL https://github.com/Bugsterapp/bugster-cli/releases/latest/download/install.sh | bash -s -- -y |
| 15 | +``` |
16 | 16 |
|
17 | | -To test different variations, you can use the Dev Tools at the bottom to reset the stable id and reload the page. |
18 | | -This allows you to test different variations of the banners. |
| 17 | +#### Verify Installation |
19 | 18 |
|
20 | | -This templates also tracks analytics events in Vercel Analytics. |
| 19 | +```bash |
| 20 | +bugster --version |
| 21 | +``` |
21 | 22 |
|
22 | | -If you deployed your own instance of this example you can also use the [Flags Explorer](https://vercel.com/docs/workflow-collaboration/feature-flags/using-vercel-toolbar) to test different variations by creating overrides. |
| 23 | +_If the command doesn't work, open a new terminal to load the new command._ |
23 | 24 |
|
24 | | -## Deploy this template |
| 25 | +### Step 2: Clone and Run the Example |
25 | 26 |
|
26 | | -[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fflags%2Ftree%2Fmain%2Fexamples%2Fshirt-shop&env=FLAGS_SECRET&envDescription=The+FLAGS_SECRET+will+be+used+by+the+Flags+Explorer+to+securely+overwrite+feature+flags.+Must+be+32+random+bytes%2C+base64-encoded.+Use+the+generated+value+or+set+your+own.&envLink=https%3A%2F%2Fvercel.com%2Fdocs%2Fworkflow-collaboration%2Ffeature-flags%2Fsupporting-feature-flags%23flags_secret-environment-variable&project-name=shirt-shop-flags-sdk-example&repository-name=shirt-shop-flags-sdk-example) |
| 27 | +```bash |
| 28 | +git clone https://github.com/Bugsterapp/bugster-nextjs-example.git |
| 29 | +cd bugster-nextjs-example |
| 30 | +npm install --legacy-peer-deps |
| 31 | +npm run dev |
| 32 | +``` |
27 | 33 |
|
28 | | -### Step 1: Link the project |
| 34 | +Your demo shirt shop should now be running at `http://localhost:3000` |
29 | 35 |
|
30 | | -In order to use the Flags Explorer, you need to link the project on your local machine. |
| 36 | +Open your editor: |
31 | 37 |
|
32 | 38 | ```bash |
33 | | -vercel link |
| 39 | +# With Cursor |
| 40 | +cursor . |
| 41 | +# or with VS Code |
| 42 | +code . |
34 | 43 | ``` |
35 | 44 |
|
36 | | -Select the project from the list you just deployed. |
| 45 | +### Step 3: Try Bugster in Action |
| 46 | + |
| 47 | +#### Initialize Bugster |
| 48 | + |
| 49 | +```bash |
| 50 | +bugster init |
| 51 | +# or |
| 52 | +bugster init --project-name bugster-nextjs-example --url http://localhost:3000 --no-credentials |
| 53 | +``` |
37 | 54 |
|
38 | | -### Step 2: Pull all environment variables |
| 55 | +#### Generate Tests |
39 | 56 |
|
40 | | -This allows the Flags SDK and the Flags Explorer to work correctly, by getting additional metadata. |
| 57 | +This repo already has some tests at `.bugster/tests` generated with the `bugster generate` command but you can generate more if you want: |
41 | 58 |
|
42 | 59 | ```bash |
43 | | -vercel env pull |
| 60 | +bugster generate |
44 | 61 | ``` |
45 | 62 |
|
46 | | -### Step 3: Install dependencies |
| 63 | +_Bugster will analyze your Next.js app and automatically generate comprehensive tests_ |
| 64 | + |
| 65 | +#### Run Generated Tests |
47 | 66 |
|
48 | 67 | ```bash |
49 | | -npm install |
| 68 | +bugster run |
50 | 69 | ``` |
51 | 70 |
|
52 | | -### Step 4: Run the project |
| 71 | +_Watch as Bugster runs the tests it generated for your application_ |
| 72 | + |
| 73 | +## 🚀 Phase 2: Deploy to Production with GitHub Integration |
| 74 | + |
| 75 | +Ready to see Bugster in production? Let's deploy your own version and set up GitHub integration for automatic testing on every deployment. |
| 76 | + |
| 77 | +### Step 1: Create Your Own Repository |
| 78 | + |
| 79 | +After testing locally, create your own repository with this code: |
| 80 | + |
| 81 | +**Create a new repository** |
| 82 | + |
| 83 | +1. Create a new repository on GitHub |
| 84 | +2. From your local directory, update the remote: |
53 | 85 |
|
54 | 86 | ```bash |
55 | | -npm run dev |
| 87 | +git add . |
| 88 | +git commit -m "Add Bugster Integration" |
| 89 | +git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git |
| 90 | +git push -u origin main |
56 | 91 | ``` |
| 92 | + |
| 93 | +### Step 2: Deploy to Vercel |
| 94 | + |
| 95 | +1. Go to [Vercel Dashboard](https://vercel.com/dashboard) |
| 96 | +2. Click "New Project" |
| 97 | +3. Import **your repository** (the one you just created) |
| 98 | +4. Deploy with default settings |
| 99 | + |
| 100 | +### Step 3: Set Up GitHub Integration |
| 101 | + |
| 102 | +Connect Bugster with GitHub to automatically run tests on every Vercel Preview deployment. |
| 103 | + |
| 104 | +#### Enable Vercel Protection Bypass |
| 105 | + |
| 106 | +According to the best secure practices, Vercel protects your Vercel Previews, so this step is essential to allow Bugster access to your Previews |
| 107 | + |
| 108 | +1. In [Vercel Dashboard](https://vercel.com/dashboard), go to your project |
| 109 | +2. Navigate to **Settings** → **Deployment Protection** |
| 110 | +3. Find "Protection Bypass for Automation" and click **"Add Secret"** |
| 111 | +4. Save (you can leave the value empty - it will be generated automatically) |
| 112 | +5. Copy the generated secret |
| 113 | + |
| 114 | +#### Configure Bugster |
| 115 | + |
| 116 | +Add the secret to `.bugster/config.yaml`: |
| 117 | + |
| 118 | +```yaml |
| 119 | +"x-vercel-protection-bypass": "your-secret-here" |
| 120 | +``` |
| 121 | +
|
| 122 | +Push these changes: |
| 123 | +
|
| 124 | +```bash |
| 125 | +git add . |
| 126 | +git commit -m "Add Protection Vercel Bypass Automation token to bugster config.yaml" |
| 127 | +git push |
| 128 | +``` |
| 129 | + |
| 130 | +#### Connect Repository |
| 131 | + |
| 132 | +1. Visit [Bugster Dashboard](https://gui.bugster.dev/dashboard) |
| 133 | +2. Connect your GitHub repository |
| 134 | +3. Test the integration by creating a PR |
| 135 | + |
| 136 | +Create a Pull Request and watch Bugster automatically test your Vercel Preview! 🎉 |
| 137 | + |
| 138 | +## 🤝 Contributing |
| 139 | + |
| 140 | +Found a bug or want to improve the demo? PRs welcome! |
| 141 | + |
| 142 | +## 📚 Learn More |
| 143 | + |
| 144 | +- [Bugster Documentation](https://docs.bugster.dev) |
| 145 | +- [Next.js Documentation](https://nextjs.org/docs) |
| 146 | +- [Vercel Platform](https://vercel.com/new) |
| 147 | + |
| 148 | +--- |
| 149 | + |
| 150 | +**Made with ❤️ by the Bugster team** |
0 commit comments