Before you start

You will need:

An Alva user with permission to manage the Coding Test Library
A GitHub account that can access the private template repository Alva creates for your test (anyone who will maintain the test needs access too)

If you want a fully managed setup with automated functional tests and a detailed code review scorecard, our standard tests in the library are a great starting point.

You can also Duplicate a standard test and adjust it instead of starting from scratch:

In the Coding Test Library, open the test you want to copy.
Click Duplicate in the top right.

💡Note: Coding tests you create are only visible to your own Alva organisation. They are not shared with other Alva customers.

Step 1 – Open the create form

Go to Assessments → Coding tests in the side menu.
Click Create coding test in the top-right corner of the Coding Test Library.

The Create coding test modal opens.

Step 2 – Fill in the basic information

The first section of the form captures the essentials of your test.

Name (required)

The display name of the test.
Shown in the library, on the candidate invitation, and on the scorecard.
Keep it descriptive and short (e.g. Lookup Service – Level 1 or Internal Tooling Frontend).

Category (required)

The profile the test is aimed at: Backend, Frontend, Fullstack, Mobile, Embedded, Data, Cybersecurity, Gaming, DevOps, or Machine learning.
The category controls which jobs the test is recommended for.

Tech stack selector

For most custom tests we recommend leaving this unticked.

When ticked, candidates pick a framework from Alva’s standard list (e.g. Spring Boot, NestJS, Django, FastAPI, Express.js). Alva then overlays a generic Alva-managed boilerplate for that framework - not the contents of your template repository.

Only tick this if:

Your task is genuinely framework-agnostic, and
Alva’s generic scaffolds are an acceptable starting point.

Otherwise, leave it unticked and ship your own boilerplate in the GitHub template repository (Step 5).

Template repository

Alva automatically generates a private GitHub template repository for the test.
You’ll edit this repository in Step 5 to add the README, starter code, automated tests, and configuration candidates need.

Description for the hiring team

Internal-only notes shown on the test’s detail page.
Use this to explain what the test evaluates, how to interpret results, and any hand-off instructions.
Candidates do not see this field - candidate instructions go in the repository README.

Step 3 – Set the expected time effort

Tell Alva how long the test should take a candidate at each seniority level. These values are used to set candidate deadlines and to display the time-on-task estimate in the library.

Junior, Mid-level, Senior: enter hours and minutes for each level you want to support
Leave a level blank if the test is not intended for that seniority

Empty levels will show as “–” in the library. If a coding test is missing a time estimate for a seniority level, Architect won’t be able to recommend that test for jobs where that seniority level is selected.

Step 4 – Add tags and the code review scorecard

Code review scorecard

The scorecard is the rubric our AI uses to perform a structured code review of each submission.

Each requirement is graded 0 (does not meet), 1 (partially meets), or 2 (meets)
Requirement scores roll up into an overall AI code review score on the candidate’s scorecard

For every requirement:

Requirement: a short title (e.g. Error handling, Idempotency of POST endpoint, State management in the form)
Scoring criteria: concrete, unambiguous instructions the AI should follow when grading
- Describe what a 0, 1, and 2 look like
- Mention specific files or behaviours when relevant
- Write in English for the most reliable results

You can add multiple requirements with + Add Requirement, reorder them with the arrows on the right , and delete them with the trash icon .

If you skip the scorecard entirely, the AI code review step will be skipped for that test - automated functional tests and the AI code quality score still run.

Step 5 – Create the test and edit the GitHub repository

Click Create coding test at the bottom of the modal. Alva will:

Create the coding test in your library.
Generate a private GitHub repository linked to it.
Open the test’s detail page. You can still edit any section by clicking Edit

Open the GitHub repository () from the Template repository link in the Basic information section.

The freshly generated repository contains a minimal scaffold:

README.md (currently empty) - this is what the candidate reads first. Put the task description, requirements, run instructions, and submission steps here.
.github/workflows/ - contains a setup-boilerplate workflow used by Alva’s tech stack selector. Leave this folder in place; do not delete it.

From here, treat the repository like any other GitHub template. Typical things to add:

The full task description and acceptance criteria in README.md
A working project skeleton in the language/framework you chose
Example data or fixtures the candidate should not need to recreate
An automated test suite the candidate’s solution must pass (these become the automated functional tests in the candidate score)

When writing the candidate-facing README, start with a clear problem statement and make the acceptance criteria unambiguous.

When a candidate starts the test, Alva generates a private candidate repository from this template (a fresh repo with its own git history), optionally overlays the boilerplate they selected, and invites the candidate as a collaborator.

Wiring up the automated functional test score (advanced)

Custom tests do not publish an automated test score by default. For the score to appear on the candidate’s scorecard, the template repository must:

Contain a GitHub Actions workflow file with one of these exact names:
- publish-test-results.yml
- tests.yml
- healthcheck.yml
Any other filename will be ignored.
Run the test suite on every push or pull request.
POST the results to Alva’s webhook using the repository variable AUTO_SCORE_WEBHOOK_URL and the secret AUTO_SCORE_TOKEN.

Alva injects these automatically into the candidate repository when it is generated - you don’t manage them.

If you are not comfortable wiring this yourself, the simplest paths are:

Duplicate a standard Alva test that is close to what you want and edit the description and scorecard (the publishing workflow is already wired in)
Skip the automated test score and rely on the AI code review scorecard alone

Step 6 – Test it yourself

Before sending the test to real candidates, send it to yourself or a colleague as a dry run. This catches the most common issues:

Instructions that are clear to the test author but ambiguous to a fresh reader
Automated tests that fail on the boilerplate before any code has been written
Time expectations that are far off the actual effort
Scorecard criteria that are too vague for the AI to grade consistently

If you created the test from scratch, it’s especially worth dry-running it end-to-end before you send it out. If you duplicated an existing test, still dry-run it after any changes to the boilerplate, tests, or scorecard.

You can iterate on the test by clicking Edit on any section of the detail page. The GitHub repository can be updated at any time - changes apply to the next candidate who starts the test.

Any Questions?

Use the chat in the bottom right corner to connect with a member of our support team.

Creating your own Coding Test