Initial commit

commands/steel-test.md

@@ -0,0 +1,164 @@
+---
+description: Help write and run tests for Steel automation projects
+---
+
+# Steel Testing Assistant
+
+Help the user write effective tests for Steel automation using standard testing frameworks.
+
+## Test Approaches
+
+### Unit Tests
+Test individual functions and utilities:
+```typescript
+// tests/utils.test.ts
+import { generateSelector } from '../src/utils';
+
+describe('generateSelector', () => {
+  it('should create optimal selector', () => {
+    const element = { id: 'submit', class: 'btn' };
+    expect(generateSelector(element)).toBe('#submit');
+  });
+});
+```
+
+### Integration Tests
+Test Steel session management:
+```typescript
+// tests/session.test.ts
+import { Steel } from 'steel-sdk';
+
+describe('Steel Session', () => {
+  let client: Steel;
+  
+  beforeAll(() => {
+    client = new Steel({ steelAPIKey: process.env.STEEL_API_KEY! });
+  });
+
+  it('should create session', async () => {
+    const session = await client.sessions.create();
+    expect(session.id).toBeDefined();
+    await client.sessions.release(session.id);
+  });
+
+  it('should connect with Playwright', async () => {
+    const session = await client.sessions.create();
+    const browser = await chromium.connectOverCDP(
+      `${session.websocketUrl}?apiKey=${process.env.STEEL_API_KEY}`
+    );
+    
+    expect(browser.contexts().length).toBeGreaterThan(0);
+    
+    await browser.close();
+    await client.sessions.release(session.id);
+  });
+});
+```
+
+### E2E Tests
+Test complete automation workflows:
+```typescript
+// tests/e2e/scraping.test.ts
+describe('Product Scraping', () => {
+  it('should scrape product data', async () => {
+    const client = new Steel({ steelAPIKey: process.env.STEEL_API_KEY! });
+    const session = await client.sessions.create();
+    
+    const browser = await chromium.connectOverCDP(
+      `${session.websocketUrl}?apiKey=${process.env.STEEL_API_KEY}`
+    );
+    const page = browser.contexts()[0].pages()[0];
+    
+    await page.goto('https://example.com/products');
+    const title = await page.locator('h1').first().textContent();
+    
+    expect(title).toBeTruthy();
+    
+    await browser.close();
+    await client.sessions.release(session.id);
+  });
+});
+```
+
+## Test Best Practices
+
+1. **Always Clean Up Sessions**:
+   ```typescript
+   afterEach(async () => {
+     if (session) {
+       await client.sessions.release(session.id);
+     }
+   });
+   ```
+
+2. **Use Longer Timeouts**: Steel automation can take time
+   ```typescript
+   jest.setTimeout(30000); // 30 seconds
+   ```
+
+3. **Handle Errors Gracefully**:
+   ```typescript
+   try {
+     await page.goto('https://example.com');
+   } catch (error) {
+     console.log('Session viewer:', session.sessionViewerUrl);
+     throw error;
+   }
+   ```
+
+4. **Test with Live Sessions**: Use `sessionViewerUrl` to debug test failures
+
+5. **Mock External Services**: Don't test third-party APIs, focus on your Steel code
+
+## Common Test Patterns
+
+### Session Creation Test
+```typescript
+it('should create session within timeout', async () => {
+  const start = Date.now();
+  const session = await client.sessions.create();
+  const duration = Date.now() - start;
+  
+  expect(duration).toBeLessThan(5000); // Should be fast
+  await client.sessions.release(session.id);
+});
+```
+
+### Selector Reliability Test
+```typescript
+it('should find element with selector', async () => {
+  const session = await client.sessions.create();
+  const browser = await chromium.connectOverCDP(/*...*/);
+  const page = browser.contexts()[0].pages()[0];
+  
+  await page.goto('https://example.com');
+  const element = await page.waitForSelector('[data-testid="target"]');
+  
+  expect(element).toBeTruthy();
+});
+```
+
+### Data Extraction Test
+```typescript
+it('should extract correct data', async () => {
+  // Setup session and page
+  const data = await page.evaluate(() => {
+    return {
+      title: document.querySelector('h1')?.textContent,
+      price: document.querySelector('.price')?.textContent
+    };
+  });
+  
+  expect(data.title).toBeTruthy();
+  expect(data.price).toMatch(/\$\d+/);
+});
+```
+
+## Running Tests
+
+Guide users to use standard test runners:
+- Jest: `npm test` or `jest`
+- Vitest: `vitest run`
+- Pytest: `pytest tests/`
+
+Always provide working test examples they can copy and modify.