# Test Cases

Write test cases as natural language instructions that AI agents execute autonomously. No test runner needed — just tell your agent to run the tests.

## Writing Tests

Create `.rnatest.js` (or `.ts`, `.tsx`, `.jsx`) files anywhere in your project:

```js
const { describe, it, beforeEach } = require('react-native-agentkit/test');

module.exports = describe('Login Flow', () => {

  beforeEach(`
    Make sure we are on the login screen
  `);

  it('should login with valid credentials', `
    Clear the email input and type "user@test.com"
    Clear the password input and type "password123"
    Tap the submit button
    The Home screen should appear with a welcome message
  `);

  it('should show error for invalid credentials', `
    Type "wrong@test.com" into the email input
    Type "badpass" into the password input
    Tap submit
    An error message should be visible
    We should still be on the login screen
  `);

});
```

### How to Write Instructions

Write each test step exactly as you'd describe it to an AI assistant:

- **Actions**: "Tap the submit button", "Type 'hello' into the search input", "Scroll down on the main list", "Toggle dark mode on"
- **Assertions**: "The home screen should appear", "The cart badge should show '3'", "The error message should be visible"
- **Navigation**: "Navigate to the Settings tab", "Go back to the previous screen"
- **Waiting**: "Wait for the loading spinner to disappear"

Each line is a separate instruction. Be descriptive — the AI agent uses the screen state to figure out which elements match your description.

### Available DSL Functions

| Function | Purpose | Required |
| --- | --- | --- |
| `describe(name, fn)` | Group tests into a suite | Yes |
| `it(name, instructions)` | Define a single test case | Yes |
| `test(name, instructions)` | Alias for `it` | — |
| `beforeAll(instructions)` | Run once before all tests in this suite | No |
| `afterAll(instructions)` | Run once after all tests in this suite | No |
| `beforeEach(instructions)` | Run before each test | No |
| `afterEach(instructions)` | Run after each test | No |

### Nested Suites

Organize larger test suites with nested `describe` blocks:

```js
const { describe, it, beforeAll, beforeEach } = require('react-native-agentkit/test');

module.exports = describe('My App', () => {

  beforeAll(`
    Launch the app and wait for it to fully load
  `);

  describe('Authentication', () => {
    it('should show login screen on first launch', `
      The login screen should be visible
      Email and password inputs should be present
    `);

    it('should login and show dashboard', `
      Enter valid credentials and tap login
      The dashboard screen should appear
    `);
  });

  describe('Settings', () => {
    beforeEach(`Navigate to the Settings tab`);

    it('should toggle notifications', `
      Find the notifications switch
      Toggle it off
      It should now be unchecked
      Toggle it back on
      It should now be checked
    `);
  });

});
```

## Running Tests

Tell your AI agent:

> "I have test cases in the project. Go run them."

Or more specifically:

> "Run the login tests in `__tests__/login.rnatest.js`"

The agent will:
1. Search for `.rnatest.*` files in your project
2. Read each test file to understand the test structure
3. Execute each test by translating natural language instructions into AgentKit commands
4. Report pass/fail results for each test

### Example Output

```
Test Results: Login Flow
  ✅ should login with valid credentials
  ❌ should show error for invalid credentials
     Step failed: "An error message should be visible"
     Reason: No element matching "error" found on screen

2 tests: 1 passed, 1 failed
```

## Best Practices

1. **Be descriptive** — "Tap the blue Submit button at the bottom" is better than "Tap submit"
2. **One action per line** — Makes it easier for the agent to execute step by step
3. **Use testIDs** — Reference elements by their `testID` when possible for reliability
4. **Keep tests independent** — Each `it` block should work on its own (use `beforeEach` for setup)
5. **Test the happy path first** — Start with working flows before edge cases