> For the complete documentation index, see [llms.txt](https://shepherd-1.gitbook.io/shepherd/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shepherd-1.gitbook.io/shepherd/how-to-use/run-test.md).

# Run Test

Start a New Project

Login with Github or Google. Then click the `+` button in the 'My Repositories' section to begin a new session.

<figure><img src="/files/FmFIRJoEkx1tjxBBxS5K" alt=""><figcaption></figcaption></figure>

***

### Upload Materials

* Drag / Upload your [contract assets .zip file](/shepherd/how-to-use/setup.md#required-zip-structure)
* Enter your [Tunnel URL](/shepherd/how-to-use/setup.md#step-4-creating-your-tunnel-url)
* Enter your Github repo URL

<figure><img src="/files/9r7tcKFguGNWTycXgPyy" alt=""><figcaption></figcaption></figure>

***

### Project Description

For now, paste your GitHub repo  URL into the Project description field. You can later replace this with a more detailed summary of your project.

### White Paper & References

<mark style="color:red;">**Leave the White paper and References fields blank for now.**</mark> These are optional metadata fields you can populate later if needed.

<figure><img src="/files/qbCUtXL8keyRRnlOGnJp" alt=""><figcaption></figcaption></figure>

***

### Select Environment

Set Environment to <mark style="color:red;">`Local`</mark> and click the <mark style="color:red;">`Next`</mark> button.

***

### Wait for Initialization

Shepherd will now initialize and chunk your contract materials. Wait for this process to complete before proceeding. This may take a few moments depending on the size of your codebase.

***

### Enter Your Hypothesis

In the hypothesis input field, describe the specific attack scenario you want Shepherd to test.

{% hint style="info" %}
The more detailed your hypothesis, the more accurate Shepherd's analysis will be.
{% endhint %}

<figure><img src="/files/WOjDJ6QpJGh4bbgAzSqf" alt=""><figcaption></figcaption></figure>

Include:

* Attacker capabilities - What can the attacker do? (call functions, send transactions, deploy contracts)
* Initial conditions - Starting state, balances, permissions
* Attack vector - The specific vulnerability or exploit path to test
* Expected outcome - What should happen if the vulnerability exists

Learn more [here](/shepherd/additional-info/best-practices-and-tips.md#writing-effective-hypotheses)

***

### Enter Contract Names & Function

To best support our AI model, we require as much context as you can give. Please provide to your best ability the exact contract names and functions as it appears in your repo.&#x20;

{% hint style="info" %}
Contract and function names are case-sensitive.
{% endhint %}

<figure><img src="/files/oGuk0kSarMF7IYqrmFEH" alt=""><figcaption></figcaption></figure>

If our AI successfully reads the chunk of code you have pointed to, it will look like this:&#x20;

<figure><img src="/files/hGAJmHGBZWazYjt8s7dM" alt=""><figcaption></figcaption></figure>

After it successfully read the chunk of code, you may proceed to add more. However, please beware of the token limit.&#x20;

If it did not successfully read the chunk of code you have pointed to, it will look like this:

<figure><img src="/files/mQjG7C3tAjoR9mBkjL41" alt=""><figcaption></figcaption></figure>

If you wish to retry / add more, please enter  <mark style="color:red;">`Y`</mark>&#x20;

{% hint style="warning" %}
As soon as you enter 'N', the AI will begin executing the attack.
{% endhint %}

***

### Watch the Exploit Unfold

Then application will display real-time progress as our system works:

You'll see:

* Reconnaissance and analysis messages
* Candidate exploit paths being explored
* Validation steps and agent-logic flows
* Execution traces and logs
* Node-based visualization of the attack sequence

The interface will show a timeline of how the exploit is validated.

***

### Rerun or End Session

When the analysis completes, you'll be prompted: "Do you want to rerun with another hypothesis?"

Select <mark style="color:red;">`Y`</mark> to:

* Test a new hypothesis in the same session
* Keep existing context and chunked materials loaded
* Explore different attack vectors on the same contracts

Select <mark style="color:red;">`N`</mark> to:

* End the current session
* Clear agent state
* Free up resources