PRD – Testing Vercel API “Create Deployment”
Why?
We want to make sure that the “Create Deployment” API (in vercel) works properly.
That means:
● It should succeed when we give it correct input.
● It should fail with the right error when we give it wrong input.
● It should behave consistently for unusual cases.
The goal is to validate the functionality and reliability of the Create Deployment API
provided by Vercel. This API is used to create new deployments (live versions of a
project).
How does this work?
● Needs an API key (like a secret password).
● Takes input in two main ways:
1. Git deployment → you give repo info (like GitHub).
2. File deployment → you send actual files (HTML, JS, etc.).
● If it works, you get back a receipt: Deployment ID, website URL, and status.
VALID TEST CASES:
1. Deploy using a valid Git repository
What it means:
You connect your GitHub repo to Vercel and ask the API to deploy from it.
● Example: Repo = [Link]/team/project , branch = main.
Expected outcome:
● Deployment is created successfully.
● API returns deployment ID, preview/live URL, and status.
Pros:
● Automated and repeatable (always builds from your repo).
● Keeps deployments in sync with the codebase.
Cons:
● Fails if repo permissions are wrong.
● Requires repo setup before first deployment.
2. Deploy by uploading valid project files
What it means:
Instead of Git, you upload files directly (HTML, JS, CSS, etc.).
● Example: Send [Link], [Link], and [Link].
Expected outcome:
● Deployment is created and URL is returned.
● The website shows exactly those files.
Pros:
● Quick for testing or one-off projects.
● Doesn’t require Git repo.
Cons:
● Harder to maintain (you must re-upload each time).
● Not suitable for large/complex projects.
3. Deploy with modified build settings
What it means:
You customize how Vercel builds the project — for example, choosing a different build
command or output folder.
Expected outcome:
● Deployment is created using new settings.
● Build logs show custom commands being used.
Pros:
● Flexibility for non-standard projects.
● Works for advanced setups.
Cons:
● Misconfigured settings can break the build.
● Adds complexity compared to default setup.
4. Deploy using ‘forceNew=1’ (create fresh deployment even if no
changes)
What it means:
Normally, if nothing has changed, Vercel reuses the last deployment. With forceNew=1,
you force a brand-new one.
Expected outcome:
● Deployment is created anyway.
● New deployment ID and URL returned.
Pros:
● Useful for testing or debugging.
● Guarantees a clean, fresh build.
Cons:
● Uses more build time and resources.
● Creates multiple identical deployments, which can clutter history.
INVALID TEST CASES:
1. Missing API key
Expected outcome: Request is denied with error “Authentication required”.
2. Invalid API key
Expected outcome: Request is denied with error “Invalid authentication token”.
3. No deployment source provided
Expected outcome: Request fails with error “No source provided”.
4. Empty file list
Expected outcome: Request fails with error “No files provided”.
5. File path given but no data
Expected outcome: Request fails with error indicating missing file content.
6. Invalid Git repository or branch
Expected outcome: Request fails with error “Repository or branch not found”.
7. Too many environment variables (>100)
Expected outcome: Request fails with error “Too many environment variables”.
8. Invalid characters in environment variable keys
Expected outcome: Request fails with error “Invalid key format”.
9. Environment variable key too long
Expected outcome: Request fails with error about exceeding max length.
10. Environment variable value too long
Expected outcome: Request fails with error about exceeding max length.
11. Nonexistent secret referenced
Expected outcome: Request fails with error “Secret not found”.
12. Secret without access permissions
Expected outcome: Request fails with error “Access denied”
13. Invalid deployment target
Expected outcome: Request fails with error “Invalid target”.
Recommended-
Deploy using a valid Git repository (i.e., ask the Vercel API to deploy code directly from a
Git repo and a specific branch).
1. It mirrors real use
Most teams deploy from Git (GitHub/GitLab/Bitbucket). If this works, the common
real-world flow works.
2. It covers many things at once
A Git deployment touches authentication, permissions, the API, repo access, build
detection, build execution, and the final live site. So one Git test checks a lot of
important parts.
3. It validates the build pipeline end-to-end
When you deploy from Git you actually run the build steps (install, build, output).
That catches configuration or dependency issues early.
4. It’s repeatable and automatable
You can run the same test as part of CI or an automated test suite, so it’s easy to
repeat and verify after fixes.
5. It surfaces integration issues
Problems like repo access, wrong branch, or missing build commands show up here
fixing them prevents failures in other deployment modes too.
Steps in Order:
1. User → Vercel API: Send request to create a deployment, including project info + Git
repo + branch.
2. Vercel API → Git Provider: Ask for the code of that branch.
3. Git Provider → Vercel API: Send back the code (commit files, metadata).
4. Vercel API → Build System: Pass the code along with build instructions.
5. Build System → Vercel API: Report build started.
6. Build System (internal): Install dependencies, run build commands, generate
output.
7. Build System → Vercel API: Report build finished (success or failure).
8. Vercel API → Hosting: Upload final build output to hosting infrastructure.
9. Hosting → Vercel API: Confirm deployment is live.
10.Vercel API → User: Send back deployment ID + live URL.
11.User → Hosting (via browser): Open the live URL to see the deployed site.
12.Hosting → User: Serve the live site.
