test-cases.md

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:

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:

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