> ## Documentation Index
> Fetch the complete documentation index at: https://e2e.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Základní koncepty

> Úkoly, aserce a lokátory a jak s nimi strukturovat a spouštět testy.

Test kombinuje tři typy kroků:

| Krok | API | Volání modelu |
| --- | --- | --- |
| [Úkol](#goals) | `agent.act` | Ano, pokud ho nepřehraje [cache](https://e2e.com/docs/cs/cache) |
| [Aserce](#assertions) | `agent.assert`, `agent.waitFor`, `agent.extract` | Ano |
| [Lokátor](#locators) | `screen` a `expect` | Ne |

S [vlastním executorem](https://e2e.com/docs/cs/executors) nepotřebují `act` ani `assert` žádný model.

```ts title="tests/todos.e2e.ts"

describe('todos', () => {
  test('the Done filter shows only completed todos', async ({ app, agent, screen }) => {
    await app.open('/todos');
    await agent.act('add todos "Buy milk" and "Walk the dog"');
    await agent.act('complete "Buy milk"');
    await agent.waitFor('"Buy milk" is completed and "Walk the dog" is open');

    await screen.getByRole('tab', 'Done').tap();

    await expect(screen.getByTestId('todo')).toHaveCount(1);
    await agent.assert('the only todo listed is "Buy milk"');
  });
});
```

Každý test ověřuje jedno chování ve třech blocích: připrav výchozí stav,
proveď testované chování a pak ověř výsledek.

Na každé volání agenta, volání `screen` i `expect.poll` čekej pomocí await. Pokud test
skončí, zatímco krok ještě běží, selže s chybou `STEP_NOT_AWAITED`.

## Úkoly

`agent.act` přijme jeden úkol a provede akce, které k němu vedou. Vrátí se,
když je úkol splněný, a vyhodí výjimku, když úkol selže.

```ts
await agent.act('complete checkout with the test card');
await agent.act('invite {email} as an editor', { params: { email: 'ada@example.test' } });
```

Každý úkol drž atomický: jeden výsledek, který potvrdí jedna kontrola. Když
dvě části pokynu vedou každá ke stavu, který stojí za ověření, jsou to dva
úkoly. Test může mít úkolů mnoho.

```ts title="Bad: three goals in one call, no check between them"
await agent.act('open the Pro plan, set the seats to {seats}, and check out', {
  params: { seats: 3 },
});
```

```ts title="Good: one atomic goal per call, arrange, act, assert"
test('checks out the Pro plan', async ({ app, agent, screen }) => {
  await app.open('/plans');
  await agent.act('open the Pro plan');
  await agent.act('set the seats to {seats}', { params: { seats: 3 } });
  await agent.waitFor('the cart shows the Pro plan with 3 seats');

  await agent.act('check out');

  await expect(screen.getByText('Order confirmed')).toBeVisible();
});
```

Nejdřív přijdou přípravné úkoly a skončí čekáním na stav, ke kterému vedou.
Pak následuje testovaný úkol. Aserce na jeho výsledek jsou až na konci.
Případné selhání pak ukáže na úkol, který se rozbil. Každý úkol se přehrává
ze svého vlastního záznamu a má vlastní
[limity](https://e2e.com/docs/cs/reference/agent#budgets) na volání modelu a akce. Akce vedoucí
k jednomu výsledku nejsou úkoly: otevření obrazovky nebo nabídky s ovládacím
prvkem, posun k němu, zavření banneru nebo vyplnění polí jednoho formuláře.

- Pořadí úkolů určuješ ty. Akce volí agent.
- Test zakonči voláním `expect` na výsledek. [Replay cache](https://e2e.com/docs/cs/cache)
  uloží úkol až poté, co projde některá z dalších kontrol nebo čekání.
- Používej slova, která jsou na obrazovce.
- Testovací data předávej v `params`. Heslo předej jako `Secret`. Model
  nikdy nedostane jeho hodnotu jako text. Viz [Autentizace](https://e2e.com/docs/cs/authentication).
- Pro hodnotu, která se mění při každém běhu, použij `unique()`, aby
  [cache mohla krok přehrát](https://e2e.com/docs/cs/cache#what-must-match):

```ts

const email = `ada+${Date.now()}@example.test`;
await agent.act('sign up with email {email}', { params: { email: unique(email) } });
```

`act` si snímky obrazovky vyžádá, když je potřebuje. Na některých enginech
umí klepat a psát na konkrétní body v obrázku.

Když úkol selže, přečti si report a zformuluj pokyn konkrétněji. Slova, která
používá mnoho úkolů, dej do [`context`](https://e2e.com/docs/cs/agents) agenta.

## Aserce

Aserce posuzuje obrazovku. Model vidí tvrzení, redigovaný textový snímek
aktuální obrazovky, její umístění a kontext agenta. Nevidí předchozí kroky
ani shrnutí z `act`.

- `agent.assert` posoudí obrazovku v daném okamžiku. Nepravdivé tvrzení selže
  s `ASSERTION_FAILED`. Když důkazy nestačí, selže s
  `ASSERTION_INCONCLUSIVE`.
- `agent.waitFor` čeká, až podmínka začne platit. Model volá jen tehdy, když
  se změní obrazovka nebo její umístění.
- `agent.extract` načte data z obrazovky do typu
  [Standard Schema](https://standardschema.dev), například ze Zodu.

```ts

await agent.assert('the dashboard shows a trial badge');
await agent.waitFor('a download link appears', { timeout: 120_000 });
await agent.assert('the chart trends upward', { vision: true });

const data = await agent.extract('every todo title', {
  schema: z.object({ titles: z.array(z.string()) }),
});
expect(data.titles).toContain('Buy milk');
```

U textu, který napsal model, ověřuj význam, ne celou větu. Když záleží na
přesném znění, použij [lokátor](#locators).

Pro vizuální kontrolu, třeba grafu nebo rozvržení, přidej `vision: true`.
Pokud má aserce posoudit jen snímek obrazovky, použij `vision: 'only'`.
Obrázky zvyšují počet vstupních tokenů. Viz [referenci agenta](https://e2e.com/docs/cs/reference/agent#vision).

## Lokátory

Lokátor najde známý ovládací prvek bez volání modelu. Použij ho, když znáš
přesnou akci nebo přesnou hodnotu.

```ts
// Role and name first, label second, test ID last.
await screen.getByRole('button', 'Sign in').tap();
await screen.getByLabel('Email').fill('ada@example.test');

// Scope into a row.
const row = screen.getByRole('listitem').filter({ hasText: 'Design review' });
await row.getByRole('button', 'Archive').tap();

// Gestures and coordinates.
await screen.swipe({ direction: 'up' });
await screen.getByRole('image', 'Seat map').tap({ position: { x: 120, y: 48 } });

// Assertions retry until they pass or time out.
await expect(screen.getByRole('status')).toHaveText('2 remaining');
```

- Akce, čtení nebo aserce na jeden uzel selže, když dotaz najde víc než
  jeden uzel. K zúžení na jeden uzel použij `.filter()`, `.first()` nebo
  `.nth()`.
- Přímé čtení, například `textContent()`, počká na shodu, pak přečte hodnotu
  jednou; čtení hodnoty se už neopakuje.

Viz [referenci screen](https://e2e.com/docs/cs/reference/screen) a
[referenci expect](https://e2e.com/docs/cs/reference/expect#locator-matchers). Routy, cookies,
dialogy a stahování popisuje [Práce s prohlížečem](https://e2e.com/docs/cs/browser).

## Uspořádání testů

```ts

describe('billing', { tags: ['billing'] }, () => {
  beforeEach(async ({ app }) => { await app.open('/billing'); });

  test('upgrades', { retries: 2, timeout: 60_000 }, async ({ agent }) => {
    await agent.act('upgrade to Pro');
  });
});

test('needs two organizations', async ({ app }) => {
  test.skip((await countOrganizations()) < 2, 'nothing to switch to');
  await app.open('/organizations');
});
```

- Každý test běží ve vlastním pokusu. Začni ho co nejblíž obrazovce, kterou
  ověřuje, aby každý běh přeskočil kliknutí, která k ní vedou. Jeho data
  vytvoř ve fixtures nebo hoocích. V prohlížeči obnov [uloženou relaci](https://e2e.com/docs/cs/authentication)
  a otevři obrazovku přes její cestu. Na zařízení otevři
  [deep link](https://e2e.com/docs/cs/mobile#the-device-fixture).
- `test.skip(condition, reason)` zastaví test jako `skipped`, když
  podmínka platí.
- Pro tok napříč mnoha testy nastav na skupině `{ serial: true }`. Testy
  pak běží postupně na jednom workeru a opakují se společně.
- Pro přípravu a úklid použij `test.extend`. Viz
  [Psaní fixtures](https://e2e.com/docs/cs/fixtures).
- Importuj `test` z `@e2e-dev/web` nebo `@e2e-dev/mobile`, aby měla fixture
  `browser` nebo `device` správný typ.

Všechny možnosti ukazuje [reference test](https://e2e.com/docs/cs/reference/test).

## Spuštění jednoho testu

<CodeGroup>
```bash npm
npx e2e run tests/signup.e2e.ts:12   # the test at line 12
npx e2e run --grep checkout          # tests with a matching title
npx e2e run --target web             # one target
```

```bash pnpm
pnpm exec e2e run tests/signup.e2e.ts:12   # the test at line 12
pnpm exec e2e run --grep checkout          # tests with a matching title
pnpm exec e2e run --target web             # one target
```

```bash bun
bunx e2e run tests/signup.e2e.ts:12   # the test at line 12
bunx e2e run --grep checkout          # tests with a matching title
bunx e2e run --target web             # one target
```
</CodeGroup>

Všechny přepínače ukazuje [reference CLI](https://e2e.com/docs/cs/reference/cli#e2e-run).

## Co dál

<CardGroup cols={2}>
  <Card title="Cache" icon="box-archive" href="/cache">
    Přehrávej úspěšné úkoly bez volání modelu.
  </Card>
  <Card title="Jak fungují agentní kroky" icon="list-check" href="/agent-steps">
    Verdikty, návratové kódy a co model vidí.
  </Card>
</CardGroup>
