diff --git a/README.md b/README.md index c88fcdefc..b50083c63 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,6 @@ The command starts a local development server and opens a browser window. > ๐Ÿ’ก **Tip:** After running `npm install`, use `npm start` to preview changes live at `http://localhost:3000/`. - ## Running Vale Locally for Documentation Linting To help maintain consistency in our documentation, we use Vale, a syntax-aware linter that checks for spelling, grammar, and style issues. diff --git a/STYLE.md b/STYLE.md index cfacb92da..3c80efe43 100644 --- a/STYLE.md +++ b/STYLE.md @@ -1,6 +1,6 @@ # Style Guidance -Keploy documentation generally follows the [Google Developer Documentation Style Guide](https://developers.google.com/style). +Keploy documentation generally follows the [Google Developer Documentation Style Guide](https://developers.google.com/style). When the Google guide does not address a specific topic, we defer to the [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/). @@ -17,10 +17,12 @@ The following are Keploy-specific rules that override or expand on the Google an Some of Keployโ€™s core terms may also exist as generic terms in software or technical contexts. To reduce confusion, **always capitalize Keploy-specific terms** when referring to features or platform components. Generic usage should be lowercase and used sparingly. -โœ… **Correct:** +โœ… **Correct:** + > โ€œNext, Normalise the Test case on the Test run details page.โ€ -โŒ **Incorrect:** +โŒ **Incorrect:** + > โ€œNext, normalise the test case on the test run details.โ€ --- @@ -30,9 +32,11 @@ To reduce confusion, **always capitalize Keploy-specific terms** when referring Use **sentence case** for all titles and headings. This means only the **first word** and **proper nouns** are capitalized. โœ… Correct: + > How to get started with Keploy โŒ Incorrect: + > How To Get Started With Keploy --- @@ -43,10 +47,12 @@ Use **infinitive verb forms** (e.g., "to install", "to create", "to configure") This improves searchability and aligns with common SEO practices. โœ… Correct: + > Install Keploy > Create test cases โŒ Incorrect: + > Installing Keploy > Creating test cases @@ -55,13 +61,15 @@ This improves searchability and aligns with common SEO practices. ### ๐Ÿงฎ En Dashes in Ranges Use **en dashes (โ€“)** to indicate numeric ranges. Do **not** mix styles or use hyphens inconsistently. -You may also use words like *from*, *to*, or *through* โ€” but be consistent throughout the doc. +You may also use words like _from_, _to_, or _through_ โ€” but be consistent throughout the doc. โœ… Correct: + - 5โ€“10 GB - 5 to 10 GB โŒ Incorrect: + - from 5-10 GB - 5โ€“10 GB and 10 to 20 MB (mixed style) @@ -72,9 +80,11 @@ You may also use words like *from*, *to*, or *through* โ€” but be consistent thr Use **active voice** instead of passive voice to improve clarity and readability. โœ… Correct: + > Keploy records the API calls and generates test cases. โŒ Incorrect: + > The API calls are recorded and test cases are generated by Keploy. --- @@ -82,14 +92,17 @@ Use **active voice** instead of passive voice to improve clarity and readability ### ๐ŸŒ Write for Global Readability Use clear, simple, and **inclusive language**: + - Avoid jargon or unexplained acronyms. - Provide context for technical terms. - Prefer short, direct sentences. โœ… Better: + > After installing Go, use the following command to run Keploy. โŒ Confusing: + > Assuming GOPATH is set and your binaries are globally linked, execute Keploy. --- @@ -98,10 +111,10 @@ Use clear, simple, and **inclusive language**: - Wrap inline code using backticks: \`like this\` - Use triple backticks for multi-line code blocks: - \`\`\`bash - npm install - npm run serve - \`\`\` + \`\`\`bash + npm install + npm run serve + \`\`\` - Add comments in code examples where needed for clarity. --- @@ -118,4 +131,3 @@ Use clear, simple, and **inclusive language**: --- > โœจ _Consistency leads to clarity. Letโ€™s keep Keploy documentation clean, helpful, and easy to follow._ - diff --git a/versioned_docs/version-3.0.0/quickstart/samples-go-fiber-s3.md b/versioned_docs/version-3.0.0/quickstart/samples-go-fiber-s3.md new file mode 100644 index 000000000..ea36abc5d --- /dev/null +++ b/versioned_docs/version-3.0.0/quickstart/samples-go-fiber-s3.md @@ -0,0 +1,310 @@ +--- +id: samples-s3-keploy +title: Sample S3 File Manager App (Golang) +sidebar_label: Fiber + S3 +description: The following sample app showcases how to use fiber framework with AWS S3 and the Keploy Platform. +tags: + - go + - quickstart + - samples + - examples + - tutorial + - s3 + - fiber-framework +keyword: + - Fiber Framework + - AWS S3 Mock + - Golang + - API Test generator + - Auto Testcase generation +--- + +## Introduction + +๐Ÿช„ Dive into the world of cloud storage management and see how seamlessly Keploy integrates with Fiber and AWS S3! Buckle up, it's gonna be a fun ride! ๐ŸŽข + +import InstallationGuide from '../concepts/installation.md' + + + +## Get Started! ๐ŸŽฌ + +## Clone the sample S3 file manager app ๐Ÿงช + +```bash +git clone https://github.com/keploy/samples-go.git && cd samples-go/S3-Keploy +go mod download +``` + +## Prerequisites ๐Ÿ”ง + +Before we start, make sure you have: + +1. [Go](https://go.dev/doc/install) installed +2. [AWS Access Key and Secret Key](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/welcome.html) +3. AWS credentials configured + +### Setting AWS Credentials ๐Ÿ”‘ + +Go to your home directory and create `.aws` folder: + +```bash +mkdir ~/.aws +``` + +Create a `credentials` file inside `.aws` folder: + +```bash +touch ~/.aws/credentials +``` + +Open `credentials` in any text editor and add the following: + +``` +[default] +aws_access_key_id = +aws_secret_access_key = +``` + +## Running the Application ๐Ÿš€ + +We'll be running our sample application locally with AWS S3 integration. Ready? Let's get the party started! ๐ŸŽ‰ + +If you are using WSL on Windows then use below to start wsl in the user's home directory: + +```bash +wsl ~ +``` + +### Recording Test Cases ๐Ÿ“ผ + +Ready, set, record! Here's how: + +```bash +sudo -E env PATH="$PATH" keploy record -c 'go run .' +``` + +Keep an eye out for the `-c` flag! It's the command charm to run the app. Whether you're using `go run .` or `go run main.go`, it's your call. + +If you're seeing logs that resemble the ones below, you're on the right track: + + Keploy Record Test case locally + +๐Ÿ”ฅ Challenge time! Generate some test cases. How? Just **make some API calls**. Postman, Hoppscotch or even curl - take your pick! + +Let's manage some S3 buckets and files: + +#### Create a new bucket + +```bash +curl --request POST \ + --url http://localhost:3000/create \ + --header 'content-type: application/json' \ + --data '{ + "name": "my-test-bucket-keploy-2024" + }' +``` + +Here's a peek of what you get: + +```json +{ + "msg": "my-test-bucket-keploy-2024 Bucket created successfully!" +} +``` + +#### List all buckets + +```bash +curl --request GET \ + --url http://localhost:3000/list +``` + +Response: + +```json +{ + "buckets": ["my-test-bucket-keploy-2024", "another-bucket-name"] +} +``` + +๐ŸŽ‰ Woohoo! With simple API calls, you've crafted test cases with mocks! Dive into the Keploy directory and feast your eyes on the newly minted `test-1.yml` and `mocks.yml` + +```yaml +version: api.keploy.io/v1beta2 +kind: Http +name: test-1 +spec: + metadata: {} + req: + method: POST + proto_major: 1 + proto_minor: 1 + url: http://localhost:3000/create + header: + Accept: "*/*" + Content-Length: "35" + Content-Type: application/json + Host: localhost:3000 + User-Agent: curl/7.77.0 + body: |- + { + "name": "my-test-bucket-keploy-2024" + } + body_type: "" + resp: + status_code: 200 + header: + Content-Length: "55" + Content-Type: application/json; charset=utf-8 + Date: Wed, 18 Jun 2025 10:15:47 GMT + body: '{"msg":"my-test-bucket-keploy-2024 Bucket created successfully!"}' + body_type: "" + status_message: "" + proto_major: 0 + proto_minor: 0 + objects: [] + assertions: + noise: + - header.Date + created: 1718705747 +``` + +This is how the generated **mock.yml** will look like: + +```yaml +version: api.keploy.io/v1beta2 +kind: Http +name: mocks +spec: + metadata: + operation: "CreateBucket" + requests: + - header: + Authorization: "AWS4-HMAC-SHA256 Credential=..." + Content-Type: "application/x-amz-json-1.0" + X-Amz-Target: "DynamoDB_20120810.CreateBucket" + body: '{"BucketName":"my-test-bucket-keploy-2024","Region":"ap-south-1"}' + method: POST + url: "https://s3.ap-south-1.amazonaws.com/" + responses: + - status_code: 200 + header: + Content-Type: "application/x-amz-json-1.0" + Date: "Wed, 18 Jun 2025 10:15:47 GMT" + body: '{"BucketLocation":"ap-south-1"}' + created: 1718705747 +``` + +_Time to perform more API magic!_ + +#### Upload a file to bucket + +```bash +curl --request POST \ + --url "http://localhost:3000/upload?bucket=my-test-bucket-keploy-2024" \ + --form 'filename=@apple.png' +``` + +#### Get all objects in a bucket + +```bash +curl --request GET \ + --url "http://localhost:3000/getallobjects?bucket=my-test-bucket-keploy-2024" +``` + +#### Replace/Update a file + +```bash +curl --request PUT \ + --url "http://localhost:3000/replacefile?bucket=my-test-bucket-keploy-2024" \ + --form 'filename=@mango.png' +``` + +#### Delete all objects in a bucket + +```bash +curl --request DELETE \ + --url "http://localhost:3000/deleteallobjects?bucket=my-test-bucket-keploy-2024" +``` + +#### Delete a bucket + +```bash +curl --request DELETE \ + --url "http://localhost:3000/delete?bucket=my-test-bucket-keploy-2024" +``` + +Spotted the new test and mock files in your project? High five! ๐Ÿ™Œ + +Sample Keploy Test case and Mock for Fiber S3 + +### Running Tests ๐Ÿƒโ€โ™€๏ธ + +Time to put things to the test ๐Ÿงช + +```bash +sudo -E env PATH=$PATH keploy test -c "go run ." --delay 20 +``` + +> The `--delay` flag? Oh, that's just giving your app a little breather (in seconds) before the test cases come knocking. This is especially important for S3 operations as they might need some time to propagate across AWS infrastructure. + +Your results should be looking all _snazzy_, like this: + +Sample Keploy Test Result Fiber S3 + +Did you spot any AWS-specific fields showing differences? That's totally normal with cloud services! โ˜๏ธ + +Worry not, just add the ever-changing fields (like AWS **signatures**, **timestamps**, or **request IDs**) to the **noise parameter** to **dodge those assertions**. + +> Pro tip: Add `header.Authorization`, `header.X-Amz-Date`, `header.X-Amz-Request-Id` to noise in `test-x.yaml` if needed. + +Adding Noise to Test case Fiber S3 + +Run that `keploy test` command once more and watch as everything falls into place with all tests passing! ๐ŸŒŸ + +Final thoughts? Dive deeper! Try different API calls, tweak the S3 response in the `mocks.yml`, or fiddle with the request or response in `test-x.yml`. Run the tests again and see the magic unfold! โœจ๐Ÿ‘ฉโ€๐Ÿ’ป๐Ÿ‘จโ€๐Ÿ’ปโœจ + +## Available API Endpoints ๐Ÿ›ฃ๏ธ + +Here's a quick reference of all available endpoints: + +- `GET /list` - Get all bucket names +- `GET /getallobjects?bucket=` - Get all objects in a specific bucket +- `POST /create` - Create a new bucket +- `POST /upload?bucket=` - Upload a file to a bucket +- `PUT /replacefile?bucket=` - Replace/update an existing file +- `DELETE /delete?bucket=` - Delete a bucket +- `DELETE /deleteallobjects?bucket=` - Delete all objects in a bucket + +## Troubleshooting ๐Ÿ”ง + +**AWS Credentials Issues:** + +- Make sure your AWS credentials are properly configured in `~/.aws/credentials` +- Ensure your IAM user has appropriate S3 permissions +- Check that the region is set correctly (default: `ap-south-1`) + +**Bucket Name Issues:** + +- S3 bucket names must be globally unique +- Use lowercase letters, numbers, and hyphens only +- Avoid dots in bucket names + +**File Upload Issues:** + +- Make sure the file exists in your current directory +- Check file permissions +- Ensure the bucket exists before uploading + +## Wrapping it up ๐ŸŽ‰ + +Congrats on the journey so far! You've seen Keploy's power with Fiber and AWS S3, flexed your coding muscles, and had a bit of fun too! Now, go out there and keep exploring, innovating, and creating! Remember, with the right tools and a sprinkle of fun, anything's possible. ๐Ÿ˜Š๐Ÿš€ + +Happy coding! โœจ๐Ÿ‘ฉโ€๐Ÿ’ป๐Ÿ‘จโ€๐Ÿ’ปโœจ + +Hope this helps you out, if you still have any questions, reach out to us. + +import GetSupport from '../concepts/support.md' + + diff --git a/versioned_sidebars/version-3.0.0-sidebars.json b/versioned_sidebars/version-3.0.0-sidebars.json index 6a81c03ef..16f17f141 100644 --- a/versioned_sidebars/version-3.0.0-sidebars.json +++ b/versioned_sidebars/version-3.0.0-sidebars.json @@ -108,7 +108,8 @@ "quickstart/samples-redis", "quickstart/samples-mux", "quickstart/samples-mysql", - "quickstart/samples-fasthttp" + "quickstart/samples-fasthttp", + "quickstart/samples-s3-keploy" ] }, {